ima-evm-utils - IMA/EVM signing utility
=========================================

Contents:

   1. Key and signature formats
   2. Key generation
   3. Initialization
   4. Signing


Key and signature formats
-------------------------

EVM support (v2) in latest version of the kernel adds the file system UUID to
the HMAC calculation. It is controlled by the CONFIG_EVM_HMAC_VERSION and
version 2 is enabled by default. To include the UUID to the signature calculation,
it is necessary to provide '--uuid -' or '-u -' parameter to the 'sign' command.

Latest kernel got IMA/EVM support for using X509 certificates and asymmetric key
support for verifying digital signatures. The new command line parameter
'-x' or '--x509' was added to the evmctl to enable using of X509 certificates
and new signature format.


Key generation
--------------

Generate private key in plain text format

    $ openssl genrsa -out privkey_evm.pem 1024

Generate encrypted private key

    $ openssl genrsa -des3 -out privkey_evm.pem 1024

Make encrypted private key from unencrypted

    $ openssl rsa -in /etc/keys/privkey_evm.pem -out privkey_evm_enc.pem -des3

Generate self-signed X509 certificate and private key for using kernel asymmetric
keys support

	$ openssl req -new -nodes -utf8 -sha1 -days 36500 -batch \
	      -x509 -config x509_evm.genkey \
	      -outform DER -out x509_evm.der -keyout privkey_evm.pem

Configuration file x509_evm.genkey:

	# Begining of the file
	[ req ]
	default_bits = 1024
	distinguished_name = req_distinguished_name
	prompt = no
	string_mask = utf8only
	x509_extensions = myexts

	[ req_distinguished_name ]
	O = Magrathea
	CN = Glacier signing key
	emailAddress = slartibartfast@magrathea.h2g2

	[ myexts ]
	basicConstraints=critical,CA:FALSE
	keyUsage=digitalSignature
	subjectKeyIdentifier=hash
	authorityKeyIdentifier=keyid
	# EOF


Get public key

    $ openssl rsa -pubout -in privkey_evm.pem -out pubkey_evm.pem

Copy keys to /etc/keys

    $ 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


Initialization
--------------

IMA/EVM initialization should be normally done from initial RAM file system
before mounting root filesystem.

Here is an example script /etc/initramfs-tools/scripts/local-top/ima.sh

    # import EVM HMAC key
    keyctl clear @u
    keyctl add user kmk "testing123" @u
    keyctl add encrypted evm-key "load `cat /etc/keys/evm-key`" @u

    # import IMA public key
    ima_id=`keyctl newring _ima @u`
    evmctl import /etc/keys/pubkey_evm.pem $ima_id

    # import EVM public key
    evm_id=`keyctl newring _evm @u`
    evmctl import /etc/keys/pubkey_evm.pem $evm_id

    # enable EVM
    echo "1" > /sys/kernel/security/evm


Import X509 certificate into the kernel keyring (since kernel 3.9?)

    $ evmctl -x import /etc/keys/x509_evm.der `keyctl search @u keyring _ima`
    $ evmctl -x import /etc/keys/x509_evm.der `keyctl search @u keyring _evm`


Signing
-------

Default public key: /etc/keys/pubkey_evm.pem
Default private key: /etc/keys/privkey_evm.pem
Default X509 certificate: /etc/keys/x509_evm.der

Signing for using X509 certificates is done using '-x' or '--x509' parameter.
Signing for using new the EVM HMAC format is done using '-u -' or '--uuid -' parameter.

Sign file with EVM signature and use hash value for IMA - common case

    $ evmctl sign [-u -] [-x] --imahash test.txt

Sign file with both IMA and EVM signatures - for immutable files

    $ evmctl sign [-u -] [-x] --imasig test.txt

Sign file with IMA signature - for immutable files

    $ evmctl ima_sign [-x] test.txt

Label whole filesystem with EVM signatures

    $ find / \( -fstype rootfs -o -fstype ext4 \) -exec evmctl sign [-u -] [-x] --imahash '{}' \;

Label filesystem in fix mode - kernel sets correct values to IMA and EVM xattrs

    $ find / \( -fstype rootfs -o -fstype ext4 \) -exec sh -c "< '{}'" \;