diff options
Diffstat (limited to 'meta-integrity/README.md')
| -rw-r--r-- | meta-integrity/README.md | 253 |
1 files changed, 253 insertions, 0 deletions
diff --git a/meta-integrity/README.md b/meta-integrity/README.md new file mode 100644 index 0000000..ba96d8e --- /dev/null +++ b/meta-integrity/README.md @@ -0,0 +1,253 @@ +This README file contains information on the contents of the +integrity layer. + +Please see the corresponding sections below for details. + + +Dependencies +============ + +This layer depends on: + + URI: git://git.openembedded.org/bitbake + branch: master + + URI: git://git.openembedded.org/openembedded-core + layers: meta + branch: master + + URI: git://github.com/01org/meta-security/meta-integrate + layers: security-framework + branch: master + + +Patches +======= + +Please submit any patches against the integrity layer via Github +pull requests. + +For discussion or patch submission via email, use the +yocto@yoctoproject.org mailing list. When submitting patches that way, +make sure to copy the maintainer and add a "[meta-]" +prefix to the subject of the mails. + +Maintainer: Armin Kuster <akuster808@gmail.com> + + +Table of Contents +================= + +1. Adding the integrity layer to your build +2. Usage +3. Known Issues + + +1. Adding the integrity layer to your build +=========================================== + +In order to use this layer, you need to make the build system aware of +it. + +Assuming the security repository exists at the top-level of your +yocto build tree, you can add it to the build system by adding the +location of the integrity layer to bblayers.conf, along with any +other layers needed. e.g.: + + BBLAYERS ?= " \ + /path/to/yocto/meta \ + /path/to/yocto/meta-yocto \ + /path/to/yocto/meta-yocto-bsp \ + /path/to/yocto/meta-security/meta-integrity \ + " + +It has some dependencies on a suitable BSP; in particular the kernel +must have a recent enough IMA/EVM subsystem. The layer was tested with +Linux 3.19 and uses some features (like loading X509 certificates +directly from the kernel) which were added in that release. Your +mileage may vary with older kernels. + +The necessary kernel configuration parameters are added to all kernel +versions by this layer. Watch out for QA warnings about unused kernel +configuration parameters: those indicate that the kernel used by the BSP +does not have the necessary IMA/EVM features. + +Adding the layer only enables IMA (see below regarding EVM) during +compilation of the Linux kernel. To also activate it when building +the image, enable image signing in the local.conf like this: + + INHERIT += "ima-evm-rootfs" + IMA_EVM_KEY_DIR = "${IMA_EVM_BASE}/data/debug-keys" + +This uses the default keys provided in the "data" directory of the layer. +Because everyone has access to these private keys, such an image +should never be used in production! + +For that, create your own keys first. All tools and scripts required +for that are included in the layer. This is also how the +``debug-keys`` were generated: + + # Choose a directory for storing keys. Preserve this + # across builds and keep its private keys secret! + export IMA_EVM_KEY_DIR=/tmp/imaevm + mkdir -p $IMA_EVM_KEY_DIR + # Build the required tools. + bitbake openssl-native + # Set up shell for use of the tools. + bitbake -c devshell openssl-native + cd $IMA_EVM_KEY_DIR + # In that shell, create the keys. Several options exist: + + # 1. Self-signed keys. + $IMA_EVM_BASE/scripts/ima-gen-self-signed.sh + + # 2. Keys signed by a new CA. + # When asked for a PEM passphrase, that will be for the root CA. + # Signing images then will not require entering that passphrase, + # only creating new certificates does. Most likely the default + # attributes for these certificates need to be adapted; modify + # the scripts as needed. + # $IMA_EVM_BASE/scripts/ima-gen-local-ca.sh + # $IMA_EVM_BASE/scripts/ima-gen-CA-signed.sh + + # 3. Keys signed by an existing CA. + # $IMA_EVM_BASE/scripts/ima-gen-CA-signed.sh <CA.pem> <CA.priv> + exit + +When using ``ima-self-signed.sh`` as described above, self-signed keys +are created. Alternatively, one can also use keys signed by a CA. The +``ima-gen-local-ca.sh`` and ``ima-gen.sh`` scripts create a root CA +and sign the signing keys with it. The ``ima-evm-rootfs.bbclass`` then +supports adding tha CA's public key to the kernel's system keyring by +compiling it directly into the kernel. Because it is unknown whether +that is necessary (for example, the CA might also get added to the +system key ring via UEFI Secure Boot), one has to enable compilation +into the kernel explicitly in a local.conf with: + + IMA_EVM_ROOT_CA = "<path to .x509 file, for example the ima-local-ca.x509 created by ima-gen-local-ca.sh>" + + + + +To use the personal keys, override the default IMA_EVM_KEY_DIR in your +local.conf and/or override the individual variables from +ima-evm-rootfs.bbclass: + + IMA_EVM_KEY_DIR = "<full path>" + IMA_EVM_PRIVKEY = "<some other path/privkey_ima.pem>" + +By default, the entire file system gets signed. When using a policy which +does not require that, the set of files to be labelled can be chosen +by overriding the default "find" expression, for example like this: + + IMA_EVM_ROOTFS_FILES = "usr sbin bin lib -type f" + + +2. Usage +======== + +After creating an image with IMA/EVM enabled, one needs to enable +the built-in policies before IMA/EVM is active at runtime. To do this, +add one or both of these boot parameters: + + ima_tcb # measures all files read as root and all files executed + ima_appraise_tcb # appraises all files owned by root, beware of + # the known issue mentioned below + +Instead of booting with default policies, one can also activate custom +policies in different ways. First, boot without any IMA policy and +then cat a policy file into +`/sys/kernel/security/ima/policy`. This can only be done once +after booting and is useful for debugging. + +In production, the long term goal is to load a verified policy +directly from the kernel, using a patch which still needs to be +included upstream ("ima: load policy from the kernel", +<https://lwn.net/Articles/595759/>). + +Loading via systemd also works with systemd, but is considered less +secure (policy file is not checked before activating it). Beware that +IMA policy loading became broken in systemd 2.18. The modified systemd +2.19 in meta-security-smack has a patch reverting the broken +changes. To activate policy loading via systemd, place a policy file +in `/etc/ima/ima-policy`, for example with: + + IMA_EVM_POLICY_SYSTEMD = "${IMA_EVM_BASE}/data/ima_policy_simple" + +To check that measuring works, look at `/sys/kernel/security/ima/ascii_runtime_measurements` + +To check that appraisal works, try modifying executables and ensure +that executing them fails: + + echo "foobar" >>/usr/bin/rpm + evmctl ima_verify /usr/bin/rpm + rpm --version + +Depending on the current appraisal policy, the `echo` command may +already fail because writing is not allowed. If the file was modified +and the current appraisal policy allows reading, then `evmctl` will +report (the errno value seems to be printed always and is unrelated to +the actual verification failure here): + + Verification failed: 35 + errno: No such file or directory (2) + +After enabling a suitable IMA appraisal policy, reading and/or +executing the file is no longer allowed: + + # evmctl ima_verify /usr/bin/rpm + Failed to open: /usr/bin/rpm + errno: Permission denied (13) + # rpm --version + -sh: /usr/bin/rpm: Permission denied + +Enabling the audit kernel subsystem may help to debug appraisal +issues. Enable it by adding the meta-security-framework layer and +changing your local.conf: + SRC_URI_append_pn-linux-yocto = " file://audit.cfg" + CORE_IMAGE_EXTRA_INSTALL += "auditd" + +Then boot with "ima_appraise=log ima_appraise_tcb". + +Adding auditd is not strictly necessary but helps to capture a +more complete set of events in /var/log/audit/ and search in +them with ausearch. + + +3. Known Issues +=============== + +EVM is not enabled, for multiple reasons: +* Signing files in advance with a X509 certificate and then not having + any confidential keys on the device would be the most useful mode, + but is not supported by EVM [1]. +* EVM signing in advance would only work on the final file system and thus + will require further integration work with image creation. The content + of the files can be signed for IMA in the rootfs, with the extended + attributes remaining valid when copying the files to the final image. + But for EVM that copy operation changes relevant parameters (for example, + inode) and thus invalidates the EVM hash. +* On device creation of EVM hashes depends on secure key handling on the + device (TPM) and booting at least once in a special mode (file system + writable, evm=fix as boot parameter, reboot after opening all files); + such a mode is too device specific to be implemented in a generic way. + +IMA appraisal with "ima_appraise_tcb" enables rules which are too strict +for most distros. For example, systemd needs to write certain files +as root, which is prevented by the ima_appraise_tcb appraise rules. As +a result, the system fails to boot: + + [FAILED] Failed to start Commit a transient machine-id on disk. + See "systemctl status systemd-machine-id-commit.service" for details. + ... + [FAILED] Failed to start Network Service. + See "systemctl status systemd-networkd.service" for details. + [FAILED] Failed to start Login Service. + See "systemctl status systemd-logind.service" for details. + +No package manager is integrated with IMA/EVM. When updating packages, +files will end up getting installed without correct IMA/EVM attributes +and thus will not be usable when appraisal is turned on. + +[1] http://permalink.gmane.org/gmane.comp.handhelds.tizen.devel/6281 +[2] http://permalink.gmane.org/gmane.comp.handhelds.tizen.devel/6275 |