Debian Codegraph @

README

raw ◀ ▶
Source reconstructed at patch state 0 of 1 — not the installed (fully patched) source.
1 Debian patch touch this file
1 EVMCTL(1)
2 =========
3
4 NAME
5 ----
6
7 evmctl - IMA/EVM signing utility
8
9
10 SYNOPSIS
11 --------
12
13 evmctl [options] <command> [OPTIONS]
14
15
16 DESCRIPTION
17 -----------
18
19 The evmctl utility can be used for producing and verifying digital signatures,
20 which are used by Linux kernel integrity subsystem (IMA/EVM). It can be also
21 used to import keys into the kernel keyring.
22
23 COMMANDS
24 --------
25
26 --version
27 help <command>
28 import [--rsa (deprecated)] pubkey keyring
29 sign [-r] [--imahash | --imasig ] [--key key] [--pass[=<password>] file
30 verify file
31 ima_sign [--sigfile] [--key key] [--pass[=<password>]] file
32 ima_verify file
33 ima_setxattr [--sigfile file]
34 ima_hash file
35 ima_measurement [--ignore-violations] [--verify-sig [--key "key1, key2, ..."]]
36 [--pcrs [hash-algorithm,]file [--pcrs hash-algorithm,file] ...]
37 [--verify-bank hash-algorithm] file
38 ima_boot_aggregate [--pcrs hash-algorithm,file] [TPM 1.2 BIOS event log]
39 [--hwtpm]
40 ima_fix [-t fdsxm] path
41 ima_clear [-t fdsxm] path
42 sign_hash [--veritysig] [--key key] [--pass=<password>]
43 hmac [--imahash | --imasig ] file
44
45
46 OPTIONS
47 -------
48
49 -a, --hashalgo sha1, sha224, sha256, sha384, sha512, streebog256, streebog512 (default: sha256)
50 -s, --imasig make IMA signature
51 --veritysig sign an fs-verity file digest hash
52 -d, --imahash make IMA hash
53 -f, --sigfile store IMA signature in .sig file instead of xattr
54 --xattr-user store xattrs in user namespace (for testing purposes)
55 --rsa use RSA key type and signing scheme v1 (deprecated)
56 -k, --key path to signing key (default: /etc/keys/{privkey,pubkey}_evm.pem)
57 or a pkcs11 URI
58 --keyid n overwrite signature keyid with a 32-bit value in hex (for signing)
59 --keyid-from-cert file
60 read keyid value from SKID of a x509 cert file
61 -o, --portable generate portable EVM signatures
62 -p, --pass password for encrypted signing key
63 -r, --recursive recurse into directories (sign)
64 -t, --type file types to fix 'fxm' (f: file)
65 x - skip fixing if both ima and evm xattrs exist (use with caution)
66 m - stay on the same filesystem (like 'find -xdev')
67 -n print result to stdout instead of setting xattr
68 -u, --uuid use custom FS UUID for EVM (unspecified: from FS, empty: do not use)
69 --smack use extra SMACK xattrs for EVM
70 --m32 force EVM hmac/signature for 32 bit target system
71 --m64 force EVM hmac/signature for 64 bit target system
72 --engine e preload OpenSSL engine e (such as: gost) is deprecated
73 --ino use custom inode for EVM
74 --uid use custom UID for EVM
75 --gid use custom GID for EVM
76 --mode use custom Mode for EVM
77 --generation use custom Generation for EVM(unspecified: from FS, empty: use 0)
78 --ima use custom IMA signature for EVM
79 --selinux use custom Selinux label for EVM
80 --caps use custom Capabilities for EVM(unspecified: from FS, empty: do not use)
81 --pcrs file containing TPM pcrs, one per hash-algorithm/bank
82 --ignore-violations ignore ToMToU measurement violations
83 --verify-sig verify the file signature based on the file hash, both
84 stored in the template data.
85 -v increase verbosity level
86 -h, --help display this help and exit
87
88 Environment variables:
89
90 EVMCTL_KEY_PASSWORD : Private key password to use; do not use --pass option
91
92
93 INTRODUCTION
94 ------------
95
96 Linux kernel integrity subsystem is comprised of a number of different components
97 including the Integrity Measurement Architecture (IMA), Extended Verification Module
98 (EVM), IMA-appraisal extension, digital signature verification extension and audit
99 measurement log support.
100
101 The evmctl utility is used for producing and verifying digital signatures, which
102 are used by the Linux kernel integrity subsystem. It is also used for importing keys
103 into the kernel keyring.
104
105 Linux integrity subsystem allows one to use IMA and EVM signatures. EVM signature
106 protects file metadata, such as file attributes and extended attributes. IMA
107 signature protects file content.
108
109 For more detailed information about integrity subsystem it is recommended to follow
110 resources in RESOURCES section.
111
112
113 EVM HMAC and signature metadata
114 -------------------------------
115
116 EVM protects file metadata by including following attributes into HMAC and signature
117 calculation: inode number, inode generation, UID, GID, file mode, security.selinux,
118 security.SMACK64, security.ima, security.capability.
119
120 EVM HMAC and signature in may also include additional file and file system attributes.
121 Currently supported additional attributes are filesystem UUID and extra SMACK
122 extended attributes.
123
124 Kernel configuration option CONFIG_EVM_ATTR_FSUUID controls whether to include
125 filesystem UUID into HMAC and enabled by default. Therefore evmctl also includes
126 fsuuid by default. Providing '--uuid' option without parameter allows one to disable
127 usage of fs uuid. Providing '--uuid=UUID' option with parameter allows one to use
128 custom UUID. Providing the '--portable' option will disable usage of the fs uuid
129 and also the inode number and generation.
130
131 Kernel configuration option CONFIG_EVM_EXTRA_SMACK_XATTRS controls whether to
132 include additional SMACK extended attributes into HMAC. They are following:
133 security.SMACK64EXEC, security.SMACK64TRANSMUTE and security.SMACK64MMAP.
134 evmctl '--smack' options enables that.
135
136
137 Key and signature formats
138 -------------------------
139
140 Linux integrity subsystem supports two type of signature and respectively two
141 key formats.
142
143 First key format (v1) is pure RSA key encoded in PEM a format and uses own signature
144 format. It is now non-default format and requires to provide evmctl '--rsa' option
145 for signing and importing the key.
146
147 Second key format uses X509 DER encoded public key certificates and uses asymmetric key support
148 in the kernel (since kernel 3.9). CONFIG_INTEGRITY_ASYMMETRIC_KEYS must be enabled (default).
149
150 For v2 signatures x509 certificate (containing the public key) could be appended to the
151 private key (they both are in PEM format) to automatically extract keyid from its Subject
152 Key Identifier (SKID).
153
154 Integrity keyrings
155 ----------------
156
157 Integrity subsystem uses dedicated IMA/EVM keyrings to search for signature verification
158 keys - '_ima' and '_evm' respectively.
159
160 Since 3.13 IMA allows one to declare IMA keyring as trusted. It allows only to load keys,
161 signed by a key from the system keyring (.system). It means self-signed keys are not
162 allowed. This is a default behavior unless CONFIG_IMA_TRUSTED_KEYRING is undefined.
163 IMA trusted keyring is has different name '.ima'. Trusted keyring requires X509
164 public key certificates. Old version RSA public keys are not compatible with trusted
165 keyring.
166
167
168 Generate EVM encrypted keys
169 ---------------------------
170
171 EVM encrypted key is used for EVM HMAC calculation:
172
173 # create and save the key kernel master key (user type)
174 # LMK is used to encrypt encrypted keys
175 keyctl add user kmk "`dd if=/dev/urandom bs=1 count=32 2>/dev/null`" @u
176 keyctl pipe `keyctl search @u user kmk` > /etc/keys/kmk
177
178 # create the EVM encrypted key
179 keyctl add encrypted evm-key "new user:kmk 64" @u
180 keyctl pipe `keyctl search @u encrypted evm-key` >/etc/keys/evm-key
181
182
183 Generate EVM trusted keys (TPM based)
184 -------------------------------------
185
186 Trusted EVM keys are keys which a generate with the help of TPM.
187 They are not related to integrity trusted keys.
188
189 # create and save the key kernel master key (user type)
190 keyctl add trusted kmk "new 32" @u
191 keyctl pipe `keyctl search @u trusted kmk` >kmk
192
193 # create the EVM trusted key
194 keyctl add encrypted evm-key "new trusted:kmk 32" @u
195 keyctl pipe `keyctl search @u encrypted evm-key` >evm-key
196
197
198 Generate signing and verification keys
199 --------------------------------------
200
201 Generate private key in plain text format:
202
203 openssl genrsa -out privkey_evm.pem 1024
204
205 Generate encrypted private key:
206
207 openssl genrsa -des3 -out privkey_evm.pem 1024
208
209 Make encrypted private key from unencrypted:
210
211 openssl rsa -in /etc/keys/privkey_evm.pem -out privkey_evm_enc.pem -des3
212
213 Generate self-signed X509 public key certificate and private key for using kernel
214 asymmetric keys support:
215
216 openssl req -new -nodes -utf8 -sha1 -days 36500 -batch \
217 -x509 -config x509_evm.genkey \
218 -outform DER -out x509_evm.der -keyout privkey_evm.pem
219
220 Configuration file x509_evm.genkey:
221
222 # Beginning of the file
223 [ req ]
224 default_bits = 1024
225 distinguished_name = req_distinguished_name
226 prompt = no
227 string_mask = utf8only
228 x509_extensions = myexts
229
230 [ req_distinguished_name ]
231 O = Magrathea
232 CN = Glacier signing key
233 emailAddress = [email protected]
234
235 [ myexts ]
236 basicConstraints=critical,CA:FALSE
237 keyUsage=digitalSignature
238 subjectKeyIdentifier=hash
239 authorityKeyIdentifier=keyid
240 # EOF
241
242
243 Generate public key for using RSA key format:
244
245 openssl rsa -pubout -in privkey_evm.pem -out pubkey_evm.pem
246
247
248 Copy keys to /etc/keys:
249
250 cp pubkey_evm.pem /etc/keys
251 scp pubkey_evm.pem target:/etc/keys
252 or
253 cp x509_evm.pem /etc/keys
254 scp x509_evm.pem target:/etc/keys
255
256
257 Generate trusted keys
258 ---------------------
259
260 Generation of trusted keys is a bit more complicated process and involves
261 following steps:
262
263 * Creation of local IMA certification authority (CA).
264 It consist of private and public key certificate which are used
265 to sign and verify other keys.
266 * Build Linux kernel with embedded local IMA CA X509 certificate.
267 It is used to verify other keys added to the '.ima' trusted keyring
268 * Generate IMA private signing key and verification public key certificate,
269 which is signed using local IMA CA private key.
270
271 Configuration file ima-local-ca.genkey:
272
273 # Beginning of the file
274 [ req ]
275 default_bits = 2048
276 distinguished_name = req_distinguished_name
277 prompt = no
278 string_mask = utf8only
279 x509_extensions = v3_ca
280
281 [ req_distinguished_name ]
282 O = IMA-CA
283 CN = IMA/EVM certificate signing key
284 emailAddress = ca@ima-ca
285
286 [ v3_ca ]
287 basicConstraints=CA:TRUE
288 subjectKeyIdentifier=hash
289 authorityKeyIdentifier=keyid:always,issuer
290 # keyUsage = cRLSign, keyCertSign
291 # EOF
292
293 Generate private key and X509 public key certificate:
294
295 openssl req -new -x509 -utf8 -sha1 -days 3650 -batch -config $GENKEY \
296 -outform DER -out ima-local-ca.x509 -keyout ima-local-ca.priv
297
298 Produce X509 in DER format for using while building the kernel:
299
300 openssl x509 -inform DER -in ima-local-ca.x509 -out ima-local-ca.pem
301
302 Configuration file ima.genkey:
303
304 # Beginning of the file
305 [ req ]
306 default_bits = 1024
307 distinguished_name = req_distinguished_name
308 prompt = no
309 string_mask = utf8only
310 x509_extensions = v3_usr
311
312 [ req_distinguished_name ]
313 O = `hostname`
314 CN = `whoami` signing key
315 emailAddress = `whoami`@`hostname`
316
317 [ v3_usr ]
318 basicConstraints=critical,CA:FALSE
319 #basicConstraints=CA:FALSE
320 keyUsage=digitalSignature
321 #keyUsage = nonRepudiation, digitalSignature, keyEncipherment
322 subjectKeyIdentifier=hash
323 authorityKeyIdentifier=keyid
324 #authorityKeyIdentifier=keyid,issuer
325 # EOF
326
327
328 Generate private key and X509 public key certificate signing request:
329
330 openssl req -new -nodes -utf8 -sha1 -days 365 -batch -config $GENKEY \
331 -out csr_ima.pem -keyout privkey_ima.pem
332
333 Sign X509 public key certificate signing request with local IMA CA private key:
334
335 openssl x509 -req -in csr_ima.pem -days 365 -extfile $GENKEY -extensions v3_usr \
336 -CA ima-local-ca.pem -CAkey ima-local-ca.priv -CAcreateserial \
337 -outform DER -out x509_ima.der
338
339
340 Sign file data and metadata
341 ---------------------------
342
343 Default key locations:
344
345 Private RSA key: /etc/keys/privkey_evm.pem
346 Public RSA key: /etc/keys/pubkey_evm.pem
347 X509 certificate: /etc/keys/x509_evm.der
348
349 Options to remember: '-k', '-r', '--rsa', '--uuid', '--smack'.
350
351 Sign file with EVM signature and calculate hash value for IMA:
352
353 evmctl sign --imahash test.txt
354
355 Sign file with both IMA and EVM signatures:
356
357 evmctl sign --imasig test.txt:
358
359 Sign file with IMA signature:
360
361 evmctl ima_sign test.txt
362
363 Sign recursively whole filesystem:
364
365 evmctl -r sign --imahash /
366
367 Fix recursively whole filesystem:
368
369 evmctl -r ima_fix /
370
371 Sign filesystem selectively using 'find' command:
372
373 find / \( -fstype rootfs -o -fstype ext4 \) -exec evmctl sign --imahash '{}' \;
374
375 Fix filesystem selectively using 'find' command:
376
377 find / \( -fstype rootfs -o -fstype ext4 \) -exec sh -c "< '{}'" \;
378
379
380 Initialize IMA/EVM at early boot
381 --------------------------------
382
383 IMA/EVM initialization should be normally done from initial RAM file system
384 before mounting root filesystem.
385
386 Here is Ubuntu initramfs example script (/etc/initramfs-tools/scripts/local-top/ima.sh)
387
388 # mount securityfs if not mounted
389 SECFS=/sys/kernel/security
390 grep -q $SECFS /proc/mounts || mount -n -t securityfs securityfs $SECFS
391
392 # search for IMA trusted keyring, then for untrusted
393 ima_id="`awk '/\.ima/ { printf "%d", "0x"$1; }' /proc/keys`"
394 if [ -z "$ima_id" ]; then
395 ima_id=`keyctl search @u keyring _ima 2>/dev/null`
396 if [ -z "$ima_id" ]; then
397 ima_id=`keyctl newring _ima @u`
398 fi
399 fi
400 # import IMA X509 certificate
401 evmctl import /etc/keys/x509_ima.der $ima_id
402
403 # search for EVM keyring
404 evm_id=`keyctl search @u keyring _evm 2>/dev/null`
405 if [ -z "$evm_id" ]; then
406 evm_id=`keyctl newring _evm @u`
407 fi
408 # import EVM X509 certificate
409 evmctl import /etc/keys/x509_evm.der $evm_id
410
411 # a) import EVM encrypted key
412 cat /etc/keys/kmk | keyctl padd user kmk @u
413 keyctl add encrypted evm-key "load `cat /etc/keys/evm-key`" @u
414 # OR
415 # b) import EVM trusted key
416 keyctl add trusted kmk "load `cat /etc/keys/kmk`" @u
417 keyctl add encrypted evm-key "load `cat /etc/keys/evm-key`" @u
418
419 # enable EVM
420 echo "1" > /sys/kernel/security/evm
421
422 Optionally it is possible also to forbid adding, removing of new public keys
423 and certificates into keyrings and revoking keys using 'keyctl setperm' command:
424
425 # protect EVM keyring
426 keyctl setperm $evm_id 0x0b0b0000
427 # protect IMA keyring
428 keyctl setperm $ima_id 0x0b0b0000
429 # protecting IMA key from revoking (against DoS)
430 ima_key=`evmctl import /etc/keys/x509_ima.der $ima_id`
431 keyctl setperm $ima_key 0x0b0b0000
432
433
434 When using plain RSA public keys in PEM format, use 'evmctl import --rsa' for importing keys:
435
436 evmctl import --rsa /etc/keys/pubkey_evm.pem $evm_id
437
438 Latest version of keyctl allows one to import X509 public key certificates:
439
440 cat /etc/keys/x509_ima.der | keyctl padd asymmetric '' $ima_id
441
442
443 FILES
444 -----
445
446 Examples of scripts to generate X509 public key certificates:
447
448 /usr/share/doc/ima-evm-utils/ima-genkey-self.sh
449 /usr/share/doc/ima-evm-utils/ima-genkey.sh
450 /usr/share/doc/ima-evm-utils/ima-gen-local-ca.sh
451
452
453 AUTHOR
454 ------
455
456 Written by Dmitry Kasatkin, <dmitry.kasatkin at gmail.com> and others.
457
458
459 RESOURCES
460 ---------
461
462 http://sourceforge.net/p/linux-ima/wiki/Home
463 http://sourceforge.net/p/linux-ima/ima-evm-utils
464
465
466 COPYING
467 -------
468
469 Copyright \(C) 2012 - 2014 Linux Integrity Project. Free use of this software is granted under
470 the terms of the GNU General Public License (GPL).
471