1What:		/sys/kernel/security/*/ima/policy
2Date:		May 2008
3Contact:	Mimi Zohar <zohar@us.ibm.com>
4Description:
5		The Trusted Computing Group(TCG) runtime Integrity
6		Measurement Architecture(IMA) maintains a list of hash
7		values of executables and other sensitive system files
8		loaded into the run-time of this system.  At runtime,
9		the policy can be constrained based on LSM specific data.
10		Policies are loaded into the securityfs file ima/policy
11		by opening the file, writing the rules one at a time and
12		then closing the file.  The new policy takes effect after
13		the file ima/policy is closed.
14
15		IMA appraisal, if configured, uses these file measurements
16		for local measurement appraisal.
17
18		::
19
20		  rule format: action [condition ...]
21
22		  action: measure | dont_measure | appraise | dont_appraise |
23			  audit | hash | dont_hash
24		  condition:= base | lsm  [option]
25			base:	[[func=] [mask=] [fsmagic=] [fsuuid=] [fsname=]
26				[uid=] [euid=] [gid=] [egid=]
27				[fowner=] [fgroup=]]
28			lsm:	[[subj_user=] [subj_role=] [subj_type=]
29				 [obj_user=] [obj_role=] [obj_type=]]
30			option:	[digest_type=] [template=] [permit_directio]
31				[appraise_type=] [appraise_flag=]
32				[appraise_algos=] [keyrings=]
33		  base:
34			func:= [BPRM_CHECK][MMAP_CHECK][CREDS_CHECK][FILE_CHECK][MODULE_CHECK]
35				[FIRMWARE_CHECK]
36				[KEXEC_KERNEL_CHECK] [KEXEC_INITRAMFS_CHECK]
37				[KEXEC_CMDLINE] [KEY_CHECK] [CRITICAL_DATA]
38				[SETXATTR_CHECK][MMAP_CHECK_REQPROT]
39			mask:= [[^]MAY_READ] [[^]MAY_WRITE] [[^]MAY_APPEND]
40			       [[^]MAY_EXEC]
41			fsmagic:= hex value
42			fsuuid:= file system UUID (e.g 8bcbe394-4f13-4144-be8e-5aa9ea2ce2f6)
43			uid:= decimal value
44			euid:= decimal value
45			gid:= decimal value
46			egid:= decimal value
47			fowner:= decimal value
48			fgroup:= decimal value
49		  lsm:  are LSM specific
50		  option:
51			appraise_type:= [imasig] | [imasig|modsig] | [sigv3]
52			    where 'imasig' is the original or the signature
53				format v2.
54			    where 'modsig' is an appended signature,
55			    where 'sigv3' is the signature format v3. (Currently
56				limited to fsverity digest based signatures
57				stored in security.ima xattr. Requires
58				specifying "digest_type=verity" first.)
59
60			appraise_flag:= [check_blacklist]
61			Currently, blacklist check is only for files signed with appended
62			signature.
63			digest_type:= verity
64			    Require fs-verity's file digest instead of the
65			    regular IMA file hash.
66			keyrings:= list of keyrings
67			(eg, .builtin_trusted_keys|.ima). Only valid
68			when action is "measure" and func is KEY_CHECK.
69			template:= name of a defined IMA template type
70			(eg, ima-ng). Only valid when action is "measure".
71			pcr:= decimal value
72			label:= [selinux]|[kernel_info]|[data_label]
73			data_label:= a unique string used for grouping and limiting critical data.
74			For example, "selinux" to measure critical data for SELinux.
75			appraise_algos:= comma-separated list of hash algorithms
76			For example, "sha256,sha512" to only accept to appraise
77			files where the security.ima xattr was hashed with one
78			of these two algorithms.
79
80		  default policy:
81			# PROC_SUPER_MAGIC
82			dont_measure fsmagic=0x9fa0
83			dont_appraise fsmagic=0x9fa0
84			# SYSFS_MAGIC
85			dont_measure fsmagic=0x62656572
86			dont_appraise fsmagic=0x62656572
87			# DEBUGFS_MAGIC
88			dont_measure fsmagic=0x64626720
89			dont_appraise fsmagic=0x64626720
90			# TMPFS_MAGIC
91			dont_measure fsmagic=0x01021994
92			dont_appraise fsmagic=0x01021994
93			# RAMFS_MAGIC
94			dont_appraise fsmagic=0x858458f6
95			# DEVPTS_SUPER_MAGIC
96			dont_measure fsmagic=0x1cd1
97			dont_appraise fsmagic=0x1cd1
98			# BINFMTFS_MAGIC
99			dont_measure fsmagic=0x42494e4d
100			dont_appraise fsmagic=0x42494e4d
101			# SECURITYFS_MAGIC
102			dont_measure fsmagic=0x73636673
103			dont_appraise fsmagic=0x73636673
104			# SELINUX_MAGIC
105			dont_measure fsmagic=0xf97cff8c
106			dont_appraise fsmagic=0xf97cff8c
107			# CGROUP_SUPER_MAGIC
108			dont_measure fsmagic=0x27e0eb
109			dont_appraise fsmagic=0x27e0eb
110			# NSFS_MAGIC
111			dont_measure fsmagic=0x6e736673
112			dont_appraise fsmagic=0x6e736673
113
114			measure func=BPRM_CHECK
115			measure func=FILE_MMAP mask=MAY_EXEC
116			measure func=FILE_CHECK mask=MAY_READ uid=0
117			measure func=MODULE_CHECK
118			measure func=FIRMWARE_CHECK
119			appraise fowner=0
120
121		The default policy measures all executables in bprm_check,
122		all files mmapped executable in file_mmap, and all files
123		open for read by root in do_filp_open.  The default appraisal
124		policy appraises all files owned by root.
125
126		Examples of LSM specific definitions:
127
128		SELinux::
129
130			dont_measure obj_type=var_log_t
131			dont_appraise obj_type=var_log_t
132			dont_measure obj_type=auditd_log_t
133			dont_appraise obj_type=auditd_log_t
134			measure subj_user=system_u func=FILE_CHECK mask=MAY_READ
135			measure subj_role=system_r func=FILE_CHECK mask=MAY_READ
136
137		Smack::
138
139			measure subj_user=_ func=FILE_CHECK mask=MAY_READ
140
141		Example of measure rules using alternate PCRs::
142
143			measure func=KEXEC_KERNEL_CHECK pcr=4
144			measure func=KEXEC_INITRAMFS_CHECK pcr=5
145
146		Example of appraise rule allowing modsig appended signatures:
147
148			appraise func=KEXEC_KERNEL_CHECK appraise_type=imasig|modsig
149
150		Example of measure rule using KEY_CHECK to measure all keys:
151
152			measure func=KEY_CHECK
153
154		Example of measure rule using KEY_CHECK to only measure
155		keys added to .builtin_trusted_keys or .ima keyring:
156
157			measure func=KEY_CHECK keyrings=.builtin_trusted_keys|.ima
158
159		Example of the special SETXATTR_CHECK appraise rule, that
160		restricts the hash algorithms allowed when writing to the
161		security.ima xattr of a file:
162
163			appraise func=SETXATTR_CHECK appraise_algos=sha256,sha384,sha512
164
165		Example of a 'measure' rule requiring fs-verity's digests
166		with indication of type of digest in the measurement list.
167
168			measure func=FILE_CHECK digest_type=verity \
169				template=ima-ngv2
170
171		Example of 'measure' and 'appraise' rules requiring fs-verity
172		signatures (format version 3) stored in security.ima xattr.
173
174		The 'measure' rule specifies the 'ima-sigv3' template option,
175		which includes the indication of type of digest and the file
176		signature in the measurement list.
177
178			measure func=BPRM_CHECK digest_type=verity \
179				template=ima-sigv3
180
181
182		The 'appraise' rule specifies the type and signature format
183		version (sigv3) required.
184
185			appraise func=BPRM_CHECK digest_type=verity \
186				appraise_type=sigv3
187
188		All of these policy rules could, for example, be constrained
189		either based on a filesystem's UUID (fsuuid) or based on LSM
190		labels.
191