| 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 |
|