[RFC PATCH v2 8/8] clavis: Introduce new LSM called clavis

[Eric Snowberg]

> On Jun 10, 2024, at 8:33 PM, Randy Dunlap <rdunlap at infradead.org> wrote:
> 
> Hi Eric,
> 
> On 5/30/24 5:39 PM, Eric Snowberg wrote:
>> 
>> Signed-off-by: Eric Snowberg <eric.snowberg at 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 = user at 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?

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.