Update README/man page documentation

Add more info on:
* introduction
* EVM formats
* Signature and keys formats
* IMA trusted keys and keyrings
* EVM trusted keys
* Updated scripts and examples

Signed-off-by: Dmitry Kasatkin <d.kasatkin@samsung.com>

README

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