README

   1 ima-evm-utils - IMA/EVM signing utility
   2 =========================================
   3
   4 Contents:
   5
   6
   7    1. Key and signature formats
   8    2. Key generation
   9    3. Initialization
  10    4. Signing
  11
  12
  13 Key and signature formats
  14 -------------------------
  15
  16 EVM support (v2) in latest version of the kernel adds the file system UUID to
  17 the HMAC calculation. It is controlled by the CONFIG_EVM_HMAC_VERSION and
  18 version 2 is enabled by default. To include the UUID to the signature calculation,
  19 it is necessary to provide '--uuid -' or '-u -' parameter to the 'sign' command.
  20
  21 Key generation
  22 --------------
  23
  24 Generate private key in plain text format
  25
  26     $ openssl genrsa -out privkey_evm.pem 1024
  27
  28 Generate encrypted private key
  29
  30     $ openssl genrsa -des3 -out privkey_evm.pem 1024
  31
  32 Make encrypted private key from unencrypted
  33
  34     $ openssl rsa -in /etc/keys/privkey_evm.pem -out privkey_evm_enc.pem -des3
  35
  36 Get public key
  37
  38     $ openssl rsa -pubout -in privkey_evm.pem -out pubkey_evm.pem
  39
  40 Copy keys to /etc/keys
  41
  42     $ cp pubkey_evm.pem /etc/keys
  43     $ scp pubkey_evm.pem target:/etc/keys
  44
  45
  46 Initialization
  47 --------------
  48
  49 IMA/EVM initialization should be normally done from initial RAM file system
  50 before mounting root filesystem.
  51
  52 Here is an example script /etc/initramfs-tools/scripts/local-top/ima.sh
  53
  54     # import EVM HMAC key
  55     keyctl clear @u
  56     keyctl add user kmk "testing123" @u
  57     keyctl add encrypted evm-key "load `cat /etc/keys/evm-key`" @u
  58
  59     # import IMA public key
  60     ima_id=`keyctl newring _ima @u`
  61     evmctl import /etc/keys/pubkey_evm.pem $ima_id
  62
  63     # import EVM public key
  64     evm_id=`keyctl newring _evm @u`
  65     evmctl import /etc/keys/pubkey_evm.pem $evm_id
  66
  67     # enable EVM
  68     echo "1" > /sys/kernel/security/evm
  69
  70
  71 Signing
  72 -------
  73
  74 Signing for using new the EVM HMAC format is done using '-u -' or '--uuid -' parameter.
  75
  76 Sign file with EVM signature and use hash value for IMA - common case
  77
  78     $ evmctl sign [-u -] --imahash test.txt
  79
  80 Sign file with both IMA and EVM signatures - for immutable files
  81
  82     $ evmctl sign [-u -] --imasig test.txt
  83
  84 Label whole filesystem with EVM signatures
  85
  86     $ find / \( -fstype rootfs -o -fstype ext4 \) -exec evmctl sign [-u -] --imahash '{}' \;
  87
  88 Label filesystem in fix mode - kernel sets correct values to IMA and EVM xattrs
  89
  90     $ find / \( -fstype rootfs -o -fstype ext4 \) -exec sh -c "< '{}'" \;
  91