'\" t
.\"     Title: evmctl
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 05/06/2020
.\"    Manual: \ \&
.\"    Source: \ \&
.\"  Language: English
.\"
.TH "EVMCTL" "1" "05/06/2020" "\ \&" "\ \&"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
evmctl \- IMA/EVM signing utility
.SH "SYNOPSIS"
.sp
evmctl [options] <command> [OPTIONS]
.SH "DESCRIPTION"
.sp
The evmctl utility can be used for producing and verifying digital signatures, which are used by Linux kernel integrity subsystem (IMA/EVM)\&. It can be also used to import keys into the kernel keyring\&.
.SH "COMMANDS"
.sp
.if n \{\
.RS 4
.\}
.nf
\-\-version
help <command>
import [\-\-rsa] pubkey keyring
sign [\-r] [\-\-imahash | \-\-imasig ] [\-\-portable] [\-\-key key] [\-\-pass password] file
verify file
ima_sign [\-\-sigfile] [\-\-key key] [\-\-pass password] file
ima_verify file
ima_hash file
ima_measurement [\-\-key "key1, key2, \&.\&.\&."] [\-\-list] file
ima_fix [\-t fdsxm] path
sign_hash [\-\-key key] [\-\-pass password]
hmac [\-\-imahash | \-\-imasig ] file
.fi
.if n \{\
.RE
.\}
.SH "OPTIONS"
.sp
.if n \{\
.RS 4
.\}
.nf
\-a, \-\-hashalgo     sha1 (default), sha224, sha256, sha384, sha512
\-s, \-\-imasig       make IMA signature
\-d, \-\-imahash      make IMA hash
\-f, \-\-sigfile      store IMA signature in \&.sig file instead of xattr
    \-\-rsa          use RSA key type and signing scheme v1
