Pastebin launched a little side project called VERYVIRAL.com, check it out ;-) Want more features on Pastebin? Sign Up, it's FREE!
Guest

aegis_validator.txt

By: a guest on Jul 11th, 2011  |  syntax: None  |  size: 17.66 KB  |  views: 945  |  expires: Never
download  |  raw  |  embed  |  report abuse  |  print
Text below is selected. Please press Ctrl+C to copy to your clipboard. (⌘+C on Mac)
  1.  
  2. Aegis Validator kernel module
  3. -----------------------------
  4.  
  5. Markku Kylänpää <ext-markku.kylanpaa@nokia.com>
  6. 12.11. 2010
  7.  
  8.  
  9. Introduction
  10. ============
  11.  
  12. Aegis Validator is a kernel-based integrity protection framework.
  13. Userspace applications, shared libraries, certain data files and kernel
  14. modules are verified during loading. SHA1 hash of the object to be loaded
  15. is calculated in Linux Security Module (LSM) hook function and the result
  16. is compared to a stored reference value. The list of the reference values
  17. is loaded into kernel during boot. Positive verification results are cached
  18. (and indexed by inode number). An object is verified only once after each
  19. boot and an attempt to write to a cached entry removes the entry from the
  20. cache forcing revalidation.
  21.  
  22. Aegis Platform Security Framework
  23. ==================================
  24.  
  25. Aegis Validator is a part of Aegis Platform Security framework, which
  26. was published in October 2009 Maemo Summit in Amsterdam. Brief description
  27. about concepts is available in:
  28.  
  29.   http://www.slideshare.net/peterschneider/maemo-6-platform-security
  30.  
  31. Aegis Validator relies on OMAP Secure Environment services provided
  32. by security driver component (Documentation/arm/OMAP/omap_sec.txt)
  33. and Aegis Runtime Policy Framework access control mechanism. SHA1 hash
  34. calculation is utilizing OMAP SHA1 accelerator. Aegis Validator is a
  35. built-in kernel module and there is a securityfs interface to control
  36. the module and also to update new reference hash values. Securityfs is
  37. a pseudo-filesystem (like sysfs) and is commonly used by security
  38. modules to allow the kernel module to interact with userspace.
  39.  
  40. Userspace Debian dpkg installer has been modified to update the reference
  41. hash list via securityfs. The initial list is generated and signed by
  42. firmware image generation system. Kernel invokes statically linked userspce
  43. helper application that loads and verifies the reference hashlist file and
  44. translates (pathname,sha1) values into (inode, sha1) values. Bootloader
  45. should pass the SHA1 hash of the userspace helper application to kernel
  46. as command-line parameter. The value is used to authorize userspapce helper
  47. application. When the installer updates the reference hash list it is using
  48. OMAP Secure Environment services to create device specific HMAC signature.
  49.  
  50. DigSig
  51. ======
  52.  
  53. The original code is based on DigSig open source software (available in
  54. http://disec.sourceforge.net/). DigSig relied solely on signed binaries and
  55. tried to sign all ELF executables by adding special signature section to
  56. executable files. DigSig project added RSA code from gnupg project to Linux
  57. kernel to do the verification. This feature is removed from Aegis Validator.
  58. It is using the stored list of reference hashes for verification.
  59.  
  60. The original DigSig is meant to be used as Tripwire-like tool for system
  61. administrator to verify integrity of installed binaries. System administrators
  62. can RSA sign ELF applications and libraries and execution of non-signed ELF
  63. code can be prevented. Verification result is cached. Aegis Validator is
  64. using LSM hooks to catch executable code loading. The original DigSig was
  65. implemented as a loadable kernel module and verification public key is
  66. inserted using init script via sysfs kernel interface. Aegis Validator is
  67. mainly used to protect the system against offline tampering attempts and
  68. malware.
  69.  
  70. Code structure and interfaces
  71. =============================
  72.  
  73. All code is in its own subtree (security/aegis/validator) except small
  74. LSM hook addon that was added for kernel module verification. Most of the
  75. code is generic. OMAP Security Environment specific code is in separate
  76. module (platsec.c). There are dependencies to kernel-based Aegis Runtime
  77. Policy Framework. Runtime Policy Framework source origin check is
  78. triggered by Aegis Validator. Validator is also using Runtime Policy
  79. Framework services for access checking. This functionality is separated
  80. in sidcheck.c module.
  81.  
  82. Securityfs configuration interface is in /sys/kernel/security/validator. There
  83. are entries to enable and disable functionality and also to insert new
  84. reference hashes to the kernel. Cache and reference hash list content can
  85. also be dumped for debugging purpose. Validator securityfs entries are:
  86.  
  87.   hashlist - load new reference hash entries (write), print hashlist (read)
  88.   cache    - print verification cache (read)
  89.   flush    - flush verification cache (write)
  90.   enabled  - enable validator functionality (write), show value (read)
  91.   enforce  - set validator to enforcing mode (write), show value (read)
  92.   modlist  - authorize kernel modules (write), show value (read)
  93.  
  94. Both enable and enforce allow integrity protection features to be enabled
  95. and enforced separately. The value is treated as a bit mask with fields
  96. (enforce control includes bits 0-3):
  97.  
  98.   bit 0: enable/enforce SHA1 hash calculation
  99.   bit 1: enable/enforce source origin checking
  100.   bit 2: enable/enforce data file checking
  101.   bit 3: enable/enforce file attribute checking
  102.   bit 4: invoke userspace helper to load more hashes
  103.   bit 5: check only entries that are listed in the reference hash list
  104.   bit 6: if set require the client to own "tcb" Runtime Policy Framework
  105.          credential to allow adding new reference hashes.
  106.   bit 7: if set then only allow loading of new hashes but no mode changes
  107.   bit 8: if set then allow only whitelisted kernel modules
  108.  
  109. The following LSM hooks are used to interface with the kernel:
  110.  
  111.   .netlink_send
  112.   .file_mmap
  113.   .file_free_security
  114.   .dentry_open
  115.   .inode_permission
  116.   .inode_unlink
  117.   .inode_create
  118.   .inode_rename
  119.   .bprm_check_security
  120.   .inode_free_security
  121.   .sb_free_security
  122.  
  123. Reference hashlist values are loaded into kernel by invoking userspace
  124. helper application from kernel. The helper application is reading, verifying
  125. and parsing the reference hashlist file and creates the list of records to
  126. be sent into kernel via securityfs. The list consist of records having SHA1
  127. hash, inode number, mount volume identifier and source origin identifier of
  128. the component. Software installer is also using securityfs interface to add
  129. new reference hashes into kernel.
  130.  
  131. There is also netlink-based validation error notification mechanism to
  132. userspace. If Validator blocks loading then this error with some context
  133. information is also logged to netlink multicast socket (25).
  134.  
  135. Features
  136. ========
  137.  
  138. SHA1 integrity check for executables
  139. Enable/Enforce: BIT(0) "HASH_CHECK_BIT"
  140.  
  141. This is basic functionality of Aegis Validator. Applications and shared
  142. libraries are verified. The check is triggered by LSM hooks .file_mmap
  143. and .bprm_check_security. The object is read, SHA1 hash is calculated and
  144. positive verification result is cached. The object is only verified once
  145. in each boot session and later invocations only lookup verification result
  146. from cache.
  147.  
  148. Source origin checking
  149. Enable/Enforce: BIT(1) SID_CHECK_BIT
  150.  
  151. All executable objects are bound to some source origin. The origin is
  152. typically a repository which contains the Debian package having the
  153. executable object. Source origins can have different trust level, which
  154. means that applications from certain repository are allowed to grant more
  155. credentials like POSIX capabilities and resource tokens (concept of Aegis
  156. Runtime Policy Framework). When an object is loaded to execution Aegis
  157. Vaölidator is calling one Aegis Runtime Policy Framework kernel function
  158. to verify that the current process is allowed to load the object.
  159.  
  160. Data file checking
  161. Enable/Enforce: BIT(2) DATA_CHECK_BIT
  162.  
  163. There is also limited support to protect data files. Certain directories
  164. can be specified in the reference hash list to be protected directories
  165. and files in those directories should have matching reference hash. The
  166. hash value is checked in file open operation. If the hash does not match
  167. opening of the file is prevented. It is also possible to declare some
  168. files in the protected to be dynamic, which means that those files are
  169. not verified.
  170.  
  171. Use cases for data file protection are:
  172.   * Protection of upstart configuration files in /etc/init
  173.   * Protection of kernel modules in /lib/modules/*
  174.   * Protection of Perl libraries
  175.  
  176. File attribute checking
  177. Enable/Enforce: BIT(3) ATTRIB_CHECK_BIT
  178.  
  179. Aegis Validator also records file attributes (user, group, mode) and can
  180. verify that file attributes are still the same.
  181.  
  182. Request to load more hashes
  183. Enable: BIT(4) HASH_REQ_BIT
  184.  
  185. The hash list of the root filesystem is loaded during boot. If other
  186. volumes are mounted and something is executed from the mounted volume
  187. then userspace helper application is invoked to load new reference hashes
  188. to authorize execution of executables.
  189.  
  190. Checking only listed files
  191. Enable: BIT(5) LISTED_ONLY_BIT
  192.  
  193. It is also possible to limit reference hash checking to only those files
  194. that are listed in the reference hashlist. If source origin checking is
  195. configured then unlisted executables are treated to come from unknown
  196. source origin.
  197.  
  198. Use "tcb" resource token to protect hash loading
  199. Enable: BIT(6) SECFS_BIT
  200.  
  201. Userspace helper can configure Validator to require "tcb" resource
  202. token for clients loading new reference hashes.
  203.  
  204. Sealing operation mode
  205. Enable: BIT(7) SEAL_BIT
  206.  
  207. If the seal bit is set during configuration then further configuration
  208. changes (modifications to enable and enforce settings) are not allowed.
  209. It is still possible to load new reference hashes, but loading requires
  210. possession of tcb resource token.
  211.  
  212. Kernel module whitelist mode
  213. Enable BIT(8) KMOD_BIT
  214.  
  215. SHA1 hashes of authorized kernel modules can be loaded via modlist
  216. securityfs entry. If this bit is set then all kernel modules are verified
  217. when the module is loaded and only those that are in the whitelist are
  218. accepted.
  219.  
  220. Hash input message format
  221. =========================
  222.  
  223. Securityfs entry /sys/kernel/security/validator/hashlist is used to load
  224. reference hashes to Aegis Validator. This is done either during startup
  225. or afterwards if the installer installs new software. There can be four
  226. different messages. The message can be:
  227.  
  228. 1. Old format reference hash message (a)
  229.  
  230. This message type is still supported because of backwards compatibility.
  231. When all userspace components and other tools have been updated this
  232. message can be deprecated. This message has been replaced by the new
  233. format message, which also includes file metadata fields and source
  234. identifier is numeric instead of string.
  235.  
  236. 2. New format reference hash message (s|t)
  237.  
  238. This message type adds file metadata fields and source identifier is also
  239. given as numeric identifier instead of textual string value. Exactly same
  240. format is used for executables (s) and static data (t). However those
  241. objects are still separately labeled in the hashlist.
  242.  
  243. 3. Dynamic file entry (x)
  244.  
  245. Integrity protected directories can also contain configuration files
  246. whose value can change. These files should be declared as dynamic. Those
  247. files are not integrity protected but writing can be controlled and
  248. file attributes can be verified. Note that this message does not include
  249. any hash value, because integrity of dynamic files is not verified.
  250.  
  251. 4. Immutable directory entry (d)
  252.  
  253. This message type specifies immutable directories. Also this message
  254. does not contain reference hash value. There are two additional fields
  255. that specify resource token and capability mask requirements for writing
  256. to the directory. If those values are zero writing is not controlled.
  257.  
  258. 5. Protected directory entry (p)
  259.  
  260. This message type specifies directories that should be protected against
  261. unauthorized renaming, removal and the use as a mount poinyt. Also this
  262. message does not contain reference hash value. There are two additional
  263. fields that specify resource token and capability mask requirements for
  264. writing to the directory. If those values are zero writing is not
  265. controlled.
  266.  
  267. Field     Description                          Length
  268. -----     -----------                          ------
  269. a         = Code byte for old hash format       (1)
  270. SHA1      = 20 bytes of SHA1 hash               (20)
  271. blank     = One blank character                 (1)
  272. devid     = Device id as integer string         (>=1)
  273. blank     = One blank character                 (1)
  274. ino       = inode number as integer string      (>=1)
  275. blank     = One blank character                 (1)
  276. sid       = Source identifier string            (>=1)
  277. null      = '\0' character                      (1)
  278. newline   = '\n' character                      (1)
  279.  
  280. Field     Description                          Length
  281. -----     -----------                          ------
  282. s|t       = Code byte for new hash format       (1)
  283. SHA1      = 20 bytes of SHA1 hash               (20)
  284. blank     = One blank character                 (1)
  285. devid     = Device id as integer string         (>=1)
  286. blank     = One blank character                 (1)
  287. ino       = inode number as integer string      (>=1)
  288. blank     = One blank character                 (1)
  289. uid       = uid number as integer string        (>=1)
  290. blank     = One blank character                 (1)
  291. gid       = gid number as integer string        (>=1)
  292. blank     = One blank character                 (1)
  293. mode      = filemode number integer string      (>=1)
  294. blank     = One blank character                 (1)
  295. sid       = Sid identifier as integer string    (>=1)
  296. blank     = One blank character                 (1)
  297. crednum   = Number of credtype/credvalue pairs  (>=1)
  298.  
  299. Multiple credtype/credvalue pairs depending on crednum value
  300. If crednum was 0 then there won't be these fields
  301.  
  302. blank     = One blank character                 (1)
  303. id        = Policy identifier as integer string (>=1)
  304. blank     = One blank character                 (1)
  305. credtype  = Credential type as integer string   (>=1)
  306. blank     = One blank character                 (1)
  307. credvalue = Credential value as integer string  (>=1)
  308. null      = '\0' character                      (1)
  309. newline   = '\n' character                      (1)
  310.  
  311. Field     Description                          Length
  312. -----     -----------                          ------
  313. x         = Code byte for dynamic files         (1)
  314. devid     = Device id as integer string         (>=1)
  315. blank     = One blank character                 (1)
  316. ino       = inode number as integer string      (>=1)
  317. blank     = One blank character                 (1)
  318. uid       = uid number as integer string        (>=1)
  319. blank     = One blank character                 (1)
  320. gid       = gid number as integer string        (>=1)
  321. blank     = One blank character                 (1)
  322. mode      = filemode number integer string      (>=1)
  323. blank     = One blank character                 (1)
  324. sid       = Sid identifier as integer string    (>=1)
  325. blank     = One blank character                 (1)
  326.  
  327. Multiple credtype/credvalue pairs depending on crednum value
  328. If crednum was 0 then there won't be these fields
  329.  
  330. blank     = One blank character                 (1)
  331. id        = Policy identifier as integer string (>=1)
  332. blank     = One blank character                 (1)
  333. credtype  = Credential type as integer string   (>=1)
  334. blank     = One blank character                 (1)
  335. credvalue = Credential value as integer string  (>=1)
  336.  
  337. null      = '\0' character                      (1)
  338. newline   = '\n' character                      (1)
  339.  
  340. Field     Description                          Length
  341. -----     -----------                          ------
  342. d|p       = Code byte for directory entry       (1)
  343. devid     = Device id as integer string         (>=1)
  344. blank     = One blank character                 (1)
  345. ino       = inode number as integer string      (>=1)
  346. blank     = One blank character                 (1)
  347. uid       = uid number as integer string        (>=1)
  348. blank     = One blank character                 (1)
  349. gid       = gid number as integer string        (>=1)
  350. blank     = One blank character                 (1)
  351. mode      = filemode number integer string      (>=1)
  352. blank     = One blank character                 (1)
  353. sid       = Sid identifier as integer string    (>=1)
  354. blank     = One blank character                 (1)
  355.  
  356. Multiple credtype/credvalue pairs depending on crednum value
  357. If crednum was 0 then there won't be these fields
  358.  
  359. blank     = One blank character                 (1)
  360. id        = Policy identifier as integer string (>=1)
  361. blank     = One blank character                 (1)
  362. credtype  = Credential type as integer string   (>=1)
  363. blank     = One blank character                 (1)
  364. credvalue = Credential value as integer string  (>=1)
  365.  
  366. null      = '\0' character                      (1)
  367. newline   = '\n' character                      (1)
  368.  
  369. So the minimum length of the message should be at least 14 bytes.
  370. There is odd message termination with "\0\n". The change requires
  371. changes to userspace tools as well.
  372.  
  373. Potential future work
  374. =====================
  375.  
  376. Linux kernel version 2.6.30 introduced a new framework called Integrity
  377. Measurement Architecture (IMA). IMA framework partly overlaps with
  378. Aegis Validator as both are measuring loaded executables. However,
  379. IMA is just doing measurements and its purpose is to provide Trusted
  380. Platform Module (TPM) backed measurement agent inside Linux kernel,
  381. which can be used to generate signed replies (signed PCR registers +
  382. measurement log) to remote attestation requests. There is no local
  383. integrity enforcement in IMA, but there are plans to add such module
  384. called EVM.
  385.  
  386. IMA code could be extended to provide an interface for integrity
  387. enforcement modules. This should be proposed. If succesful then Aegis
  388. Validator measurement code can be dropped in favor of IMA measurement
  389. code. As LSM hooks are not in general stackable it also makes sense
  390. to minimize the use of LSM hooks if there is a need to run another
  391. framework that relies on LSM.