1EVMCTL(1)                                                            EVMCTL(1)
2
3
4

NAME

6       evmctl - IMA/EVM signing utility
7

SYNOPSIS

9       evmctl [options] <command> [OPTIONS]
10

DESCRIPTION

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

COMMANDS

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

OPTIONS

32           -a, --hashalgo     sha1, 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                              or a pkcs11 URI
40               --keyid n      overwrite signature keyid with a 32-bit value in hex (for signing)
41               --keyid-from-cert file
42                              read keyid value from SKID of a x509 cert file
43           -o, --portable     generate portable EVM signatures
44           -p, --pass         password for encrypted signing key
45           -r, --recursive    recurse into directories (sign)
46           -t, --type         file types to fix 'fxm' (f: file)
47                              x - skip fixing if both ima and evm xattrs exist (use with caution)
48                              m - stay on the same filesystem (like 'find -xdev')
49           -n                 print result to stdout instead of setting xattr
50           -u, --uuid         use custom FS UUID for EVM (unspecified: from FS, empty: do not use)
51               --smack        use extra SMACK xattrs for EVM
52               --m32          force EVM hmac/signature for 32 bit target system
53               --m64          force EVM hmac/signature for 64 bit target system
54               --engine e     preload OpenSSL engine e (such as: gost)
55               --pcrs         file containing TPM pcrs, one per hash-algorithm/bank
56               --ignore-violations ignore ToMToU measurement violations
57               --verify-sig   verify the file signature based on the file hash, both
58                              stored in the template data.
59           -v                 increase verbosity level
60           -h, --help         display this help and exit
61
62       Environment variables:
63
64       EVMCTL_KEY_PASSWORD : Private key password to use; do not use --pass
65       option
66

INTRODUCTION

68       Linux kernel integrity subsystem is comprised of a number of different
69       components including the Integrity Measurement Architecture (IMA),
70       Extended Verification Module (EVM), IMA-appraisal extension, digital
71       signature verification extension and audit measurement log support.
72
73       The evmctl utility is used for producing and verifying digital
74       signatures, which are used by the Linux kernel integrity subsystem. It
75       is also used for importing keys into the kernel keyring.
76
77       Linux integrity subsystem allows to use IMA and EVM signatures. EVM
78       signature protects file metadata, such as file attributes and extended
79       attributes. IMA signature protects file content.
80
81       For more detailed information about integrity subsystem it is
82       recommended to follow resources in RESOURCES section.
83

EVM HMAC AND SIGNATURE METADATA

85       EVM protects file metadata by including following attributes into HMAC
86       and signature calculation: inode number, inode generation, UID, GID,
87       file mode, security.selinux, security.SMACK64, security.ima,
88       security.capability.
89
90       EVM HMAC and signature in may also include additional file and file
91       system attributes. Currently supported additional attributes are
92       filesystem UUID and extra SMACK extended attributes.
93
94       Kernel configuration option CONFIG_EVM_ATTR_FSUUID controls whether to
95       include filesystem UUID into HMAC and enabled by default. Therefore
96       evmctl also includes fsuuid by default. Providing --uuid option without
97       parameter allows to disable usage of fs uuid. Providing --uuid=UUID
98       option with parameter allows to use custom UUID. Providing the
99       --portable option will disable usage of the fs uuid and also the inode
100       number and generation.
101
102       Kernel configuration option CONFIG_EVM_EXTRA_SMACK_XATTRS controls
103       whether to include additional SMACK extended attributes into HMAC. They
104       are following: security.SMACK64EXEC, security.SMACK64TRANSMUTE and
105       security.SMACK64MMAP. evmctl --smack options enables that.
106

KEY AND SIGNATURE FORMATS

