Hi Eric,
On 5/30/24 5:39 PM, Eric Snowberg wrote:
>
> Signed-off-by: Eric Snowberg <eric.snowb...@oracle.com>
> ---
> 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 = u...@example.com
> + [ 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
