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

[Randy Dunlap]

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