108       Linux integrity subsystem supports two type of signature and
109       respectively two key formats.
110
111       First key format (v1) is pure RSA key encoded in PEM a format and uses
112       own signature format. It is now non-default format and requires to
113       provide evmctl --rsa option for signing and importing the key.
114
115       Second key format uses X509 DER encoded public key certificates and
116       uses asymmetric key support in the kernel (since kernel 3.9).
117       CONFIG_INTEGRITY_ASYMMETRIC_KEYS must be enabled (default).
118
119       For v2 signatures x509 certificate (containing the public key) could be
120       appended to the private key (they both are in PEM format) to
121       automatically extract keyid from its Subject Key Identifier (SKID).
122

INTEGRITY KEYRINGS

124       Integrity subsystem uses dedicated IMA/EVM keyrings to search for
125       signature verification keys - _ima and _evm respectively.
126
127       Since 3.13 IMA allows to declare IMA keyring as trusted. It allows only
128       to load keys, signed by a key from the system keyring (.system). It
129       means self-signed keys are not allowed. This is a default behavior
130       unless CONFIG_IMA_TRUSTED_KEYRING is undefined. IMA trusted keyring is
131       has different name .ima. Trusted keyring requires X509 public key
132       certificates. Old version RSA public keys are not compatible with
133       trusted keyring.
134

GENERATE EVM ENCRYPTED KEYS

136       EVM encrypted key is used for EVM HMAC calculation:
137
138           # create and save the key kernel master key (user type)
139           # LMK is used to encrypt encrypted keys
140           keyctl add user kmk "`dd if=/dev/urandom bs=1 count=32 2>/dev/null`" @u
141           keyctl pipe `keyctl search @u user kmk` > /etc/keys/kmk
142
143           # create the EVM encrypted key
144           keyctl add encrypted evm-key "new user:kmk 64" @u
145           keyctl pipe `keyctl search @u encrypted evm-key` >/etc/keys/evm-key
146

GENERATE EVM TRUSTED KEYS (TPM BASED)

148       Trusted EVM keys are keys which a generate with the help of TPM. They
149       are not related to integrity trusted keys.
150
151           # create and save the key kernel master key (user type)
152           keyctl add trusted kmk "new 32" @u
153           keyctl pipe `keyctl search @u trusted kmk` >kmk
154
155           # create the EVM trusted key
156           keyctl add encrypted evm-key "new trusted:kmk 32" @u
157           keyctl pipe `keyctl search @u encrypted evm-key` >evm-key
158

GENERATE SIGNING AND VERIFICATION KEYS

160       Generate private key in plain text format:
161
162           openssl genrsa -out privkey_evm.pem 1024
163
164       Generate encrypted private key:
165
166           openssl genrsa -des3 -out privkey_evm.pem 1024
167
168       Make encrypted private key from unencrypted:
169
170           openssl rsa -in /etc/keys/privkey_evm.pem -out privkey_evm_enc.pem -des3
171
172       Generate self-signed X509 public key certificate and private key for
173       using kernel asymmetric keys support:
174
175           openssl req -new -nodes -utf8 -sha1 -days 36500 -batch \
176                       -x509 -config x509_evm.genkey \
177                       -outform DER -out x509_evm.der -keyout privkey_evm.pem
178
179       Configuration file x509_evm.genkey:
180
181           # Begining of the file
182           [ req ]
183           default_bits = 1024
184           distinguished_name = req_distinguished_name
185           prompt = no
186           string_mask = utf8only
187           x509_extensions = myexts
188
189           [ req_distinguished_name ]
190           O = Magrathea
191           CN = Glacier signing key
192           emailAddress = slartibartfast@magrathea.h2g2
193
194           [ myexts ]
195           basicConstraints=critical,CA:FALSE
196           keyUsage=digitalSignature
197           subjectKeyIdentifier=hash
198           authorityKeyIdentifier=keyid
199           # EOF
200
201       Generate public key for using RSA key format:
202
203           openssl rsa -pubout -in privkey_evm.pem -out pubkey_evm.pem
204
205       Copy keys to /etc/keys:
206
207              cp pubkey_evm.pem /etc/keys
208              scp pubkey_evm.pem target:/etc/keys
209           or
210              cp x509_evm.pem /etc/keys
211              scp x509_evm.pem target:/etc/keys
212

