Blame README

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