meta-integrity: port over from meta-intel-iot-security

Signed-off-by: Armin Kuster <akuster808@gmail.com>

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