From: Rodolfo Giometti <giometti@enneenne.com>
To: David Howells <dhowells@redhat.com>,
Jarkko Sakkinen <jarkko@kernel.org>,
keyrings@vger.kernel.org
Cc: "Herbert Xu" <herbert@gondor.apana.org.au>,
"David S. Miller" <davem@davemloft.net>,
"Jens Wiklander" <jenswi@kernel.org>,
"Sumit Garg" <sumit.garg@kernel.org>,
op-tee@lists.trustedfirmware.org,
"Horia Geantă" <horia.geanta@nxp.com>,
"Pankaj Gupta" <pankaj.gupta@nxp.com>,
"Sahil Malhotra" <sahil.malhotra@nxp.com>,
"Ahmad Fatoum" <a.fatoum@pengutronix.de>,
"Richard Weinberger" <richard@nod.at>,
"Christophe Leroy (CS GROUP)" <chleroy@kernel.org>,
"Eric Biggers" <ebiggers@kernel.org>,
"Demi Marie Obenour" <demiobenour@gmail.com>,
"Arnd Bergmann" <arnd@arndb.de>,
"Paul Moore" <paul@paul-moore.com>,
"James Morris" <jmorris@namei.org>,
"Serge E. Hallyn" <serge@hallyn.com>,
"Jonathan Corbet" <corbet@lwn.net>,
"Shuah Khan" <skhan@linuxfoundation.org>,
"Randy Dunlap" <rdunlap@infradead.org>,
linux-crypto@vger.kernel.org, linux-integrity@vger.kernel.org,
linux-security-module@vger.kernel.org,
linux-kselftest@vger.kernel.org, linux-doc@vger.kernel.org,
linux-api@vger.kernel.org, linux-arm-kernel@lists.infradead.org,
linuxppc-dev@lists.ozlabs.org, linux-kernel@vger.kernel.org,
"Rodolfo Giometti" <giometti@enneenne.com>
Subject: [RFC PATCH 6/9] KEYS: keycrypt: Add the engine tier
Date: Wed, 18 Nov 2026 15:09:42 +0100 [thread overview]
Message-ID: <20261118140942.611715-1-giometti@enneenne.com> (raw)
In-Reply-To: <20261118140421.584086-1-giometti@enneenne.com>
Some crypto engines hold a key so that the kernel never reads it once
sealed, yet run whatever operation the kernel asks of it: the CAAM's
black keys are of this kind. A key there is better kept than in
kernel memory, but its use is no more checked than the kernel
tier's.
Add the engine tier, 15, between kernel and tee, for such backends:
tier=engine and min-tier=engine choose them, accepted-min-tier=engine
and KEYCTL_CRYPT_OPEN's accepted_min_tier take them, and
CONFIG_KEYCRYPT_SYSTEM_TIER_ENGINE makes it the system tier at boot.
The core warns in the kernel log when a backend registers at it, since
the protection its name may suggest stops short of the use of the key.
No backend in the kernel declares this tier yet; the keycrypt CAAM
backend proposed with it does.
Signed-off-by: Rodolfo Giometti <giometti@enneenne.com>
---
.../admin-guide/kernel-parameters.txt | 2 +-
Documentation/security/keys/keycrypt.rst | 42 ++++++++++++-------
include/uapi/linux/keycrypt.h | 2 +
security/keys/keycrypt/Kconfig | 11 ++++-
security/keys/keycrypt/core.c | 4 ++
security/keys/keycrypt/keycrypt.h | 2 +
6 files changed, 46 insertions(+), 17 deletions(-)
diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt
index 62d44a5225e4..0cacb7d1ca1d 100644
--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -2947,7 +2947,7 @@ Kernel parameters
keycrypt.system_tier= [KEYS] Lowest protection tier a keycrypt key
may be used at; keys of a lower tier can still
be created and loaded.
- Format: { kernel | tee | hsm }
+ Format: { kernel | engine | tee | hsm }
Default: the CONFIG_KEYCRYPT_SYSTEM_TIER_*
choice, kernel unless set. Can only be raised,
here or later through the
diff --git a/Documentation/security/keys/keycrypt.rst b/Documentation/security/keys/keycrypt.rst
index 17af3b041000..ac393a0bc97d 100644
--- a/Documentation/security/keys/keycrypt.rst
+++ b/Documentation/security/keys/keycrypt.rst
@@ -26,6 +26,10 @@ The tiers, lowest first:
========== =========================================================
``kernel`` the key is in clear in kernel memory while loaded; the
kernel enforces its use
+``engine`` a crypto engine the kernel drives keeps the key, never in
+ clear in the kernel once sealed; the kernel decides its use
+ (a secure element that does not check a key's use is an
+ engine too)
``tee`` a trusted execution environment keeps the key and checks
every use against the purpose it bound (an OP-TEE TA)
``hsm`` as ``tee``, in dedicated hardware apart from the CPU running
@@ -34,7 +38,9 @@ The tiers, lowest first:
policy)
========== =========================================================
-Each tier holds the guarantees of those before it.
+Each tier holds the guarantees of those before it. Keys of the ``engine``
+tier, such as the CAAM's protected keys, are used by the kernel, which
+cannot read them once sealed.
The backends of this document: ``sw``, of tier ``kernel``, where the
kernel's own software uses the key (`The sw backend`_); and ``optee``,
@@ -55,7 +61,9 @@ sw backend the secret is the trusted master each key names with
master (`The sw backend`_).
A backend of tier ``tee`` or ``hsm`` also declares that it meets
-`Backend requirements`_.
+`Backend requirements`_; one that keeps a sealed key out of the kernel's
+reading but leaves its use to the kernel is ``engine``. The core says
+so in the kernel log when an ``engine`` backend registers.
A backend registers with ``keycrypt_register_backend()``
(``include/keys/keycrypt.h``) under a name that is stored in every blob it
@@ -96,10 +104,13 @@ itself does what the core has no way to check:
A backend declares its own tier at ``keycrypt_register_backend()``; the
core stores and compares it wherever a tier is checked, but never
confirms that the backend is actually a TEE or hardware rather than
-ordinary kernel code claiming to be one. The ``kernel`` tier meets
-none of the above: its key material is in clear in kernel memory (`The
-sw backend`_), so there every property above is only as strong as the
-kernel itself.
+ordinary kernel code claiming to be one. The ``engine`` and ``kernel``
+tiers meet none of the above: an ``engine`` backend leaves the key's
+use to the kernel, and the kernel tier's key material is in clear in
+kernel memory (`The sw backend`_), so there every property above is
+only as strong as the kernel itself. What an ``engine`` backend keeps
+against a compromised kernel is only that a sealed key is not in clear
+in kernel memory, as far as its hardware's own properties hold.
Metadata
========
@@ -187,7 +198,7 @@ Any other ``<option>=<value>`` is passed to the backend; the core refuses
an option the backend does not declare and an option given twice. The
one option a backend of this document takes from user space is
``master=``, the sw backend's: it needs a master to seal its keys, while from
-``tee`` up a backend's own mechanisms protect the key. A command for
+``engine`` up a backend's own mechanisms protect the key. A command for
the kernel tier therefore reads ``tier=kernel master=<name>``; the kernel
tier chosen without ``master=``, or ``master=`` given to a backend of
another tier, is refused with ``EINVAL``.
@@ -451,10 +462,11 @@ so that a kernel compromised enough to lie about the operation or the
key's metadata still cannot open, say, an encryption context on a
decrypt-only key; the sw backend has no such check of its own, since
a compromised kernel already has that backend's key material in clear
-(`The sw backend`_), and relies on the core's check alone. Across
-every tier it is the kernel, not any backend, that decides who may open
-a context on a key, since Search permission is the core's own check; a
-compromised kernel can
+(`The sw backend`_), and relies on the core's check alone; neither
+does an ``engine`` backend, whose key's use the kernel decides
+(`Tiers and backends`_). Across every tier it is the kernel, not any
+backend, that decides who may open a context on a key, since Search
+permission is the core's own check; a compromised kernel can
therefore still open a context on a key of any tier and use it for a
purpose the key already has, but, for a backend of tier ``tee`` or
``hsm`` meeting `Backend requirements`_, it can neither read that key
@@ -603,8 +615,8 @@ the capability); neither touches a context already open at the time
they change.
``kernel.keys.keycrypt_system_tier`` is the system tier, the lowest tier
-a key may be used at: one of ``10`` (``kernel``), ``20`` (``tee``)
-or ``30`` (``hsm``), the same values as
+a key may be used at: one of ``10`` (``kernel``), ``15`` (``engine``),
+``20`` (``tee``) or ``30`` (``hsm``), the same values as
``KEYCRYPT_TIER_*`` (`Tiers and backends`_). It can only be raised,
never lowered (``EPERM`` on a lower value, ``EINVAL`` on anything
else). It applies to use only: ``KEYCTL_CRYPT_OPEN`` refuses a key
@@ -630,8 +642,8 @@ already loaded is affected, imported or not. With
rather than this one.
Each has a boot parameter setting its starting value before either sysctl
-is ever written: ``keycrypt.system_tier=`` (``kernel``, ``tee`` or
-``hsm``) and ``keycrypt.import=`` (a boolean). An invalid
+is ever written: ``keycrypt.system_tier=`` (``kernel``, ``engine``,
+``tee`` or ``hsm``) and ``keycrypt.import=`` (a boolean). An invalid
value, or one that would lower what is already set, is ignored, with a
kernel warning, rather than failing the boot. An administrator who
wants either policy fixed from the very start, before any user-space
diff --git a/include/uapi/linux/keycrypt.h b/include/uapi/linux/keycrypt.h
index c03348579f62..71209a08c924 100644
--- a/include/uapi/linux/keycrypt.h
+++ b/include/uapi/linux/keycrypt.h
@@ -13,6 +13,8 @@
/* Protection tiers, lowest first; the gaps leave room for more */
#define KEYCRYPT_TIER_KERNEL 10 /* the kernel itself */
+/* a crypto engine the kernel drives; the kernel decides its use */
+#define KEYCRYPT_TIER_ENGINE 15
#define KEYCRYPT_TIER_TEE 20 /* a trusted execution environment */
/* as TEE, in dedicated hardware apart from the CPU running the kernel */
#define KEYCRYPT_TIER_HSM 30
diff --git a/security/keys/keycrypt/Kconfig b/security/keys/keycrypt/Kconfig
index e61922933bd7..a6d8a0fa6d29 100644
--- a/security/keys/keycrypt/Kconfig
+++ b/security/keys/keycrypt/Kconfig
@@ -56,11 +56,20 @@ config KEYCRYPT_SYSTEM_TIER_KERNEL
A system with no backend of the kernel tier built has no key of
that tier to use.
+config KEYCRYPT_SYSTEM_TIER_ENGINE
+ bool "Engine"
+ help
+ Only keys whose backend declares them never in clear in the
+ kernel once sealed can be used: a key of the kernel tier is
+ refused at every KEYCTL_CRYPT_OPEN; the engine, tee and hsm tiers
+ can be used. For a system that must never use a key held in clear
+ by the kernel.
+
config KEYCRYPT_SYSTEM_TIER_TEE
bool "TEE"
help
Keys whose use a trusted execution environment or the hardware
- checks: keys of the kernel tier are refused at every
+ checks: keys of the kernel and engine tiers are refused at every
KEYCTL_CRYPT_OPEN; the tee and hsm tiers can be used. For a
system where OP-TEE or an hsm backend holds the keys.
diff --git a/security/keys/keycrypt/core.c b/security/keys/keycrypt/core.c
index debd0845621e..4a2609c6830f 100644
--- a/security/keys/keycrypt/core.c
+++ b/security/keys/keycrypt/core.c
@@ -40,6 +40,7 @@ static const struct keycrypt_name keycrypt_algs[] = {
static const struct keycrypt_name keycrypt_tiers[] = {
{ KEYCRYPT_TIER_KERNEL, "kernel" },
+ { KEYCRYPT_TIER_ENGINE, "engine" },
{ KEYCRYPT_TIER_TEE, "tee" },
{ KEYCRYPT_TIER_HSM, "hsm" },
};
@@ -441,6 +442,9 @@ int keycrypt_register_backend(struct keycrypt_backend *b)
b->handle = h;
}
mutex_unlock(&keycrypt_lock);
+ if (!ret && b->tier == KEYCRYPT_TIER_ENGINE)
+ pr_warn("backend %s registered at tier engine: the use of its keys is checked by the kernel only\n",
+ b->name);
if (ret)
kfree(h);
return ret;
diff --git a/security/keys/keycrypt/keycrypt.h b/security/keys/keycrypt/keycrypt.h
index 5a41a68c48fa..40487eb3e139 100644
--- a/security/keys/keycrypt/keycrypt.h
+++ b/security/keys/keycrypt/keycrypt.h
@@ -143,6 +143,8 @@ bool keycrypt_tier_valid(u32 tier);
#define KEYCRYPT_BOOT_SYSTEM_TIER KEYCRYPT_TIER_HSM
#elif IS_ENABLED(CONFIG_KEYCRYPT_SYSTEM_TIER_TEE)
#define KEYCRYPT_BOOT_SYSTEM_TIER KEYCRYPT_TIER_TEE
+#elif IS_ENABLED(CONFIG_KEYCRYPT_SYSTEM_TIER_ENGINE)
+#define KEYCRYPT_BOOT_SYSTEM_TIER KEYCRYPT_TIER_ENGINE
#else
#define KEYCRYPT_BOOT_SYSTEM_TIER KEYCRYPT_TIER_KERNEL
#endif
--
2.43.0
next prev parent reply other threads:[~2026-11-18 14:09 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-18 14:04 [RFC PATCH 0/9] KEYS: keycrypt: keys that user space can use but never read Rodolfo Giometti
2026-11-18 14:04 ` [RFC PATCH 1/9] KEYS: keycrypt: Add a key type for keys user space never reads Rodolfo Giometti
2026-11-18 14:04 ` [RFC PATCH 2/9] KEYS: keycrypt: Add the sw backend Rodolfo Giometti
2026-11-18 14:04 ` [RFC PATCH 3/9] KEYS: keycrypt: Add the OP-TEE backend Rodolfo Giometti
2026-11-18 14:07 ` [RFC PATCH 4/9] docs: keycrypt: document keycrypt keys Rodolfo Giometti
2026-11-18 14:08 ` [RFC PATCH 5/9] MAINTAINERS: add KEYS-KEYCRYPT Rodolfo Giometti
2026-11-18 14:09 ` Rodolfo Giometti [this message]
2026-11-18 14:10 ` [RFC PATCH 7/9] crypto: caam - add an internal cbc(paes) taking the blob's key modifier Rodolfo Giometti
2026-11-18 14:11 ` [RFC PATCH 8/9] KEYS: keycrypt: Add the CAAM backend Rodolfo Giometti
2026-11-18 14:12 ` [RFC PATCH 9/9] KEYS: keycrypt: Add the aes256-gcm-stream algorithm Rodolfo Giometti
2026-11-18 14:31 ` [RFC PATCH 0/9] KEYS: keycrypt: keys that user space can use but never read Jarkko Sakkinen
2026-11-18 14:39 ` Jarkko Sakkinen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261118140942.611715-1-giometti@enneenne.com \
--to=giometti@enneenne.com \
--cc=a.fatoum@pengutronix.de \
--cc=arnd@arndb.de \
--cc=chleroy@kernel.org \
--cc=corbet@lwn.net \
--cc=davem@davemloft.net \
--cc=demiobenour@gmail.com \
--cc=dhowells@redhat.com \
--cc=ebiggers@kernel.org \
--cc=herbert@gondor.apana.org.au \
--cc=horia.geanta@nxp.com \
--cc=jarkko@kernel.org \
--cc=jenswi@kernel.org \
--cc=jmorris@namei.org \
--cc=keyrings@vger.kernel.org \
--cc=linux-api@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-crypto@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-integrity@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-kselftest@vger.kernel.org \
--cc=linux-security-module@vger.kernel.org \
--cc=linuxppc-dev@lists.ozlabs.org \
--cc=op-tee@lists.trustedfirmware.org \
--cc=pankaj.gupta@nxp.com \
--cc=paul@paul-moore.com \
--cc=rdunlap@infradead.org \
--cc=richard@nod.at \
--cc=sahil.malhotra@nxp.com \
--cc=serge@hallyn.com \
--cc=skhan@linuxfoundation.org \
--cc=sumit.garg@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox