> On Jun 10, 2024, at 8:33 PM, Randy Dunlap <rdunlap@xxxxxxxxxxxxx> wrote: > > 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? This example would apply to any architecture that boots through a shim and has mokutil. I'll fix this and remove the reference to x86. I'll also fix all the other changes you identified. Thanks.
