1This README file contains information on the contents of the 2integrity layer. 3 4Please see the corresponding sections below for details. 5 6 7Dependencies 8============ 9 10This layer depends on: 11 12 URI: git://git.openembedded.org/bitbake 13 branch: master 14 15 URI: git://git.openembedded.org/openembedded-core 16 layers: meta 17 branch: master 18 19 URI: git://github.com/01org/meta-security/meta-integrate 20 layers: security-framework 21 branch: master 22 23 24Patches 25======= 26 27For discussion or patch submission via email, use the 28yocto@yoctoproject.org mailing list. When submitting patches that way, 29make sure to copy the maintainer and add a "[meta-integrity]" 30prefix to the subject of the mails. 31 32Maintainer: Armin Kuster <akuster808@gmail.com> 33 34 35Table of Contents 36================= 37 381. Adding the integrity layer to your build 392. Usage 403. Known Issues 41 42 431. Adding the integrity layer to your build 44=========================================== 45 46In order to use this layer, you need to make the build system aware of 47it. 48 49Assuming the security repository exists at the top-level of your 50yocto build tree, you can add it to the build system by adding the 51location of the integrity layer to bblayers.conf, along with any 52other layers needed. e.g.: 53 54 BBLAYERS ?= " \ 55 /path/to/yocto/meta \ 56 /path/to/yocto/meta-yocto \ 57 /path/to/yocto/meta-yocto-bsp \ 58 /path/to/yocto/meta-security/meta-integrity \ 59 " 60 61It has some dependencies on a suitable BSP; in particular the kernel 62must have a recent enough IMA/EVM subsystem. The layer was tested with 63Linux 3.19 and uses some features (like loading X509 certificates 64directly from the kernel) which were added in that release. Your 65mileage may vary with older kernels. 66 67The necessary kernel configuration parameters are added to all kernel 68versions by this layer. Watch out for QA warnings about unused kernel 69configuration parameters: those indicate that the kernel used by the BSP 70does not have the necessary IMA/EVM features. 71 72Adding the layer only enables IMA (see below regarding EVM) during 73compilation of the Linux kernel. To also activate it when building 74the image, enable image signing in the local.conf like this: 75 76 INHERIT += "ima-evm-rootfs" 77 IMA_EVM_KEY_DIR = "${INTEGRITY_BASE}/data/debug-keys" 78 79This uses the default keys provided in the "data" directory of the layer. 80Because everyone has access to these private keys, such an image 81should never be used in production! 82 83For that, create your own keys first. All tools and scripts required 84for that are included in the layer. This is also how the 85``debug-keys`` were generated: 86 87 # Choose a directory for storing keys. Preserve this 88 # across builds and keep its private keys secret! 89 export IMA_EVM_KEY_DIR=/tmp/imaevm 90 mkdir -p $IMA_EVM_KEY_DIR 91 # Build the required tools. 92 bitbake openssl-native 93 # Set up shell for use of the tools. 94 bitbake -c devshell openssl-native 95 cd $IMA_EVM_KEY_DIR 96 # In that shell, create the keys. Several options exist: 97 98 # 1. Self-signed keys. 99 $INTEGRITY_BASE/scripts/ima-gen-self-signed.sh 100 101 # 2. Keys signed by a new CA. 102 # When asked for a PEM passphrase, that will be for the root CA. 103 # Signing images then will not require entering that passphrase, 104 # only creating new certificates does. Most likely the default 105 # attributes for these certificates need to be adapted; modify 106 # the scripts as needed. 107 # $INTEGRITY_BASE/scripts/ima-gen-local-ca.sh 108 # $INTEGRITY_BASE/scripts/ima-gen-CA-signed.sh 109 110 # 3. Keys signed by an existing CA. 111 # $INTEGRITY_BASE/scripts/ima-gen-CA-signed.sh <CA.pem> <CA.priv> 112 exit 113 114When using ``ima-self-signed.sh`` as described above, self-signed keys 115are created. Alternatively, one can also use keys signed by a CA. The 116``ima-gen-local-ca.sh`` and ``ima-gen.sh`` scripts create a root CA 117and sign the signing keys with it. The ``ima-evm-rootfs.bbclass`` then 118supports adding tha CA's public key to the kernel's system keyring by 119compiling it directly into the kernel. Because it is unknown whether 120that is necessary (for example, the CA might also get added to the 121system key ring via UEFI Secure Boot), one has to enable compilation 122into the kernel explicitly in a local.conf with: 123 124 IMA_EVM_ROOT_CA = "<path to .x509 file, for example the ima-local-ca.x509 created by ima-gen-local-ca.sh>" 125 126 127 128 129To use the personal keys, override the default IMA_EVM_KEY_DIR in your 130local.conf and/or override the individual variables from 131ima-evm-rootfs.bbclass: 132 133 IMA_EVM_KEY_DIR = "<full path>" 134 IMA_EVM_PRIVKEY = "<some other path/privkey_ima.pem>" 135 136By default, the entire file system gets signed. When using a policy which 137does not require that, the set of files to be labelled can be chosen 138by overriding the default "find" expression, for example like this: 139 140 IMA_EVM_ROOTFS_FILES = "usr sbin bin lib -type f" 141 142 1432. Usage 144======== 145 146After creating an image with IMA/EVM enabled, one needs to enable 147the built-in policies before IMA/EVM is active at runtime. To do this, 148add one or both of these boot parameters: 149 150 ima_tcb # measures all files read as root and all files executed 151 ima_appraise_tcb # appraises all files owned by root, beware of 152 # the known issue mentioned below 153 154Instead of booting with default policies, one can also activate custom 155policies in different ways. First, boot without any IMA policy and 156then cat a policy file into 157`/sys/kernel/security/ima/policy`. This can only be done once 158after booting and is useful for debugging. 159 160In production, the long term goal is to load a verified policy 161directly from the kernel, using a patch which still needs to be 162included upstream ("ima: load policy from the kernel", 163<https://lwn.net/Articles/595759/>). 164 165Loading via systemd also works with systemd, but is considered less 166secure (policy file is not checked before activating it). Beware that 167IMA policy loading became broken in systemd 2.18. The modified systemd 1682.19 in meta-security-smack has a patch reverting the broken 169changes. To activate policy loading via systemd, place a policy file 170in `/etc/ima/ima-policy`, for example with: 171 172 IMA_EVM_POLICY_SYSTEMD = "${INTEGRITY_BASE}/data/ima_policy_simple" 173 174To check that measuring works, look at `/sys/kernel/security/ima/ascii_runtime_measurements` 175 176To check that appraisal works, try modifying executables and ensure 177that executing them fails: 178 179 echo "foobar" >>/usr/bin/rpm 180 evmctl ima_verify /usr/bin/rpm 181 rpm --version 182 183Depending on the current appraisal policy, the `echo` command may 184already fail because writing is not allowed. If the file was modified 185and the current appraisal policy allows reading, then `evmctl` will 186report (the errno value seems to be printed always and is unrelated to 187the actual verification failure here): 188 189 Verification failed: 35 190 errno: No such file or directory (2) 191 192After enabling a suitable IMA appraisal policy, reading and/or 193executing the file is no longer allowed: 194 195 # evmctl ima_verify /usr/bin/rpm 196 Failed to open: /usr/bin/rpm 197 errno: Permission denied (13) 198 # rpm --version 199 -sh: /usr/bin/rpm: Permission denied 200 201Enabling the audit kernel subsystem may help to debug appraisal 202issues. Enable it by adding the meta-security-framework layer and 203changing your local.conf: 204 SRC_URI_append_pn-linux-yocto = " file://audit.cfg" 205 CORE_IMAGE_EXTRA_INSTALL += "auditd" 206 207Then boot with "ima_appraise=log ima_appraise_tcb". 208 209Adding auditd is not strictly necessary but helps to capture a 210more complete set of events in /var/log/audit/ and search in 211them with ausearch. 212 213 2143. Known Issues 215=============== 216 217EVM is not enabled, for multiple reasons: 218* Signing files in advance with a X509 certificate and then not having 219 any confidential keys on the device would be the most useful mode, 220 but is not supported by EVM [1]. 221* EVM signing in advance would only work on the final file system and thus 222 will require further integration work with image creation. The content 223 of the files can be signed for IMA in the rootfs, with the extended 224 attributes remaining valid when copying the files to the final image. 225 But for EVM that copy operation changes relevant parameters (for example, 226 inode) and thus invalidates the EVM hash. 227* On device creation of EVM hashes depends on secure key handling on the 228 device (TPM) and booting at least once in a special mode (file system 229 writable, evm=fix as boot parameter, reboot after opening all files); 230 such a mode is too device specific to be implemented in a generic way. 231 232IMA appraisal with "ima_appraise_tcb" enables rules which are too strict 233for most distros. For example, systemd needs to write certain files 234as root, which is prevented by the ima_appraise_tcb appraise rules. As 235a result, the system fails to boot: 236 237 [FAILED] Failed to start Commit a transient machine-id on disk. 238 See "systemctl status systemd-machine-id-commit.service" for details. 239 ... 240 [FAILED] Failed to start Network Service. 241 See "systemctl status systemd-networkd.service" for details. 242 [FAILED] Failed to start Login Service. 243 See "systemctl status systemd-logind.service" for details. 244 245No package manager is integrated with IMA/EVM. When updating packages, 246files will end up getting installed without correct IMA/EVM attributes 247and thus will not be usable when appraisal is turned on. 248 249[1] http://permalink.gmane.org/gmane.comp.handhelds.tizen.devel/6281 250[2] http://permalink.gmane.org/gmane.comp.handhelds.tizen.devel/6275 251