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