README

   1 ima-evm-utils - IMA/EVM signing utility
   2 =========================================
   3
   4 Contents:
   5
   6    1. Key and signature formats
   7    2. Key generation
   8    3. Initialization
   9    4. Signing
  10
  11
  12 Key and signature formats
  13 -------------------------
  14
  15 EVM support (v2) in latest version of the kernel adds the file system UUID to
  16 the HMAC calculation. It is controlled by the CONFIG_EVM_HMAC_VERSION and
  17 version 2 is enabled by default. To include the UUID to the signature calculation,
  18 it is necessary to provide '--uuid -' or '-u -' parameter to the 'sign' command.
  19
  20 Latest kernel got IMA/EVM support for using X509 certificates and asymmetric key
  21 support for verifying digital signatures. The new command line parameter
  22 '-x' or '--x509' was added to the evmctl to enable using of X509 certificates
  23 and new signature format.
  24
  25
  26 Key generation
  27 --------------
  28
  29 Generate private key in plain text format
  30
  31     $ openssl genrsa -out privkey_evm.pem 1024
  32
  33 Generate encrypted private key
  34
  35     $ openssl genrsa -des3 -out privkey_evm.pem 1024
  36
  37 Make encrypted private key from unencrypted
  38
  39     $ openssl rsa -in /etc/keys/privkey_evm.pem -out privkey_evm_enc.pem -des3
  40
  41 Generate self-signed X509 certificate and private key for using kernel asymmetric
  42 keys support
  43
  44         $ openssl req -new -nodes -utf8 -sha1 -days 36500 -batch \
  45               -x509 -config x509_evm.genkey \
  46               -outform DER -out x509_evm.der -keyout privkey_evm.pem
  47
  48 Configuration file x509_evm.genkey:
  49
  50         # Begining of the file
  51         [ req ]
  52         default_bits = 1024
  53         distinguished_name = req_distinguished_name
  54         prompt = no
  55         string_mask = utf8only
  56         x509_extensions = myexts
  57
  58         [ req_distinguished_name ]
  59         O = Magrathea
  60         CN = Glacier signing key
  61         emailAddress = slartibartfast@magrathea.h2g2
  62
  63         [ myexts ]
  64         basicConstraints=critical,CA:FALSE
  65         keyUsage=digitalSignature
  66         subjectKeyIdentifier=hash
  67         authorityKeyIdentifier=keyid
  68         # EOF
  69
  70
  71 Get public key
  72
  73     $ openssl rsa -pubout -in privkey_evm.pem -out pubkey_evm.pem
  74
  75 Copy keys to /etc/keys
  76
  77     $ cp pubkey_evm.pem /etc/keys
  78     $ scp pubkey_evm.pem target:/etc/keys
  79
  80 or
  81     $ cp x509_evm.pem /etc/keys
  82     $ scp x509_evm.pem target:/etc/keys
  83
  84
  85 Initialization
  86 --------------
  87
  88 IMA/EVM initialization should be normally done from initial RAM file system
  89 before mounting root filesystem.
  90
  91 Here is an example script /etc/initramfs-tools/scripts/local-top/ima.sh
  92
  93     # import EVM HMAC key
  94     keyctl clear @u
  95     keyctl add user kmk "testing123" @u
  96     keyctl add encrypted evm-key "load `cat /etc/keys/evm-key`" @u
  97
  98     # import IMA public key
  99     ima_id=`keyctl newring _ima @u`
 100     evmctl import /etc/keys/pubkey_evm.pem $ima_id
 101
 102     # import EVM public key
 103     evm_id=`keyctl newring _evm @u`
 104     evmctl import /etc/keys/pubkey_evm.pem $evm_id
 105
 106     # enable EVM
 107     echo "1" > /sys/kernel/security/evm
 108
 109
 110 Import X509 certificate into the kernel keyring (since kernel 3.9?)
 111
 112     $ evmctl -x import /etc/keys/x509_evm.der `keyctl search @u keyring _ima`
 113     $ evmctl -x import /etc/keys/x509_evm.der `keyctl search @u keyring _evm`
 114
 115
 116 Signing
 117 -------
 118
 119 Default public key: /etc/keys/pubkey_evm.pem
 120 Default private key: /etc/keys/privkey_evm.pem
 121 Default X509 certificate: /etc/keys/x509_evm.der
 122
 123 Signing for using X509 certificates is done using '-x' or '--x509' parameter.
 124 Signing for using new the EVM HMAC format is done using '-u -' or '--uuid -' parameter.
 125
 126 Sign file with EVM signature and use hash value for IMA - common case
 127
 128     $ evmctl sign [-u -] [-x] --imahash test.txt
 129
 130 Sign file with both IMA and EVM signatures - for immutable files
 131
 132     $ evmctl sign [-u -] [-x] --imasig test.txt
 133
 134 Sign file with IMA signature - for immutable files
 135
 136     $ evmctl ima_sign [-x] test.txt
 137
 138 Label whole filesystem with EVM signatures
 139
 140     $ find / \( -fstype rootfs -o -fstype ext4 \) -exec evmctl sign [-u -] [-x] --imahash '{}' \;
 141
 142 Label filesystem in fix mode - kernel sets correct values to IMA and EVM xattrs
 143
 144     $ find / \( -fstype rootfs -o -fstype ext4 \) -exec sh -c "< '{}'" \;
 145