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] pubkey keyring
20 sign [-r] [--imahash | --imasig ] [--portable] [--key key] [--pass password] file
21 verify file
22 ima_boot_aggregate [--pcrs hash-algorithm,file] [TPM 1.2 BIOS event log]
23 ima_sign [--sigfile] [--key key] [--pass password] file
24 ima_verify file
25 ima_hash file
26 ima_measurement [--ignore-violations] [--verify-sig [--key "key1, key2, ..."]] [--pcrs [hash-algorithm,]file [--pcrs hash-algorithm,file] ...] file
27 ima_fix [-t fdsxm] path
28 sign_hash [--key key] [--pass password]
29 hmac [--imahash | --imasig ] file
30
32 -a, --hashalgo sha1 (default), sha224, sha256, sha384, sha512
33 -s, --imasig make IMA signature
34 -d, --imahash make IMA hash
35 -f, --sigfile store IMA signature in .sig file instead of xattr
36 --xattr-user store xattrs in user namespace (for testing purposes)
37 --rsa use RSA key type and signing scheme v1
38 -k, --key path to signing key (default: /etc/keys/{privkey,pubkey}_evm.pem)
39 -o, --portable generate portable EVM signatures
40 -p, --pass password for encrypted signing key
41 -r, --recursive recurse into directories (sign)
42 -t, --type file types to fix 'fdsxm' (f: file, d: directory, s: block/char/symlink)
43 x - skip fixing if both ima and evm xattrs exist (use with caution)
44 m - stay on the same filesystem (like 'find -xdev')
45 -n print result to stdout instead of setting xattr
46 -u, --uuid use custom FS UUID for EVM (unspecified: from FS, empty: do not use)
47 --smack use extra SMACK xattrs for EVM
48 --m32 force EVM hmac/signature for 32 bit target system
49 --m64 force EVM hmac/signature for 64 bit target system
50 --engine e preload OpenSSL engine e (such as: gost)
51 --pcrs file containing TPM pcrs, one per hash-algorithm/bank
52 --ignore-violations ignore ToMToU measurement violations
53 --verify-sig verify the file signature based on the file hash, both
54 stored in the template data.
55 -v increase verbosity level
56 -h, --help display this help and exit
57
59 Linux kernel integrity subsystem is comprised of a number of different
60 components including the Integrity Measurement Architecture (IMA),
61 Extended Verification Module (EVM), IMA-appraisal extension, digital
62 signature verification extension and audit measurement log support.
63 The evmctl utility is used for producing and verifying digital
65 signatures, which are used by the Linux kernel integrity subsystem. It
66 is also used for importing keys into the kernel keyring.
67 Linux integrity subsystem allows to use IMA and EVM signatures. EVM
69 signature protects file metadata, such as file attributes and extended
70 attributes. IMA signature protects file content.
71 For more detailed information about integrity subsystem it is
73 recommended to follow resources in RESOURCES section.
74
76 EVM protects file metadata by including following attributes into HMAC
77 and signature calculation: inode number, inode generation, UID, GID,
78 file mode, security.selinux, security.SMACK64, security.ima,
79 security.capability.
80 EVM HMAC and signature in may also include additional file and file
82 system attributes. Currently supported additional attributes are
83 filesystem UUID and extra SMACK extended attributes.
84 Kernel configuration option CONFIG_EVM_ATTR_FSUUID controls whether to
86 include filesystem UUID into HMAC and enabled by default. Therefore
87 evmctl also includes fsuuid by default. Providing --uuid option without
88 parameter allows to disable usage of fs uuid. Providing --uuid=UUID
89 option with parameter allows to use custom UUID. Providing the
90 --portable option will disable usage of the fs uuid and also the inode
91 number and generation.
92 Kernel configuration option CONFIG_EVM_EXTRA_SMACK_XATTRS controls
94 whether to include additional SMACK extended attributes into HMAC. They
95 are following: security.SMACK64EXEC, security.SMACK64TRANSMUTE and
96 security.SMACK64MMAP. evmctl --smack options enables that.
97
99 Linux integrity subsystem supports two type of signature and
100 respectively two key formats.
101 First key format (v1) is pure RSA key encoded in PEM a format and uses
103 own signature format. It is now non-default format and requires to
104 provide evmctl --rsa option for signing and importing the key.
105 Second key format uses X509 DER encoded public key certificates and
107 uses asymmetric key support in the kernel (since kernel 3.9).
108 CONFIG_INTEGRITY_ASYMMETRIC_KEYS must be enabled (default).
109
111 Integrity subsystem uses dedicated IMA/EVM keyrings to search for
112 signature verification keys - _ima and _evm respectively.
113 Since 3.13 IMA allows to declare IMA keyring as trusted. It allows only
115 to load keys, signed by a key from the system keyring (.system). It
116 means self-signed keys are not allowed. This is a default behavior
117 unless CONFIG_IMA_TRUSTED_KEYRING is undefined. IMA trusted keyring is
118 has different name .ima. Trusted keyring requires X509 public key
119 certificates. Old version RSA public keys are not compatible with
120 trusted keyring.
121
123 EVM encrypted key is used for EVM HMAC calculation:
124 # create and save the key kernel master key (user type)
126 # LMK is used to encrypt encrypted keys
127 keyctl add user kmk "`dd if=/dev/urandom bs=1 count=32 2>/dev/null`" @u
128 keyctl pipe `keyctl search @u user kmk` > /etc/keys/kmk
129 # create the EVM encrypted key
131 keyctl add encrypted evm-key "new user:kmk 64" @u
132 keyctl pipe `keyctl search @u encrypted evm-key` >/etc/keys/evm-key
133
135 Trusted EVM keys are keys which a generate with the help of TPM. They
136 are not related to integrity trusted keys.
137 # create and save the key kernel master key (user type)
139 keyctl add trusted kmk "new 32" @u
140 keyctl pipe `keyctl search @u trusted kmk` >kmk
141 # create the EVM trusted key
143 keyctl add encrypted evm-key "new trusted:kmk 32" @u
144 keyctl pipe `keyctl search @u encrypted evm-key` >evm-key
145
147 Generate private key in plain text format:
148 openssl genrsa -out privkey_evm.pem 1024
150 Generate encrypted private key:
152 openssl genrsa -des3 -out privkey_evm.pem 1024
154 Make encrypted private key from unencrypted:
156 openssl rsa -in /etc/keys/privkey_evm.pem -out privkey_evm_enc.pem -des3
158 Generate self-signed X509 public key certificate and private key for
160 using kernel asymmetric keys support:
161 openssl req -new -nodes -utf8 -sha1 -days 36500 -batch \
163 -x509 -config x509_evm.genkey \
164 -outform DER -out x509_evm.der -keyout privkey_evm.pem
165 Configuration file x509_evm.genkey:
167 # Begining of the file
169 [ req ]
170 default_bits = 1024
171 distinguished_name = req_distinguished_name
172 prompt = no
173 string_mask = utf8only
174 x509_extensions = myexts
175 [ req_distinguished_name ]
177 O = Magrathea
178 CN = Glacier signing key
179 emailAddress = slartibartfast@magrathea.h2g2
180 [ myexts ]
182 basicConstraints=critical,CA:FALSE
183 keyUsage=digitalSignature
184 subjectKeyIdentifier=hash
185 authorityKeyIdentifier=keyid
186 # EOF
187 Generate public key for using RSA key format:
189 openssl rsa -pubout -in privkey_evm.pem -out pubkey_evm.pem
191 Copy keys to /etc/keys:
193 cp pubkey_evm.pem /etc/keys
195 scp pubkey_evm.pem target:/etc/keys
196 or
197 cp x509_evm.pem /etc/keys
198 scp x509_evm.pem target:/etc/keys
199
201 Generation of trusted keys is a bit more complicated process and
202 involves following steps:
203 • Creation of local IMA certification authority (CA). It consist of
205 private and public key certificate which are used to sign and
206 verify other keys.
207 • Build Linux kernel with embedded local IMA CA X509 certificate. It
209 is used to verify other keys added to the .ima trusted keyring
210 • Generate IMA private signing key and verification public key
212 certificate, which is signed using local IMA CA private key.
213 Configuration file ima-local-ca.genkey:
215 # Begining of the file
217 [ req ]
218 default_bits = 2048
219 distinguished_name = req_distinguished_name
220 prompt = no
221 string_mask = utf8only
222 x509_extensions = v3_ca
223 [ req_distinguished_name ]
225 O = IMA-CA
226 CN = IMA/EVM certificate signing key
227 emailAddress = ca@ima-ca
228 [ v3_ca ]
230 basicConstraints=CA:TRUE
231 subjectKeyIdentifier=hash
232 authorityKeyIdentifier=keyid:always,issuer
233 # keyUsage = cRLSign, keyCertSign
234 # EOF
235 Generate private key and X509 public key certificate:
237 openssl req -new -x509 -utf8 -sha1 -days 3650 -batch -config $GENKEY \
239 -outform DER -out ima-local-ca.x509 -keyout ima-local-ca.priv
240 Produce X509 in DER format for using while building the kernel:
242 openssl x509 -inform DER -in ima-local-ca.x509 -out ima-local-ca.pem
244 Configuration file ima.genkey:
246 # Begining of the file
248 [ req ]
249 default_bits = 1024
250 distinguished_name = req_distinguished_name
251 prompt = no
252 string_mask = utf8only
253 x509_extensions = v3_usr
254 [ req_distinguished_name ]
256 O = `hostname`
257 CN = `whoami` signing key
258 emailAddress = `whoami`@`hostname`
259 [ v3_usr ]
261 basicConstraints=critical,CA:FALSE
262 #basicConstraints=CA:FALSE
263 keyUsage=digitalSignature
264 #keyUsage = nonRepudiation, digitalSignature, keyEncipherment
265 subjectKeyIdentifier=hash
266 authorityKeyIdentifier=keyid
267 #authorityKeyIdentifier=keyid,issuer
268 # EOF
269 Generate private key and X509 public key certificate signing request:
271 openssl req -new -nodes -utf8 -sha1 -days 365 -batch -config $GENKEY \
273 -out csr_ima.pem -keyout privkey_ima.pem
274 Sign X509 public key certificate signing request with local IMA CA
276 private key:
277 openssl x509 -req -in csr_ima.pem -days 365 -extfile $GENKEY -extensions v3_usr \
279 -CA ima-local-ca.pem -CAkey ima-local-ca.priv -CAcreateserial \
280 -outform DER -out x509_ima.der
281
283 Default key locations:
284 Private RSA key: /etc/keys/privkey_evm.pem
286 Public RSA key: /etc/keys/pubkey_evm.pem
287 X509 certificate: /etc/keys/x509_evm.der
288 Options to remember: -k, -r, --rsa, --uuid, --smack.
290 Sign file with EVM signature and calculate hash value for IMA:
292 evmctl sign --imahash test.txt
294 Sign file with both IMA and EVM signatures:
296 evmctl sign --imasig test.txt:
298 Sign file with IMA signature:
300 evmctl ima_sign test.txt
302 Sign recursively whole filesystem:
304 evmctl -r sign --imahash /
306 Fix recursively whole filesystem:
308 evmctl -r ima_fix /
310 Sign filesystem selectively using find command:
312 find / \( -fstype rootfs -o -fstype ext4 \) -exec evmctl sign --imahash '{}' \;
314 Fix filesystem selectively using find command:
316 find / \( -fstype rootfs -o -fstype ext4 \) -exec sh -c "< '{}'" \;
318
320 IMA/EVM initialization should be normally done from initial RAM file
321 system before mounting root filesystem.
322 Here is Ubuntu initramfs example script
324 (/etc/initramfs-tools/scripts/local-top/ima.sh)
325 # mount securityfs if not mounted
327 SECFS=/sys/kernel/security
328 grep -q $SECFS /proc/mounts || mount -n -t securityfs securityfs $SECFS
329 # search for IMA trusted keyring, then for untrusted
331 ima_id="`awk '/\.ima/ { printf "%d", "0x"$1; }' /proc/keys`"
332 if [ -z "$ima_id" ]; then
333 ima_id=`keyctl search @u keyring _ima 2>/dev/null`
334 if [ -z "$ima_id" ]; then
335 ima_id=`keyctl newring _ima @u`
336 fi
337 fi
338 # import IMA X509 certificate
339 evmctl import /etc/keys/x509_ima.der $ima_id
340 # search for EVM keyring
342 evm_id=`keyctl search @u keyring _evm 2>/dev/null`
343 if [ -z "$evm_id" ]; then
344 evm_id=`keyctl newring _evm @u`
345 fi
346 # import EVM X509 certificate
347 evmctl import /etc/keys/x509_evm.der $evm_id
348 # a) import EVM encrypted key
350 cat /etc/keys/kmk | keyctl padd user kmk @u
351 keyctl add encrypted evm-key "load `cat /etc/keys/evm-key`" @u
352 # OR
353 # b) import EVM trusted key
354 keyctl add trusted kmk "load `cat /etc/keys/kmk`" @u
355 keyctl add encrypted evm-key "load `cat /etc/keys/evm-key`" @u
356 # enable EVM
358 echo "1" > /sys/kernel/security/evm
359 Optionally it is possible also to forbid adding, removing of new public
361 keys and certificates into keyrings and revoking keys using keyctl
362 setperm command:
363 # protect EVM keyring
365 keyctl setperm $evm_id 0x0b0b0000
366 # protect IMA keyring
367 keyctl setperm $ima_id 0x0b0b0000
368 # protecting IMA key from revoking (against DoS)
369 ima_key=`evmctl import /etc/keys/x509_ima.der $ima_id`
370 keyctl setperm $ima_key 0x0b0b0000
371 When using plain RSA public keys in PEM format, use evmctl import --rsa
373 for importing keys:
374 evmctl import --rsa /etc/keys/pubkey_evm.pem $evm_id
376 Latest version of keyctl allows to import X509 public key certificates:
378 cat /etc/keys/x509_ima.der | keyctl padd asymmetric '' $ima_id
380
382 Examples of scripts to generate X509 public key certificates:
383 /usr/share/doc/ima-evm-utils/ima-genkey-self.sh
385 /usr/share/doc/ima-evm-utils/ima-genkey.sh
386 /usr/share/doc/ima-evm-utils/ima-gen-local-ca.sh
387
389 Written by Dmitry Kasatkin, <dmitry.kasatkin at gmail.com> and others.
390
392 http://sourceforge.net/p/linux-ima/wiki/Home
393 http://sourceforge.net/p/linux-ima/ima-evm-utils
394
396 Copyright (C) 2012 - 2014 Linux Integrity Project. Free use of this
397 software is granted under the terms of the GNU Public License (GPL).
398 07/22/2021 EVMCTL(1)