+ima-evm-utils - IMA/EVM signing utility
+=========================================
-1. Generate private key
+Contents:
-# plain key
-openssl genrsa -out privkey_evm.pem 1024
+ 1. Key and signature formats
+ 2. Key generation
+ 3. Initialization
+ 4. Signing
-# encrypted key
-openssl genrsa -des3 -out privkey_evm.pem 1024
-# set password for the key
-openssl rsa -in /etc/keys/privkey_evm.pem -out privkey_evm_enc.pem -des3
-or
-openssl pkcs8 -topk8 -in /etc/keys/privkey_evm.pem -out privkey_evm_enc.pem
+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
-2. Generate public key
+ $ openssl genrsa -des3 -out privkey_evm.pem 1024
-openssl rsa -pubout -in privkey_evm.pem -out pubkey_evm.pem
+Make encrypted private key from unencrypted
-3. Copy public (+private if to sign on device) key to the device/qemu /etc/keys
+ $ openssl rsa -in /etc/keys/privkey_evm.pem -out privkey_evm_enc.pem -des3
-scp pubkey_evm.pem mad:/etc/keys
+Generate self-signed X509 certificate and private key for using kernel asymmetric
+keys support
-4. Load keys and enable EVM
+ $ openssl req -new -nodes -utf8 -sha1 -days 36500 -batch \
+ -x509 -config x509_evm.genkey \
+ -outform DER -out x509_evm.der -keyout privkey_evm.pem
-evm_enable.sh
+Configuration file x509_evm.genkey:
-This should be done at early phase, before mounting root filesystem.
+ # Begining of the file
+ [ req ]
+ default_bits = 1024
+ distinguished_name = req_distinguished_name
+ prompt = no
+ string_mask = utf8only
+ x509_extensions = myexts
-5. Sign EVM and use hash value for IMA - common case
+ [ req_distinguished_name ]
+ O = Magrathea
+ CN = Glacier signing key
+ emailAddress = slartibartfast@magrathea.h2g2
-evmctl sign --imahash test.txt
+ [ myexts ]
+ basicConstraints=critical,CA:FALSE
+ keyUsage=digitalSignature
+ subjectKeyIdentifier=hash
+ authorityKeyIdentifier=keyid
+ # EOF
-6. Sign IMA and EVM - for immutable files and modules
-evmctl sign --imasig test.txt
+Get public key
-7. Sign whole filesystem
+ $ 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
-evm_sign_all.sh
or
-find / \( -fstype rootfs -o -fstype ext3 -o -fstype ext4 \) ! -path "/lib/modules/*" -type f -uid 0 -exec evmctl sign --imahash '{}' \;
-find /lib/modules ! -name "*.ko" -type f -uid 0 -exec evmctl sign --imahash '{}' \;
-# security.ima needs to have signature for modules
-find /lib/modules -name "*.ko" -type f -uid 0 -exec evmctl sign --imasig '{}' \;
+ $ 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
-# generate signatures in .sig files
-find /lib/modules -name "*.ko" -type f -uid 0 -exec evmctl -n --sigfile ima_sign '{}' \;
+ $ find / \( -fstype rootfs -o -fstype ext4 \) -exec evmctl sign [-u -] [-x] --imahash '{}' \;
-8. Label filesystem in fix mode...
+Label filesystem in fix mode - kernel sets correct values to IMA and EVM xattrs
-ima_fix_dir.sh <dir>
+ $ find / \( -fstype rootfs -o -fstype ext4 \) -exec sh -c "< '{}'" \;
projects / platform / upstream / ima-evm-utils.git / blobdiff