Hi Eric, On 5/30/24 5:39 PM, Eric Snowberg wrote: > > Signed-off-by: Eric Snowberg <eric.snowberg@xxxxxxxxxx> > --- > Documentation/admin-guide/LSM/clavis.rst | 198 +++++++++++++++++++++++ > MAINTAINERS | 7 + > crypto/asymmetric_keys/signature.c | 4 + > include/linux/lsm_hook_defs.h | 2 + > include/linux/security.h | 7 + > include/uapi/linux/lsm.h | 1 + > security/Kconfig | 10 +- > security/clavis/Makefile | 1 + > security/clavis/clavis.c | 25 +++ > security/clavis/clavis.h | 4 + > security/clavis/clavis_keyring.c | 83 ++++++++++ > security/security.c | 16 +- > 12 files changed, 352 insertions(+), 6 deletions(-) > create mode 100644 Documentation/admin-guide/LSM/clavis.rst > create mode 100644 security/clavis/clavis.c > > diff --git a/Documentation/admin-guide/LSM/clavis.rst b/Documentation/admin-guide/LSM/clavis.rst > new file mode 100644 > index 000000000000..d1641e3ef38b > --- /dev/null > +++ b/Documentation/admin-guide/LSM/clavis.rst > @@ -0,0 +1,198 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +====== > +Clavis > +====== > + > +Clavis is a Linux Security Module that provides mandatory access control to > +system kernel keys (i.e. builtin, secondary, machine and platform). These > +restrictions will prohibit keys from being used for validation. Upon boot, the > +Clavis LSM is provided a key id as a boot param. This single key is then boot parameter. > +used as the root of trust for any access control modifications made going > +forward. Access control updates must be signed and validated by this key. > + > +Clavis has its own keyring. All ACL updates are applied through this keyring. > +The update must be signed by the single root of trust key. > + > +When enabled, all system keys are prohibited from being used until an ACL is > +added for them. There is two exceptions to this rule, builtin keys may be used There are rule: > +to validate both signed kernels and modules. > + > +Adding system kernel keys can only be performed by the machine owner; this > +could be through the Machine Owner Key (MOK) or the UEFI Secure Boot DB. It > +is possible the machine owner and system administrator may be different > +people. The system administrator will not be able to make ACL updates without > +them being signed by the machine owner. > + > +On UEFI platforms, the root of trust key shall survive a kexec. Trying to > +defeat or change it from the command line is not allowed. The original boot > +param is stored in UEFI and will always be referenced following a kexec. parameter > + > +The Clavis LSM contains a system keyring call .clavis. It contains a single > +asymmetric key that is use to validate anything added to it. This key can only used > +be added during boot and must be a preexisting system kernel key. If the > +``clavis=`` boot param is not used, the keyring does not exist and the feature parameter > +can not be used until the next reboot. cannot preferably > + > +The only user space components are OpenSSL and the keyctl utility. A new > +key type call ``clavis_key_acl`` is used for ACL updates. Any number of signed > +``clavis_key_acl`` entries may be added to the .clavis keyring. The > +``clavis_key_acl`` contains the subject key identifier along with the allowed > +usage type for > +the key. Join 2 lines? > + > +The format is as follows: > + > +.. code-block:: console > + > + XX:YYYYYYYYYYY > + > + XX - Single byte of the key type > + VERIFYING_MODULE_SIGNATURE 00 > + VERIFYING_FIRMWARE_SIGNATURE 01 > + VERIFYING_KEXEC_PE_SIGNATURE 02 > + VERIFYING_KEY_SIGNATURE 03 > + VERIFYING_KEY_SELF_SIGNATURE 04 > + VERIFYING_UNSPECIFIED_SIGNATURE 05 > + : - ASCII colon > + YY - Even number of hexadecimal characters representing the key id > + > +The ``clavis_key_acl`` must be S/MIME signed by the sole asymmetric key contained > +within the .clavis keyring. > + > +In the future if new features are added, new key types could be created. > + > +Usage Examples > +============== > + > +How to create a signing key: > +---------------------------- > + > +.. code-block:: bash > + > + cat <<EOF > clavis-lsm.genkey > + [ req ] > + default_bits = 4096 > + distinguished_name = req_distinguished_name > + prompt = no > + string_mask = utf8only > + x509_extensions = v3_ca > + [ req_distinguished_name ] > + O = TEST > + CN = Clavis LSM key > + emailAddress = user@xxxxxxxxxxx > + [ v3_ca ] > + basicConstraints=CA:TRUE > + subjectKeyIdentifier=hash > + authorityKeyIdentifier=keyid:always,issuer > + keyUsage=digitalSignature > + EOF > + > + openssl req -new -x509 -utf8 -sha256 -days 3650 -batch \ > + -config clavis-lsm.genkey -outform DER \ > + -out clavis-lsm.x509 -keyout clavis-lsm.priv > + > +How to get the Subject Key Identifier > +------------------------------------- > + > +.. code-block:: bash > + > + openssl x509 -in ./clavis-lsm.x509 -inform der \ > + -ext subjectKeyIdentifier -nocert \ > + | tail -n +2 | cut -f2 -d '='| tr -d ':' > + 4a00ab9f35c9dc3aed7c225d22bafcbd9285e1e8 > + > +How to enroll the signing key into the MOK > +------------------------------------------ > + > +The key must now be added to the machine or platform keyrings. This > +indicates the key was added by the system owner. To add to the machine > +keyring on x86 do: Are other architectures different? why? > + > +.. code-block:: bash > + > + mokutil --import ./clavis-lsm.x509 > + > +and then reboot and enroll the key through the MokManager. > + > +How to enable the Clavis LSM > +---------------------------- > + > +Add the key id to the ``clavis=`` boot param. With the example above the parameter. > +key id is the subject key identifier: 4a00ab9f35c9dc3aed7c225d22bafcbd9285e1e8 > + > +Add the following boot param: parameter: > + > +.. code-block:: console > + > + clavis=4a00ab9f35c9dc3aed7c225d22bafcbd9285e1e8 > + > +After booting there will be a single key contained in the .clavis keyring: > + > +.. code-block:: bash > + > + keyctl show %:.clavis > + Keyring > + 254954913 ----swrv 0 0 keyring: .clavis > + 301905375 ---lswrv 0 0 \_ asymmetric: TEST: Clavis LSM key: 4a00ab9f35c9dc3aed7c225d22bafcbd9285e1e8 > + > +The original ``clavis=`` boot param will persist across any kexec. Changing it or parameter > +removing it has no effect. > + > + > +How to sign an entry to be added to the .clavis keyring: > +-------------------------------------------------------- > + > +In this example we have 3 keys in the machine keyring. Our Clavis LSM key, a > +key we want to use for kernel verification and a key we want to use for module > +verification. > + > +.. code-block:: bash > + > + keyctl show %:.machine > + Keyring > + 999488265 ---lswrv 0 0 keyring: .machine > + 912608009 ---lswrv 0 0 \_ asymmetric: TEST: Module Key: 17eb8c5bf766364be094c577625213700add9471 > + 646229664 ---lswrv 0 0 \_ asymmetric: TEST: Kernel Key: b360d113c848ace3f1e6a80060b43d1206f0487d > + 1073737099 ---lswrv 0 0 \_ asymmetric: TEST: Clavis LSM key: 4a00ab9f35c9dc3aed7c225d22bafcbd9285e1e8 > + > +To update the .clavis kerying ACL list. First create a file containing the list, first > +key usage type followed by a colon and the key id that we want to allow to > +validate that usage. In the first example we are saying key > +17eb8c5bf766364be094c577625213700add9471 is allowed to validate kernel modules. > +In the second example we are saying key b360d113c848ace3f1e6a80060b43d1206f0487d > +is allowed to validate signed kernels. > + > +.. code-block:: bash > + > + echo "00:17eb8c5bf766364be094c577625213700add9471" > module-acl.txt > + echo "02:b360d113c848ace3f1e6a80060b43d1206f0487d" > kernel-acl.txt > + > +Now both these files must be signed by the key contained in the .clavis keyring: > + > +.. code-block:: bash > + > + openssl smime -sign -signer clavis-lsm.x509 -inkey clavis-lsm.priv -in module-acl.txt \ > + -out module-acl.pkcs7 -binary -outform DER -nodetach -noattr > + > + openssl smime -sign -signer clavis-lsm.x509 -inkey clavis-lsm.priv -in kernel-acl.txt \ > + -out kernel-acl.pkcs7 -binary -outform DER -nodetach -noattr > + > +Afterwards the ACL list in the clavis keyring can be updated: > + > +.. code-block:: bash > + > + keyctl padd clavis_key_acl "" %:.clavis < module-acl.pkcs7 > + keyctl padd clavis_key_acl "" %:.clavis < kernel-acl.pkcs7 > + > + keyctl show %:.clavis > + > + Keyring > + 254954913 ----swrv 0 0 keyring: .clavis > + 301905375 ---lswrv 0 0 \_ asymmetric: TEST: Clavis LSM key: 4a00ab9f35c9dc3aed7c225d22bafcbd9285e1e8 > + 1013065475 --alswrv 0 0 \_ clavis_key_acl: 02:b360d113c848ace3f1e6a80060b43d1206f0487d > + 445581284 --alswrv 0 0 \_ clavis_key_acl: 00:17eb8c5bf766364be094c577625213700add9471 > + > +Now the 17eb8c5bf766364be094c577625213700add9471 key can be used for > +validating kernel modules and the b360d113c848ace3f1e6a80060b43d1206f0487d > +key can be used to validate signed kernels. -- ~Randy