From mboxrd@z Thu Jan 1 00:00:00 1970 Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.remote-ip=62.149.156.91 ARC-Seal: i=1; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; cv=none; t=1795010862; b=aKGkdmto5vkaOVXhejDbW8k62kY43q+Zg+6tJVb22p9xI8ejyWxK8+TLzFg3uRrispkk oK8DzTbiE7KV3lIX8VndmB8KTkdGOwaAwBLjDIBMjQF0elqfvo/gXMx/+rtAYkxwD0RP4 e7Ba5ayF480tfhl6HwSNGdGDRdIi4iuOYgwEVAmkRz2QhPfEKvY7LUXnXF6LGVbpNT+o+ f05SzuIYyicNMnZF6t6DyqYJxoKZuYgnowXf6XDupxqV96pSsHsa5t4TjA0fyNabuA25s kkuRt7QBmBFKBun9lIsSznsKB7zzePDPG+qGeiB2cnbMOVxphFJaUge4YlkFviHl4lg== ARC-Message-Signature: i=1; d=subspace.kernel.org; s=arc20261015; a=rsa-sha256; c=relaxed/relaxed; t=1795010862; h=DMARC-Filter:Received:DKIM-Signature:From:To:Cc:Subject:Date: Message-ID:X-Mailer:In-Reply-To:References:MIME-Version: Content-Transfer-Encoding:X-CMAE-Envelope; bh=tnG27anv/clasJ41YJT6fNDRfPYKa85htRw7qYwHbVQ=; b=wU2hseT1qTy6mg3InOrDR+7ezPrngZYFSS25tRHCfnXZBIzi2vbuPtPQoddHF//n8T82 nf1OkArfBPPVtF3KrQTPlV2un/WjcbIVizB9k652yKpAtQ4/d+VeKiVJ1WfO04SXNyaDU AzkJj+nTh+h9E8CTg5E8w6duY7HhwlFVYa6TzcRFZo/TVglv1WBY52Zz9Kta1RmMfY57v CheR9OdvX+3pXRM0FnTOroS5QU9kdK4C0Fp5rbnBwo4xzTOuGkUVW2J7IJzWM1zTyqARj kVbjhunVcAF4C5vRNVjXM/rrKJxFh5qfX2qP+jHliHNc7kGAHTSQJ3jVQ69fOLLTRHA== ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass header.from=enneenne.com; spf=pass smtp.mailfrom=enneenne.com; dkim=pass header.d=aruba.it header.i=@aruba.it header.a=rsa-sha256 header.s=a1 header.b="Y/RfSfCb"; arc=none smtp.remote-ip=62.149.156.91 Received: from smtpcmd0991.aruba.it (smtpcmd0991.aruba.it [62.149.156.91]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 0F5BE606A336 for ; Wed, 18 Nov 2026 14:07:39 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.2 smtp.subspace.kernel.org 0F5BE606A336 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=enneenne.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=enneenne.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=aruba.it header.i=@aruba.it header.a=rsa-sha256 header.s=a1 header.b=Y/RfSfCb Received: from polimar.tail4f75e6.ts.net ([101.57.122.26]) by Aruba SMTP with ESMTPSA id TgK1xLN2v6q8sTgK1xc7sL; Wed, 18 Nov 2026 15:07:38 +0100 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=aruba.it; s=a1; t=1795010858; bh=TKjIwAmGMFv+JF/ig2rkwBzdBx15DkKnvWVe1PUV+Tc=; h=From:To:Subject:Date:MIME-Version; b=Y/RfSfCbSwBLOvlghAk9YDLryEAGLMYlWEc3np39XqzLTN1y4q1DKyIVZ7NK6Of8X zn+tJrqMa/V1R5UClqCMmpB5r0PqW7AUXY2Qs7Xoj0ypkYqjdaZBpTMe8QSjs0V9pf oBUgbQUZPCDHyemR1BWFOw9BqWskUDJeN7Zw6iNFzgeIs1p3uadm6rUKpsstn8fYVd nJa0xn+9SkTy9Wk0Zs6dcw/1fU7LDfrBtppIwk+u2fuan0L/OUITyvEXzU3LY9EuaD LLre2jrKhjuZTUUnmsDKHevzFxmFBFTeTyq0yzJxGAFTOec/GG5GxlxJ0FTy10cV3n BPecznVVmN0MQ== From: Rodolfo Giometti To: David Howells , Jarkko Sakkinen , keyrings@vger.kernel.org Cc: Herbert Xu , "David S. Miller" , Jens Wiklander , Sumit Garg , op-tee@lists.trustedfirmware.org, =?UTF-8?q?Horia=20Geant=C4=83?= , Pankaj Gupta , Sahil Malhotra , Ahmad Fatoum , Richard Weinberger , "Christophe Leroy (CS GROUP)" , Eric Biggers , Demi Marie Obenour , Arnd Bergmann , Paul Moore , James Morris , "Serge E. Hallyn" , Jonathan Corbet , Shuah Khan , Randy Dunlap , 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 Subject: [RFC PATCH 4/9] docs: keycrypt: document keycrypt keys Date: Wed, 18 Nov 2026 15:07:34 +0100 Message-ID: <20261118140734.601772-1-giometti@enneenne.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20261118140421.584086-1-giometti@enneenne.com> References: <20261118140421.584086-1-giometti@enneenne.com> X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Post: List-Help: List-Subscribe: List-Unsubscribe: List-Owner: Precedence: list MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-CMAE-Envelope: MS4xfCr+9l+FJskrH+951sUXEa28jLHOtUMW4t9z7zxKyh/LXO4sqoa7bQBd5Rk6CQeu3aHUyoWlOXg5QGIjMDgGUfSOhZ/i1sKCEVaP00hf8DkpNgKw0W71 E29FfSc9BLxGDnW7Bfh2//I+/JKkjFvBFqNnwnKv70TJnaip7zwf7CMcXIswYqS+tvCrVteSQhYyEEbjV45Ajwr+eoENFNVH/zP6VyJKEOZotiL3NwJg1zlr GR9oIC1PDh+/fQTII3gW5yy4dj9nmK/Yp4jKjPhw6FI3a7hea/F1Ubml4rwU0h3NZyhpiJAARnzqvIQLSq/QoWQRG4Pb2yAs5uAw81R0c+kUbSbObBQDsVSa aSf1OB2MZxZ2hQbxfYljUo8StHntXNaDLvwbIFZDZzcH/4LgnOQYgA54ewhKiA5X6PpD+WKm7Ea6Ak4dUfO7KUYbD5lvTlXHxhdrLQLTkraLdv2cs9Pnt/KU kj5WjqOvU0XOx0I54JWLqLJG2MNJzWVAm3cfke6i3+7QgIqMTPLre7Zp5KWv+8b2vkcemrFxX/DWVJj2360HgVPEY0pWrv4MHOvU9g1uSYq1FbLtH739lMMn uVUtJrTwH1tWXSRDOx4lVZIt4ebtRjY8YToj7Fjbqn4CbM3+ybZBy332BGKnk2F/enGXHQBbjeqgrlqUITNXMA9J7Y3LnCNp4A18Zs9jkCNiOXG5f05OPWU1 Wk4Rs3DFWNHHV6QuFu1YDvM7XWZaY95cVEosI9RUVh3CuGTh0M3TKxWUPWzXllDkpCEj5zTJIZb67IIU73QjtWbuARMf66hwm2JbZ0gF0P7Nc+Ibjn1BqKDQ oHWCzDujfg+AUpKlznkHhv7dJzxlZgIunyF5a9Mj/CLSZC8/CbKOLX4rmOoS0vyCMfSNjrpC4M+sCud1ap4p0zhMmjVYBgOZz93YFICmT4apaPP27+jL9ioj O64SjTsY5BaxoqRCS5NtmwA9HSW/roUqXWulxrIir3qmQ8Iqaby6k1E7qDKPoeYb4wLWzWWx7ulXLP3M4Ac98h1cUHsS1O4KZL2/XpjN4f+HmZtvuJAaCWQp wkZH5nehGoJigIfsvDtEbsCNZv6owjyanScdqHxCPWBnh6UaNofM0tOZnePie2C7uWD03Eshw/S0K8t4V1gVcT0fkaCahKUzGQzd+IucLg8kQeFlqH2IqhMw eX4xE9xSRE4OYFifDDJdXaR9z2qFNMg4Td+OQ5Co0zSfC0UM6zhPoV30fpTQZK62HgoCM/TUUpNz6yhxpqKgP0sJqskE2MKcPXz4tQM2leulX5D/kCH9Uh++ 2EPPfncg0Y3SbIgzcvo/Q2NcihdNOIHFEDpsNwpYZIivhkXMt3Y= Document the keycrypt key type: its model and tiers, what the core enforces and what only a tee or hsm backend can guarantee against a compromised kernel, the add_key() syntax and the blob, the kernel tier, the OP-TEE backend, the operation context and its ioctls, CBC, MAC and VERIFY, revocation and permissions, the system policies, why AF_ALG and KEYCTL_PKEY_* do not cover this, and the errors. Signed-off-by: Rodolfo Giometti --- Documentation/security/keys/index.rst | 1 + Documentation/security/keys/keycrypt.rst | 838 +++++++++++++++++++++++ 2 files changed, 839 insertions(+) create mode 100644 Documentation/security/keys/keycrypt.rst diff --git a/Documentation/security/keys/index.rst b/Documentation/security/keys/index.rst index 647d58f2588e..ff44babc7a8f 100644 --- a/Documentation/security/keys/index.rst +++ b/Documentation/security/keys/index.rst @@ -7,5 +7,6 @@ Kernel Keys core ecryptfs + keycrypt request-key trusted-encrypted diff --git a/Documentation/security/keys/keycrypt.rst b/Documentation/security/keys/keycrypt.rst new file mode 100644 index 000000000000..17af3b041000 --- /dev/null +++ b/Documentation/security/keys/keycrypt.rst @@ -0,0 +1,838 @@ +.. SPDX-License-Identifier: GPL-2.0-only + +============= +Keycrypt Keys +============= + +A "keycrypt" key is a symmetric key that user space uses for cryptography +but never reads. Its algorithm, purpose and protection tier are fixed when +the key is created; the key itself lives in a *backend*, and user space +keeps only a blob that the backend sealed and that authenticates that +metadata. + +Tiers and backends +================== + +Two kinds of name appear in this document. A *tier* names a guarantee +about a key; a *backend* names a mechanism that holds keys; it declares +one tier when it registers, and gives at least that tier's guarantee. +No name is both. User space asks for a tier (`Usage`_), and may +name the backend too; otherwise the kernel chooses the backend that +provides it. A key stays bound to the backend that sealed it, which +``/proc/keys`` and ``KEYCRYPT_IOC_INFO`` report. + +The tiers, lowest first: + +========== ========================================================= +``kernel`` the key is in clear in kernel memory while loaded; the + kernel enforces its use +``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 + the kernel (a secure element, a security core of its own + such as NXP's EdgeLock Enclave, a crypto engine with its own + policy) +========== ========================================================= + +Each tier holds the guarantees of those before it. + +The backends of this document: ``sw``, of tier ``kernel``, where the +kernel's own software uses the key (`The sw backend`_); and ``optee``, +of tier ``tee`` (`The OP-TEE backend`_). + +Every backend, whatever its tier, must seal with a secret that is secret +and unique to the device: the trusted key the sw backend derives from +or OP-TEE's hardware unique key. Were that secret known, the blob, which +user space reads, would be the key itself; were it shared by several +devices, a blob copied from one would load on another, and its key would +be used there. Every tier presumes it, and keycrypt cannot check it, nor +that the hardware is configured so that the secret is secret (an OP-TEE +whose hardware unique key is provisioned, not OP-TEE's test value): +whoever builds in or loads a backend for a device declares +that the device meets it, as a backend declares its tier. For the +sw backend the secret is the trusted master each key names with +``master=``, so there the requirement falls on whoever creates that +master (`The sw backend`_). + +A backend of tier ``tee`` or ``hsm`` also declares that it meets +`Backend requirements`_. + +A backend registers with ``keycrypt_register_backend()`` +(``include/keys/keycrypt.h``) under a name that is stored in every blob it +seals. Its data must authenticate the blob's header, which carries the +metadata: a blob whose metadata was changed does not load. Each key pins +the backend's module; a backend that goes away +(``keycrypt_unregister_backend()``) leaves its keys in place, unusable. + +Backend requirements +==================== + +The core enforces, from the key's own metadata, the operation against +the key's purpose and the key's tier against the caller's +``accepted_min_tier`` and the system tier at every +``KEYCTL_CRYPT_OPEN`` (`Using a key`_); and, at +``keycrypt_register_backend()``, that a backend declares a valid tier, +offers ``generate`` and ``load``, the four context callbacks all or +none and, for a ``tee`` or ``hsm`` backend with context operations, +``verify`` for hmac-sha256. None of +that defends against a *compromised kernel*: the core is kernel code +too, and a kernel that lies to itself can skip or fake any check it +runs itself. + +A sentence in this document that claims a property of a key's *use* +against a compromised kernel holds only for a backend of tier ``tee`` +or ``hsm``: declaring one of those tiers is declaring that its secure +side -- the TEE or the hardware, not its kernel-side callbacks alone -- +itself does what the core has no way to check: + +- binds the key's purpose into its own secure-world state when the key + is loaded, or re-authenticates the blob's header there at every + ``ctx_open``, instead of trusting the core's copy of the metadata; +- fixes the operation for a context at ``ctx_open`` and holds to it, + refusing ``final`` on a context it fixed for VERIFY and ``verify`` + on any other; +- fixes the length of a MAC or VERIFY tag. + +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. + +Metadata +======== + +========= ====================================================== +algorithm ``aes256-cbc`` or ``hmac-sha256`` +purpose ``encrypt``, ``decrypt`` (aes256-cbc); + ``mac``, ``verify``, or both (hmac-sha256) +tier the backend's, when the key was sealed +backend its name +origin ``generated`` (created by the backend: inside it for + ``tee`` and ``hsm``) or ``imported`` +========= ====================================================== + +These are the human-readable forms, as ``keyctl`` and ``/proc/keys`` +show them; ``KEYCRYPT_IOC_INFO`` (`Using a key`_) reports algorithm, +purpose, tier and origin instead as the numeric ``KEYCRYPT_ALG_*``, +``KEYCRYPT_PURPOSE_*``, ``KEYCRYPT_TIER_*`` and ``KEYCRYPT_ORIGIN_*`` +values of ````. + +A key cannot be changed: ``keyctl update`` fails (``EACCES`` with the +default permissions, which give no write permission; ``EOPNOTSUPP`` +otherwise). Adding a key with the same description to the same keyring +replaces the link with a new key, as for every key type. Nor is a key +ever constructed on demand: ``request_key()`` for a keycrypt key that +does not exist fails with ``ENOKEY`` without calling a request-key +helper, which would create it with its own credentials. + +Blob format +=========== + +The blob, which ``keyctl read`` gives and ``load`` takes in hex, is a +header the core writes and the backend authenticates, the length of the +backend's data, and that data, opaque to the core: + +============ ======== ================================================ +field bytes content +============ ======== ================================================ +magic 3 ``KCR`` +version 1 1 +flags 1 0 +algorithm 1 ``KEYCRYPT_ALG_*`` +purpose 2 ``KEYCRYPT_PURPOSE_*`` mask, little endian +tier 1 ``KEYCRYPT_TIER_*`` +origin 1 ``KEYCRYPT_ORIGIN_*`` +name length 1 1 to 16 +name variable the backend's name, ``[a-z0-9_-]`` +data length 4 1 to 4096, little endian +data variable the backend's own +============ ======== ================================================ + +``load`` refuses another version, or flags other than 0, with +``EOPNOTSUPP``, and any other malformed field with ``EBADMSG``; hex +that does not decode, or a blob longer than the largest possible, gives +``EINVAL``. + +Usage +===== + +:: + + keyctl add keycrypt name "new [,...] [