GENERATE TRUSTED KEYS

214       Generation of trusted keys is a bit more complicated process and
215       involves following steps:
216
217       •   Creation of local IMA certification authority (CA). It consist of
218           private and public key certificate which are used to sign and
219           verify other keys.
220
221       •   Build Linux kernel with embedded local IMA CA X509 certificate. It
222           is used to verify other keys added to the .ima trusted keyring
223
224       •   Generate IMA private signing key and verification public key
225           certificate, which is signed using local IMA CA private key.
226
227       Configuration file ima-local-ca.genkey:
228
229           # Begining of the file
230           [ req ]
231           default_bits = 2048
232           distinguished_name = req_distinguished_name
233           prompt = no
234           string_mask = utf8only
235           x509_extensions = v3_ca
236
237           [ req_distinguished_name ]
238           O = IMA-CA
239           CN = IMA/EVM certificate signing key
240           emailAddress = ca@ima-ca
241
242           [ v3_ca ]
243           basicConstraints=CA:TRUE
244           subjectKeyIdentifier=hash
245           authorityKeyIdentifier=keyid:always,issuer
246           # keyUsage = cRLSign, keyCertSign
247           # EOF
248
249       Generate private key and X509 public key certificate:
250
251           openssl req -new -x509 -utf8 -sha1 -days 3650 -batch -config $GENKEY \
252                       -outform DER -out ima-local-ca.x509 -keyout ima-local-ca.priv
253
254       Produce X509 in DER format for using while building the kernel:
255
256           openssl x509 -inform DER -in ima-local-ca.x509 -out ima-local-ca.pem
257
258       Configuration file ima.genkey:
259
260           # Begining of the file
261           [ req ]
262           default_bits = 1024
263           distinguished_name = req_distinguished_name
264           prompt = no
265           string_mask = utf8only
266           x509_extensions = v3_usr
267
268           [ req_distinguished_name ]
269           O = `hostname`
270           CN = `whoami` signing key
271           emailAddress = `whoami`@`hostname`
272
273           [ v3_usr ]
274           basicConstraints=critical,CA:FALSE
275           #basicConstraints=CA:FALSE
276           keyUsage=digitalSignature
277           #keyUsage = nonRepudiation, digitalSignature, keyEncipherment
278           subjectKeyIdentifier=hash
279           authorityKeyIdentifier=keyid
280           #authorityKeyIdentifier=keyid,issuer
281           # EOF
282
283       Generate private key and X509 public key certificate signing request:
284
285           openssl req -new -nodes -utf8 -sha1 -days 365 -batch -config $GENKEY \
286                       -out csr_ima.pem -keyout privkey_ima.pem
287
288       Sign X509 public key certificate signing request with local IMA CA
289       private key:
290
291           openssl x509 -req -in csr_ima.pem -days 365 -extfile $GENKEY -extensions v3_usr \
292                        -CA ima-local-ca.pem -CAkey ima-local-ca.priv -CAcreateserial \
293                        -outform DER -out x509_ima.der
294

SIGN FILE DATA AND METADATA

296       Default key locations:
297
298           Private RSA key: /etc/keys/privkey_evm.pem
299           Public RSA key: /etc/keys/pubkey_evm.pem
300           X509 certificate: /etc/keys/x509_evm.der
301
302       Options to remember: -k, -r, --rsa, --uuid, --smack.
303
304       Sign file with EVM signature and calculate hash value for IMA:
305
306           evmctl sign --imahash test.txt
307
308       Sign file with both IMA and EVM signatures:
309
310           evmctl sign --imasig test.txt:
311
312       Sign file with IMA signature:
313
314           evmctl ima_sign test.txt
315
316       Sign recursively whole filesystem:
317
318           evmctl -r sign --imahash /
319
320       Fix recursively whole filesystem:
321
322           evmctl -r ima_fix /
323
324       Sign filesystem selectively using find command:
325
326           find / \( -fstype rootfs -o -fstype ext4 \) -exec evmctl sign --imahash '{}' \;
327
328       Fix filesystem selectively using find command:
329
330           find / \( -fstype rootfs -o -fstype ext4 \) -exec sh -c "< '{}'" \;
331