\-k, \-\-key          path to signing key (default: /etc/keys/{privkey,pubkey}_evm\&.pem)
\-o, \-\-portable     generate portable EVM signatures
\-p, \-\-pass         password for encrypted signing key
\-r, \-\-recursive    recurse into directories (sign)
\-t, \-\-type         file types to fix \*(Aqfdsxm\*(Aq (f: file, d: directory, s: block/char/symlink)
                   x \- skip fixing if both ima and evm xattrs exist (use with caution)
                   m \- stay on the same filesystem (like \*(Aqfind \-xdev\*(Aq)
\-n                 print result to stdout instead of setting xattr
\-u, \-\-uuid         use custom FS UUID for EVM (unspecified: from FS, empty: do not use)
    \-\-smack        use extra SMACK xattrs for EVM
    \-\-m32          force EVM hmac/signature for 32 bit target system
    \-\-m64          force EVM hmac/signature for 64 bit target system
\-v                 increase verbosity level
\-h, \-\-help         display this help and exit
.fi
.if n \{\
.RE
.\}
.SH "INTRODUCTION"
.sp
Linux kernel integrity subsystem is comprised of a number of different components including the Integrity Measurement Architecture (IMA), Extended Verification Module (EVM), IMA\-appraisal extension, digital signature verification extension and audit measurement log support\&.
.sp
The evmctl utility is used for producing and verifying digital signatures, which are used by the Linux kernel integrity subsystem\&. It is also used for importing keys into the kernel keyring\&.
.sp
Linux integrity subsystem allows to use IMA and EVM signatures\&. EVM signature protects file metadata, such as file attributes and extended attributes\&. IMA signature protects file content\&.
.sp
For more detailed information about integrity subsystem it is recommended to follow resources in RESOURCES section\&.
.SH "EVM HMAC AND SIGNATURE METADATA"
.sp
EVM protects file metadata by including following attributes into HMAC and signature calculation: inode number, inode generation, UID, GID, file mode, security\&.selinux, security\&.SMACK64, security\&.ima, security\&.capability\&.
.sp
EVM HMAC and signature in may also include additional file and file system attributes\&. Currently supported additional attributes are filesystem UUID and extra SMACK extended attributes\&.
.sp
Kernel configuration option CONFIG_EVM_ATTR_FSUUID controls whether to include filesystem UUID into HMAC and enabled by default\&. Therefore evmctl also includes fsuuid by default\&. Providing \fI\-\-uuid\fR option without parameter allows to disable usage of fs uuid\&. Providing \fI\-\-uuid=UUID\fR option with parameter allows to use custom UUID\&. Providing the \fI\-\-portable\fR option will disable usage of the fs uuid and also the inode number and generation\&.
.sp
Kernel configuration option CONFIG_EVM_EXTRA_SMACK_XATTRS controls whether to include additional SMACK extended attributes into HMAC\&. They are following: security\&.SMACK64EXEC, security\&.SMACK64TRANSMUTE and security\&.SMACK64MMAP\&. evmctl \fI\-\-smack\fR options enables that\&.
.SH "KEY AND SIGNATURE FORMATS"
.sp
Linux integrity subsystem supports two type of signature and respectively two key formats\&.
.sp
First key format (v1) is pure RSA key encoded in PEM a format and uses own signature format\&. It is now non\-default format and requires to provide evmctl \fI\-\-rsa\fR option for signing and importing the key\&.
.sp
Second key format uses X509 DER encoded public key certificates and uses asymmetric key support in the kernel (since kernel 3\&.9)\&. CONFIG_INTEGRITY_ASYMMETRIC_KEYS must be enabled (default)\&.
.SH "INTEGRITY KEYRINGS"
.sp
Integrity subsystem uses dedicated IMA/EVM keyrings to search for signature verification keys \- \fI_ima\fR and \fI_evm\fR respectively\&.
.sp
Since 3\&.13 IMA allows to declare IMA keyring as trusted\&. It allows only to load keys, signed by a key from the system keyring (\&.system)\&. It means self\-signed keys are not allowed\&. This is a default behavior unless CONFIG_IMA_TRUSTED_KEYRING is undefined\&. IMA trusted keyring is has different name \fI\&.ima\fR\&. Trusted keyring requires X509 public key certificates\&. Old version RSA public keys are not compatible with trusted keyring\&.
.SH "GENERATE EVM ENCRYPTED KEYS"
.sp
EVM encrypted key is used for EVM HMAC calculation:
.sp
.if n \{\
.RS 4
.\}
.nf
# create and save the key kernel master key (user type)
# LMK is used to encrypt encrypted keys
keyctl add user kmk "`dd if=/dev/urandom bs=1 count=32 2>/dev/null`" @u
keyctl pipe `keyctl search @u user kmk` > /etc/keys/kmk
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
# create the EVM encrypted key
keyctl add encrypted evm\-key "new user:kmk 64" @u
keyctl pipe `keyctl search @u encrypted evm\-key` >/etc/keys/evm\-key
.fi
.if n \{\
.RE
.\}
.SH "GENERATE EVM TRUSTED KEYS (TPM BASED)"
.sp
Trusted EVM keys are keys which a generate with the help of TPM\&. They are not related to integrity trusted keys\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# create and save the key kernel master key (user type)
keyctl add trusted kmk "new 32" @u
keyctl pipe `keyctl search @u trusted kmk` >kmk
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
# create the EVM trusted key
keyctl add encrypted evm\-key "new trusted:kmk 32" @u
keyctl pipe `keyctl search @u encrypted evm\-key` >evm\-key
.fi
.if n \{\
.RE
.\}
.SH "GENERATE SIGNING AND VERIFICATION KEYS"
.sp
Generate private key in plain text format:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl genrsa \-out privkey_evm\&.pem 1024
.fi
.if n \{\
.RE
.\}
.sp
Generate encrypted private key:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl genrsa \-des3 \-out privkey_evm\&.pem 1024
.fi
.if n \{\
.RE
.\}
.sp
Make encrypted private key from unencrypted:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl rsa \-in /etc/keys/privkey_evm\&.pem \-out privkey_evm_enc\&.pem \-des3
.fi
.if n \{\
.RE
.\}
.sp
Generate self\-signed X509 public key certificate and private key for using kernel asymmetric keys support:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl req \-new \-nodes \-utf8 \-sha1 \-days 36500 \-batch \e
            \-x509 \-config x509_evm\&.genkey \e
            \-outform DER \-out x509_evm\&.der \-keyout privkey_evm\&.pem
.fi
.if n \{\
.RE
.\}
.sp
Configuration file x509_evm\&.genkey:
.sp
.if n \{\
.RS 4
.\}
.nf
# Begining of the file
[ req ]
default_bits = 1024
distinguished_name = req_distinguished_name
prompt = no
string_mask = utf8only
x509_extensions = myexts
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[ req_distinguished_name ]
O = Magrathea
CN = Glacier signing key
emailAddress = slartibartfast@magrathea\&.h2g2
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[ myexts ]
basicConstraints=critical,CA:FALSE
keyUsage=digitalSignature
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid
# EOF
.fi
.if n \{\
.RE
.\}
.sp
Generate public key for using RSA key format:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl rsa \-pubout \-in privkey_evm\&.pem \-out pubkey_evm\&.pem
.fi
.if n \{\
.RE
.\}
.sp
Copy keys to /etc/keys:
.sp
.if n \{\
.RS 4
.\}
.nf
   cp pubkey_evm\&.pem /etc/keys
   scp pubkey_evm\&.pem target:/etc/keys
or
   cp x509_evm\&.pem /etc/keys
   scp x509_evm\&.pem target:/etc/keys
.fi
.if n \{\
.RE
.\}
.SH "GENERATE TRUSTED KEYS"
.sp
Generation of trusted keys is a bit more complicated process and involves following steps:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Creation of local IMA certification authority (CA)\&. It consist of private and public key certificate which are used to sign and verify other keys\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Build Linux kernel with embedded local IMA CA X509 certificate\&. It is used to verify other keys added to the
\fI\&.ima\fR
trusted keyring
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Generate IMA private signing key and verification public key certificate, which is signed using local IMA CA private key\&.
.RE
.sp
Configuration file ima\-local\-ca\&.genkey:
.sp
.if n \{\
.RS 4
.\}
.nf
# Begining of the file
[ req ]
default_bits = 2048
distinguished_name = req_distinguished_name
prompt = no
string_mask = utf8only
x509_extensions = v3_ca
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[ req_distinguished_name ]
O = IMA\-CA
CN = IMA/EVM certificate signing key
emailAddress = ca@ima\-ca
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[ v3_ca ]
basicConstraints=CA:TRUE
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer
# keyUsage = cRLSign, keyCertSign
# EOF
.fi
.if n \{\
.RE
.\}
.sp
Generate private key and X509 public key certificate:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl req \-new \-x509 \-utf8 \-sha1 \-days 3650 \-batch \-config $GENKEY \e
            \-outform DER \-out ima\-local\-ca\&.x509 \-keyout ima\-local\-ca\&.priv
.fi
.if n \{\
.RE
.\}
.sp
Produce X509 in DER format for using while building the kernel:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl x509 \-inform DER \-in ima\-local\-ca\&.x509 \-out ima\-local\-ca\&.pem
.fi
.if n \{\
.RE
.\}
.sp
Configuration file ima\&.genkey:
.sp
.if n \{\
.RS 4
.\}
.nf
# Begining of the file
[ req ]
default_bits = 1024
distinguished_name = req_distinguished_name
prompt = no
string_mask = utf8only
x509_extensions = v3_usr
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[ req_distinguished_name ]
O = `hostname`
CN = `whoami` signing key
emailAddress = `whoami`@`hostname`
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
[ v3_usr ]
basicConstraints=critical,CA:FALSE
#basicConstraints=CA:FALSE
keyUsage=digitalSignature
#keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid
#authorityKeyIdentifier=keyid,issuer
# EOF
.fi
.if n \{\
.RE
.\}
.sp
Generate private key and X509 public key certificate signing request:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl req \-new \-nodes \-utf8 \-sha1 \-days 365 \-batch \-config $GENKEY \e
            \-out csr_ima\&.pem \-keyout privkey_ima\&.pem
.fi
.if n \{\
.RE
.\}
.sp
Sign X509 public key certificate signing request with local IMA CA private key:
.sp
.if n \{\
.RS 4
.\}
.nf
openssl x509 \-req \-in csr_ima\&.pem \-days 365 \-extfile $GENKEY \-extensions v3_usr \e
             \-CA ima\-local\-ca\&.pem \-CAkey ima\-local\-ca\&.priv \-CAcreateserial \e
             \-outform DER \-out x509_ima\&.der
.fi
.if n \{\
.RE
.\}
.SH "SIGN FILE DATA AND METADATA"
.sp
Default key locations:
.sp
.if n \{\
.RS 4
.\}
.nf
Private RSA key: /etc/keys/privkey_evm\&.pem
Public RSA key: /etc/keys/pubkey_evm\&.pem
X509 certificate: /etc/keys/x509_evm\&.der
.fi
.if n \{\
.RE
.\}
.sp
Options to remember: \fI\-k\fR, \fI\-r\fR, \fI\-\-rsa\fR, \fI\-\-uuid\fR, \fI\-\-smack\fR\&.
.sp
Sign file with EVM signature and calculate hash value for IMA:
.sp
.if n \{\
.RS 4
.\}
.nf
evmctl sign \-\-imahash test\&.txt
.fi
.if n \{\
.RE
.\}
.sp
Sign file with both IMA and EVM signatures:
.sp
.if n \{\
.RS 4
.\}
.nf
evmctl sign \-\-imasig test\&.txt:
.fi
.if n \{\
.RE
.\}
.sp
Sign file with IMA signature:
.sp
.if n \{\
.RS 4
.\}
.nf
evmctl ima_sign test\&.txt
.fi
.if n \{\
.RE
.\}
.sp
Sign recursively whole filesystem:
.sp
.if n \{\
.RS 4
.\}
.nf
evmctl \-r sign \-\-imahash /
.fi
.if n \{\
.RE
.\}
.sp
Fix recursively whole filesystem:
.sp
.if n \{\
.RS 4
.\}
.nf
evmctl \-r ima_fix /
.fi
.if n \{\
.RE
.\}
.sp
Sign filesystem selectively using \fIfind\fR command:
.sp
.if n \{\
.RS 4
.\}
.nf
find / \e( \-fstype rootfs \-o \-fstype ext4 \e) \-exec evmctl sign \-\-imahash \*(Aq{}\*(Aq \e;
.fi
.if n \{\
.RE
.\}
.sp
Fix filesystem selectively using \fIfind\fR command:
.sp
.if n \{\
.RS 4
.\}
.nf
find / \e( \-fstype rootfs \-o \-fstype ext4 \e) \-exec sh \-c "< \*(Aq{}\*(Aq" \e;
.fi
.if n \{\
.RE
.\}
.SH "INITIALIZE IMA/EVM AT EARLY BOOT"
.sp
IMA/EVM initialization should be normally done from initial RAM file system before mounting root filesystem\&.
.sp
Here is Ubuntu initramfs example script (/etc/initramfs\-tools/scripts/local\-top/ima\&.sh)
.sp
.if n \{\
.RS 4
.\}
.nf
# mount securityfs if not mounted
SECFS=/sys/kernel/security
grep \-q  $SECFS /proc/mounts || mount \-n \-t securityfs securityfs $SECFS
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
# search for IMA trusted keyring, then for untrusted
ima_id="`awk \*(Aq/\e\&.ima/ { printf "%d", "0x"$1; }\*(Aq /proc/keys`"
if [ \-z "$ima_id" ]; then
    ima_id=`keyctl search @u keyring _ima 2>/dev/null`
    if [ \-z "$ima_id" ]; then
        ima_id=`keyctl newring _ima @u`
    fi
fi
# import IMA X509 certificate
evmctl import /etc/keys/x509_ima\&.der $ima_id
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
# search for EVM keyring
evm_id=`keyctl search @u keyring _evm 2>/dev/null`
if [ \-z "$evm_id" ]; then
    evm_id=`keyctl newring _evm @u`
fi
# import EVM X509 certificate
evmctl import /etc/keys/x509_evm\&.der $evm_id
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
# a) import EVM encrypted key
cat /etc/keys/kmk | keyctl padd user kmk @u
keyctl add encrypted evm\-key "load `cat /etc/keys/evm\-key`" @u
# OR
# b) import EVM trusted key
keyctl add trusted kmk "load `cat /etc/keys/kmk`" @u
keyctl add encrypted evm\-key "load `cat /etc/keys/evm\-key`" @u
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.RS 4
.\}
.nf
# enable EVM
echo "1" > /sys/kernel/security/evm
.fi
.if n \{\
.RE
.\}
.sp
Optionally it is possible also to forbid adding, removing of new public keys and certificates into keyrings and revoking keys using \fIkeyctl setperm\fR command:
.sp
.if n \{\
.RS 4
.\}
.nf
# protect EVM keyring
keyctl setperm $evm_id 0x0b0b0000
# protect IMA keyring
keyctl setperm $ima_id 0x0b0b0000
# protecting IMA key from revoking (against DoS)
ima_key=`evmctl import /etc/keys/x509_ima\&.der $ima_id`
keyctl setperm $ima_key 0x0b0b0000
.fi
.if n \{\
.RE
.\}
.sp
When using plain RSA public keys in PEM format, use \fIevmctl import \-\-rsa\fR for importing keys:
.sp
.if n \{\
.RS 4
.\}
.nf
evmctl import \-\-rsa /etc/keys/pubkey_evm\&.pem $evm_id
.fi
.if n \{\
.RE
.\}
.sp
Latest version of keyctl allows to import X509 public key certificates:
.sp
.if n \{\
.RS 4
.\}
.nf
cat /etc/keys/x509_ima\&.der | keyctl padd asymmetric \*(Aq\*(Aq $ima_id
.fi
.if n \{\
.RE
.\}
.SH "FILES"
.sp
Examples of scripts to generate X509 public key certificates:
.sp
.if n \{\
.RS 4
.\}
.nf
/usr/share/doc/ima\-evm\-utils/ima\-genkey\-self\&.sh
/usr/share/doc/ima\-evm\-utils/ima\-genkey\&.sh
/usr/share/doc/ima\-evm\-utils/ima\-gen\-local\-ca\&.sh
.fi
.if n \{\
.RE
.\}
.SH "AUTHOR"
.sp
Written by Dmitry Kasatkin, <dmitry\&.kasatkin at gmail\&.com> and others\&.
.SH "RESOURCES"
.sp
.if n \{\
.RS 4
.\}
.nf
http://sourceforge\&.net/p/linux\-ima/wiki/Home
http://sourceforge\&.net/p/linux\-ima/ima\-evm\-utils
.fi
.if n \{\
.RE
.\}
.SH "COPYING"
.sp
Copyright (C) 2012 \- 2014 Linux Integrity Project\&. Free use of this software is granted under the terms of the GNU Public License (GPL)\&.