INITIALIZE IMA/EVM AT EARLY BOOT

333       IMA/EVM initialization should be normally done from initial RAM file
334       system before mounting root filesystem.
335
336       Here is Ubuntu initramfs example script
337       (/etc/initramfs-tools/scripts/local-top/ima.sh)
338
339           # mount securityfs if not mounted
340           SECFS=/sys/kernel/security
341           grep -q  $SECFS /proc/mounts || mount -n -t securityfs securityfs $SECFS
342
343           # search for IMA trusted keyring, then for untrusted
344           ima_id="`awk '/\.ima/ { printf "%d", "0x"$1; }' /proc/keys`"
345           if [ -z "$ima_id" ]; then
346               ima_id=`keyctl search @u keyring _ima 2>/dev/null`
347               if [ -z "$ima_id" ]; then
348                   ima_id=`keyctl newring _ima @u`
349               fi
350           fi
351           # import IMA X509 certificate
352           evmctl import /etc/keys/x509_ima.der $ima_id
353
354           # search for EVM keyring
355           evm_id=`keyctl search @u keyring _evm 2>/dev/null`
356           if [ -z "$evm_id" ]; then
357               evm_id=`keyctl newring _evm @u`
358           fi
359           # import EVM X509 certificate
360           evmctl import /etc/keys/x509_evm.der $evm_id
361
362           # a) import EVM encrypted key
363           cat /etc/keys/kmk | keyctl padd user kmk @u
364           keyctl add encrypted evm-key "load `cat /etc/keys/evm-key`" @u
365           # OR
366           # b) import EVM trusted key
367           keyctl add trusted kmk "load `cat /etc/keys/kmk`" @u
368           keyctl add encrypted evm-key "load `cat /etc/keys/evm-key`" @u
369
370           # enable EVM
371           echo "1" > /sys/kernel/security/evm
372
373       Optionally it is possible also to forbid adding, removing of new public
374       keys and certificates into keyrings and revoking keys using keyctl
375       setperm command:
376
377           # protect EVM keyring
378           keyctl setperm $evm_id 0x0b0b0000
379           # protect IMA keyring
380           keyctl setperm $ima_id 0x0b0b0000
381           # protecting IMA key from revoking (against DoS)
382           ima_key=`evmctl import /etc/keys/x509_ima.der $ima_id`
383           keyctl setperm $ima_key 0x0b0b0000
384
385       When using plain RSA public keys in PEM format, use evmctl import --rsa
386       for importing keys:
387
388           evmctl import --rsa /etc/keys/pubkey_evm.pem $evm_id
389
390       Latest version of keyctl allows to import X509 public key certificates:
391
392           cat /etc/keys/x509_ima.der | keyctl padd asymmetric '' $ima_id
393

FILES

395       Examples of scripts to generate X509 public key certificates:
396
397           /usr/share/doc/ima-evm-utils/ima-genkey-self.sh
398           /usr/share/doc/ima-evm-utils/ima-genkey.sh
399           /usr/share/doc/ima-evm-utils/ima-gen-local-ca.sh
400

AUTHOR

402       Written by Dmitry Kasatkin, <dmitry.kasatkin at gmail.com> and others.
403

RESOURCES

405           http://sourceforge.net/p/linux-ima/wiki/Home
406           http://sourceforge.net/p/linux-ima/ima-evm-utils
407

COPYING

409       Copyright (C) 2012 - 2014 Linux Integrity Project. Free use of this
410       software is granted under the terms of the GNU Public License (GPL).
411
412
413
414                                  01/19/2023                         EVMCTL(1)
Impressum