diff options
| author | Adrian Betschart <adrian.betschart@cinemaone.ch> | 2026-09-11 17:13:14 +0200 |
|---|---|---|
| committer | Alex Deucher <alexander.deucher@amd.com> | 2026-10-01 17:18:05 -0400 |
| commit | 106b4a2a78b2a2f14885604891957b84bba502db (patch) | |
| tree | 5d40eef2428fb1a4791ab46a4b19091a5910eac2 /Documentation/crypto | |
| download | linux-stable-106b4a2a78b2a2f14885604891957b84bba502db.tar.gz linux-stable-106b4a2a78b2a2f14885604891957b84bba502db.zip | |
drm/amd/display: Try RGB before YCbCr 4:4:4 in stream validationgrafted
amdgpu_dm_create_validate_stream_for_sink() walks encoding_order[] and
uses the first encoding that validates. YCbCr 4:4:4 is listed before
RGB, so an HDMI sink that advertises 4:4:4 gets YCbCr 4:4:4 whenever the
"color format" property is left at AUTO, even though RGB fits the same
link.
That contradicts the documented AUTO behaviour for HDMI in enum
drm_connector_color_format (RGB, falling back to YCbCr 4:2:0 only when
the bandwidth is not available or the mode is 4:2:0-only), which the
amdgpu implementation of the property also describes. It also leaves
the "Broadcast RGB" property without effect on such sinks, since the
quantization range it selects only applies to RGB output.
Try RGB first. The mask still holds every encoding the sink supports,
so a mode that cannot carry RGB falls back exactly as before.
For reference, v7.2 picked RGB here unless YCbCr 4:4:4 was forced
through debugfs, while earlier kernels picked YCbCr 4:4:4 for any HDMI
sink that advertised it.
Fixes: 0b0ff65d3ca1 ("drm/amd/display: Refactor stream validation")
Suggested-by: Adolfo Rodrigues <adolfotregosa@gmail.com>
Assisted-by: Claude Code:claude-fable-5-1
Signed-off-by: Adrian Betschart <adrian.betschart@cinemaone.ch>
Reviewed-by: Fangzhi Zuo <jerry.zuo@amd.com>
Tested-by: Adolfo Rodrigues <adolfotregosa@gmail.com>
Tested-by: Daniel Wheeler <daniel.wheeler@amd.com>
Signed-off-by: Alex Deucher <alexander.deucher@amd.com>
(cherry picked from commit 7de432bc753133764dc40d37f9388da56de251e7)
Diffstat (limited to 'Documentation/crypto')
30 files changed, 3861 insertions, 0 deletions
diff --git a/Documentation/crypto/api-aead.rst b/Documentation/crypto/api-aead.rst new file mode 100644 index 000000000..78d073319 --- /dev/null +++ b/Documentation/crypto/api-aead.rst @@ -0,0 +1,26 @@ +Authenticated Encryption With Associated Data (AEAD) +==================================================== + +Authenticated Encryption With Associated Data (AEAD) Algorithm Definitions +-------------------------------------------------------------------------- + +.. kernel-doc:: include/crypto/aead.h + :doc: Authenticated Encryption With Associated Data (AEAD) Cipher API + +.. kernel-doc:: include/crypto/aead.h + :functions: aead_request aead_alg + +Authenticated Encryption With Associated Data (AEAD) Cipher API +--------------------------------------------------------------- + +.. kernel-doc:: include/crypto/aead.h + :functions: crypto_alloc_aead crypto_free_aead crypto_aead_ivsize crypto_aead_authsize crypto_aead_blocksize crypto_aead_setkey crypto_aead_setauthsize crypto_aead_encrypt crypto_aead_decrypt + +Asynchronous AEAD Request Handle +-------------------------------- + +.. kernel-doc:: include/crypto/aead.h + :doc: Asynchronous AEAD Request Handle + +.. kernel-doc:: include/crypto/aead.h + :functions: crypto_aead_reqsize aead_request_set_tfm aead_request_alloc aead_request_free aead_request_set_callback aead_request_set_crypt aead_request_set_ad diff --git a/Documentation/crypto/api-akcipher.rst b/Documentation/crypto/api-akcipher.rst new file mode 100644 index 000000000..a31f5aef7 --- /dev/null +++ b/Documentation/crypto/api-akcipher.rst @@ -0,0 +1,23 @@ +Asymmetric Cipher +================= + +Asymmetric Cipher Algorithm Definitions +--------------------------------------- + +.. kernel-doc:: include/crypto/akcipher.h + :functions: akcipher_alg akcipher_request + +Asymmetric Cipher API +--------------------- + +.. kernel-doc:: include/crypto/akcipher.h + :doc: Generic Public Key Cipher API + +.. kernel-doc:: include/crypto/akcipher.h + :functions: crypto_alloc_akcipher crypto_free_akcipher crypto_akcipher_set_pub_key crypto_akcipher_set_priv_key crypto_akcipher_maxsize crypto_akcipher_encrypt crypto_akcipher_decrypt + +Asymmetric Cipher Request Handle +-------------------------------- + +.. kernel-doc:: include/crypto/akcipher.h + :functions: akcipher_request_alloc akcipher_request_free akcipher_request_set_callback akcipher_request_set_crypt diff --git a/Documentation/crypto/api-digest.rst b/Documentation/crypto/api-digest.rst new file mode 100644 index 000000000..02a2bcc26 --- /dev/null +++ b/Documentation/crypto/api-digest.rst @@ -0,0 +1,38 @@ +Message Digest +============== + +Message Digest Algorithm Definitions +------------------------------------ + +.. kernel-doc:: include/crypto/hash.h + :doc: Message Digest Algorithm Definitions + +.. kernel-doc:: include/crypto/hash.h + :functions: hash_alg_common ahash_alg shash_alg + +Asynchronous Message Digest API +------------------------------- + +.. kernel-doc:: include/crypto/hash.h + :doc: Asynchronous Message Digest API + +.. kernel-doc:: include/crypto/hash.h + :functions: crypto_alloc_ahash crypto_free_ahash crypto_ahash_init crypto_ahash_digestsize crypto_ahash_reqtfm crypto_ahash_reqsize crypto_ahash_statesize crypto_ahash_setkey crypto_ahash_finup crypto_ahash_final crypto_ahash_digest crypto_ahash_export crypto_ahash_import + +Asynchronous Hash Request Handle +-------------------------------- + +.. kernel-doc:: include/crypto/hash.h + :doc: Asynchronous Hash Request Handle + +.. kernel-doc:: include/crypto/hash.h + :functions: ahash_request_set_tfm ahash_request_alloc ahash_request_free ahash_request_set_callback ahash_request_set_crypt + +Synchronous Message Digest API +------------------------------ + +.. kernel-doc:: include/crypto/hash.h + :doc: Synchronous Message Digest API + +.. kernel-doc:: include/crypto/hash.h + :functions: crypto_alloc_shash crypto_free_shash crypto_shash_blocksize crypto_shash_digestsize crypto_shash_descsize crypto_shash_setkey crypto_shash_digest crypto_shash_export crypto_shash_import crypto_shash_init crypto_shash_update crypto_shash_final crypto_shash_finup diff --git a/Documentation/crypto/api-intro.rst b/Documentation/crypto/api-intro.rst new file mode 100644 index 000000000..15201be0b --- /dev/null +++ b/Documentation/crypto/api-intro.rst @@ -0,0 +1,262 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================= +Scatterlist Cryptographic API +============================= + +Introduction +============ + +The Scatterlist Crypto API takes page vectors (scatterlists) as +arguments, and works directly on pages. In some cases (e.g. ECB +mode ciphers), this will allow for pages to be encrypted in-place +with no copying. + +One of the initial goals of this design was to readily support IPsec, +so that processing can be applied to paged skb's without the need +for linearization. + + +Details +======= + +At the lowest level are algorithms, which register dynamically with the +API. + +'Transforms' are user-instantiated objects, which maintain state, handle all +of the implementation logic (e.g. manipulating page vectors) and provide an +abstraction to the underlying algorithms. However, at the user +level they are very simple. + +Conceptually, the API layering looks like this:: + + [transform api] (user interface) + [transform ops] (per-type logic glue e.g. cipher.c, compress.c) + [algorithm api] (for registering algorithms) + +The idea is to make the user interface and algorithm registration API +very simple, while hiding the core logic from both. Many good ideas +from existing APIs such as Cryptoapi and Nettle have been adapted for this. + +The API currently supports five main types of transforms: AEAD (Authenticated +Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and +Hashes. + +Please note that Block Ciphers is somewhat of a misnomer. It is in fact +meant to support all ciphers including stream ciphers. The difference +between Block Ciphers and Ciphers is that the latter operates on exactly +one block while the former can operate on an arbitrary amount of data, +subject to block size requirements (i.e., non-stream ciphers can only +process multiples of blocks). + +Here's an example of how to use the API:: + + #include <crypto/hash.h> + #include <linux/err.h> + #include <linux/scatterlist.h> + + struct scatterlist sg[2]; + char result[128]; + struct crypto_ahash *tfm; + struct ahash_request *req; + + tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC); + if (IS_ERR(tfm)) + fail(); + + /* ... set up the scatterlists ... */ + + req = ahash_request_alloc(tfm, GFP_ATOMIC); + if (!req) + fail(); + + ahash_request_set_callback(req, 0, NULL, NULL); + ahash_request_set_crypt(req, sg, result, 2); + + if (crypto_ahash_digest(req)) + fail(); + + ahash_request_free(req); + crypto_free_ahash(tfm); + + +Many real examples are available in the regression test module (tcrypt.c). + + +Developer Notes +=============== + +Transforms may only be allocated in user context, and cryptographic +methods may only be called from softirq and user contexts. For +transforms with a setkey method it too should only be called from +user context. + +When using the API for ciphers, performance will be optimal if each +scatterlist contains data which is a multiple of the cipher's block +size (typically 8 bytes). This prevents having to do any copying +across non-aligned page fragment boundaries. + + +Adding New Algorithms +===================== + +When submitting a new algorithm for inclusion, a mandatory requirement +is that at least a few test vectors from known sources (preferably +standards) be included. + +Converting existing well known code is preferred, as it is more likely +to have been reviewed and widely tested. If submitting code from LGPL +sources, please consider changing the license to GPL (see section 3 of +the LGPL). + +Algorithms submitted must also be generally patent-free (e.g. IDEA +will not be included in the mainline until around 2011), and be based +on a recognized standard and/or have been subjected to appropriate +peer review. + +Also check for any RFCs which may relate to the use of specific algorithms, +as well as general application notes such as RFC2451 ("The ESP CBC-Mode +Cipher Algorithms"). + +It's a good idea to avoid using lots of macros and use inlined functions +instead, as gcc does a good job with inlining, while excessive use of +macros can cause compilation problems on some platforms. + +Also check the TODO list at the web site listed below to see what people +might already be working on. + + +Bugs +==== + +Send bug reports to: + linux-crypto@vger.kernel.org + +Cc: + Herbert Xu <herbert@gondor.apana.org.au>, + David S. Miller <davem@redhat.com> + + +Further Information +=================== + +For further patches and various updates, including the current TODO +list, see: +http://gondor.apana.org.au/~herbert/crypto/ + + +Authors +======= + +- James Morris +- David S. Miller +- Herbert Xu + + +Credits +======= + +The following people provided invaluable feedback during the development +of the API: + + - Alexey Kuznetzov + - Rusty Russell + - Herbert Valerio Riedel + - Jeff Garzik + - Michael Richardson + - Andrew Morton + - Ingo Oeser + - Christoph Hellwig + +Portions of this API were derived from the following projects: + + Kerneli Cryptoapi (http://www.kerneli.org/) + - Alexander Kjeldaas + - Herbert Valerio Riedel + - Kyle McMartin + - Jean-Luc Cooke + - David Bryson + - Clemens Fruhwirth + - Tobias Ringstrom + - Harald Welte + +and; + + Nettle (https://www.lysator.liu.se/~nisse/nettle/) + - Niels Möller + +Original developers of the crypto algorithms: + + - Dana L. How (DES) + - Andrew Tridgell and Steve French (MD4) + - Colin Plumb (MD5) + - Steve Reid (SHA1) + - Jean-Luc Cooke (SHA256, SHA384, SHA512) + - Kazunori Miyazawa / USAGI (HMAC) + - Matthew Skala (Twofish) + - Dag Arne Osvik (Serpent) + - Brian Gladman (AES) + - Kartikey Mahendra Bhatt (CAST6) + - Jon Oberheide (ARC4) + - Jouni Malinen (Michael MIC) + - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) + +SHA1 algorithm contributors: + - Jean-Francois Dive + +DES algorithm contributors: + - Raimar Falke + - Gisle Sælensminde + - Niels Möller + +Blowfish algorithm contributors: + - Herbert Valerio Riedel + - Kyle McMartin + +Twofish algorithm contributors: + - Werner Koch + - Marc Mutz + +SHA256/384/512 algorithm contributors: + - Andrew McDonald + - Kyle McMartin + - Herbert Valerio Riedel + +AES algorithm contributors: + - Alexander Kjeldaas + - Herbert Valerio Riedel + - Kyle McMartin + - Adam J. Richter + - Fruhwirth Clemens (i586) + - Linus Torvalds (i586) + +CAST5 algorithm contributors: + - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright). + +TEA/XTEA algorithm contributors: + - Aaron Grothe + - Michael Ringe + +Khazad algorithm contributors: + - Aaron Grothe + +Whirlpool algorithm contributors: + - Aaron Grothe + - Jean-Luc Cooke + +Anubis algorithm contributors: + - Aaron Grothe + +Tiger algorithm contributors: + - Aaron Grothe + +VIA PadLock contributors: + - Michal Ludvig + +Camellia algorithm contributors: + - NTT(Nippon Telegraph and Telephone Corporation) (Camellia) + +Generic scatterwalk code by Adam J. Richter <adam@yggdrasil.com> + +Please send any credits updates or corrections to: +Herbert Xu <herbert@gondor.apana.org.au> diff --git a/Documentation/crypto/api-kpp.rst b/Documentation/crypto/api-kpp.rst new file mode 100644 index 000000000..5794e2d10 --- /dev/null +++ b/Documentation/crypto/api-kpp.rst @@ -0,0 +1,41 @@ +Key-agreement Protocol Primitives (KPP) +======================================= + +Key-agreement Protocol Primitives (KPP) Cipher Algorithm Definitions +-------------------------------------------------------------------- + +.. kernel-doc:: include/crypto/kpp.h + :functions: kpp_request crypto_kpp kpp_alg kpp_secret + +Key-agreement Protocol Primitives (KPP) Cipher API +-------------------------------------------------- + +.. kernel-doc:: include/crypto/kpp.h + :doc: Generic Key-agreement Protocol Primitives API + +.. kernel-doc:: include/crypto/kpp.h + :functions: crypto_alloc_kpp crypto_free_kpp crypto_kpp_set_secret crypto_kpp_generate_public_key crypto_kpp_compute_shared_secret crypto_kpp_maxsize + +Key-agreement Protocol Primitives (KPP) Cipher Request Handle +------------------------------------------------------------- + +.. kernel-doc:: include/crypto/kpp.h + :functions: kpp_request_alloc kpp_request_free kpp_request_set_callback kpp_request_set_input kpp_request_set_output + +ECDH Helper Functions +--------------------- + +.. kernel-doc:: include/crypto/ecdh.h + :doc: ECDH Helper Functions + +.. kernel-doc:: include/crypto/ecdh.h + :functions: ecdh crypto_ecdh_key_len crypto_ecdh_encode_key crypto_ecdh_decode_key + +DH Helper Functions +------------------- + +.. kernel-doc:: include/crypto/dh.h + :doc: DH Helper Functions + +.. kernel-doc:: include/crypto/dh.h + :functions: dh crypto_dh_key_len crypto_dh_encode_key crypto_dh_decode_key diff --git a/Documentation/crypto/api-rng.rst b/Documentation/crypto/api-rng.rst new file mode 100644 index 000000000..23a94c0b2 --- /dev/null +++ b/Documentation/crypto/api-rng.rst @@ -0,0 +1,17 @@ +Random Number Generator (RNG) +============================= + +Random Number Algorithm Definitions +----------------------------------- + +.. kernel-doc:: include/crypto/rng.h + :functions: rng_alg + +Crypto API Random Number API +---------------------------- + +.. kernel-doc:: include/crypto/rng.h + :doc: Random number generator API + +.. kernel-doc:: include/crypto/rng.h + :functions: crypto_alloc_rng crypto_rng_alg crypto_free_rng crypto_rng_generate crypto_rng_get_bytes crypto_rng_reset crypto_rng_seedsize diff --git a/Documentation/crypto/api-samples.rst b/Documentation/crypto/api-samples.rst new file mode 100644 index 000000000..388bb7d7a --- /dev/null +++ b/Documentation/crypto/api-samples.rst @@ -0,0 +1,187 @@ +Code Examples +============= + +Code Example For Symmetric Key Cipher Operation +----------------------------------------------- + +This code encrypts some data with AES-256-XTS. For sake of example, +all inputs are random bytes, the encryption is done in-place, and it's +assumed the code is running in a context where it can sleep. + +:: + + static int test_skcipher(void) + { + struct crypto_skcipher *tfm = NULL; + struct skcipher_request *req = NULL; + u8 *data = NULL; + const size_t datasize = 512; /* data size in bytes */ + struct scatterlist sg; + DECLARE_CRYPTO_WAIT(wait); + u8 iv[16]; /* AES-256-XTS takes a 16-byte IV */ + u8 key[64]; /* AES-256-XTS takes a 64-byte key */ + int err; + + /* + * Allocate a tfm (a transformation object) and set the key. + * + * In real-world use, a tfm and key are typically used for many + * encryption/decryption operations. But in this example, we'll just do a + * single encryption operation with it (which is not very efficient). + */ + + tfm = crypto_alloc_skcipher("xts(aes)", 0, 0); + if (IS_ERR(tfm)) { + pr_err("Error allocating xts(aes) handle: %ld\n", PTR_ERR(tfm)); + return PTR_ERR(tfm); + } + + get_random_bytes(key, sizeof(key)); + err = crypto_skcipher_setkey(tfm, key, sizeof(key)); + if (err) { + pr_err("Error setting key: %d\n", err); + goto out; + } + + /* Allocate a request object */ + req = skcipher_request_alloc(tfm, GFP_KERNEL); + if (!req) { + err = -ENOMEM; + goto out; + } + + /* Prepare the input data */ + data = kmalloc(datasize, GFP_KERNEL); + if (!data) { + err = -ENOMEM; + goto out; + } + get_random_bytes(data, datasize); + + /* Initialize the IV */ + get_random_bytes(iv, sizeof(iv)); + + /* + * Encrypt the data in-place. + * + * For simplicity, in this example we wait for the request to complete + * before proceeding, even if the underlying implementation is asynchronous. + * + * To decrypt instead of encrypt, just change crypto_skcipher_encrypt() to + * crypto_skcipher_decrypt(). + */ + sg_init_one(&sg, data, datasize); + skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG | + CRYPTO_TFM_REQ_MAY_SLEEP, + crypto_req_done, &wait); + skcipher_request_set_crypt(req, &sg, &sg, datasize, iv); + err = crypto_wait_req(crypto_skcipher_encrypt(req), &wait); + if (err) { + pr_err("Error encrypting data: %d\n", err); + goto out; + } + + pr_debug("Encryption was successful\n"); + out: + crypto_free_skcipher(tfm); + skcipher_request_free(req); + kfree(data); + return err; + } + + +Code Example For Use of Operational State Memory With SHASH +----------------------------------------------------------- + +:: + + + struct sdesc { + struct shash_desc shash; + char ctx[]; + }; + + static struct sdesc *init_sdesc(struct crypto_shash *alg) + { + struct sdesc *sdesc; + int size; + + size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); + sdesc = kmalloc(size, GFP_KERNEL); + if (!sdesc) + return ERR_PTR(-ENOMEM); + sdesc->shash.tfm = alg; + return sdesc; + } + + static int calc_hash(struct crypto_shash *alg, + const unsigned char *data, unsigned int datalen, + unsigned char *digest) + { + struct sdesc *sdesc; + int ret; + + sdesc = init_sdesc(alg); + if (IS_ERR(sdesc)) { + pr_info("can't alloc sdesc\n"); + return PTR_ERR(sdesc); + } + + ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); + kfree(sdesc); + return ret; + } + + static int test_hash(const unsigned char *data, unsigned int datalen, + unsigned char *digest) + { + struct crypto_shash *alg; + char *hash_alg_name = "sha1-padlock-nano"; + int ret; + + alg = crypto_alloc_shash(hash_alg_name, 0, 0); + if (IS_ERR(alg)) { + pr_info("can't alloc alg %s\n", hash_alg_name); + return PTR_ERR(alg); + } + ret = calc_hash(alg, data, datalen, digest); + crypto_free_shash(alg); + return ret; + } + + +Code Example For Random Number Generator Usage +---------------------------------------------- + +:: + + + static int get_random_numbers(u8 *buf, unsigned int len) + { + struct crypto_rng *rng = NULL; + char *drbg = "stdrng"; + int ret; + + if (!buf || !len) { + pr_debug("No output buffer provided\n"); + return -EINVAL; + } + + rng = crypto_alloc_rng(drbg, 0, 0); + if (IS_ERR(rng)) { + pr_debug("could not allocate RNG handle for %s\n", drbg); + return PTR_ERR(rng); + } + + ret = crypto_rng_get_bytes(rng, buf, len); + if (ret < 0) + pr_debug("generation of random numbers failed\n"); + else if (ret == 0) + pr_debug("RNG returned no data"); + else + pr_debug("RNG returned %d bytes of data\n", ret); + + out: + crypto_free_rng(rng); + return ret; + } diff --git a/Documentation/crypto/api-sig.rst b/Documentation/crypto/api-sig.rst new file mode 100644 index 000000000..4d8aba8ae --- /dev/null +++ b/Documentation/crypto/api-sig.rst @@ -0,0 +1,18 @@ +Asymmetric Signature +==================== + +Asymmetric Signature Algorithm Definitions +------------------------------------------ + +.. kernel-doc:: include/crypto/sig.h + :functions: sig_alg + +Asymmetric Signature API +------------------------ + +.. kernel-doc:: include/crypto/sig.h + :doc: Generic Public Key Signature API + +.. kernel-doc:: include/crypto/sig.h + :functions: crypto_alloc_sig crypto_free_sig crypto_sig_set_pubkey crypto_sig_set_privkey crypto_sig_keysize crypto_sig_maxsize crypto_sig_digestsize crypto_sig_sign crypto_sig_verify + diff --git a/Documentation/crypto/api-skcipher.rst b/Documentation/crypto/api-skcipher.rst new file mode 100644 index 000000000..4b7c81607 --- /dev/null +++ b/Documentation/crypto/api-skcipher.rst @@ -0,0 +1,38 @@ +Symmetric Key Cipher +==================== + +Block Cipher Algorithm Definitions +---------------------------------- + +.. kernel-doc:: include/linux/crypto.h + :doc: Block Cipher Algorithm Definitions + +.. kernel-doc:: include/linux/crypto.h + :functions: crypto_alg cipher_alg compress_alg + +Symmetric Key Cipher API +------------------------ + +.. kernel-doc:: include/crypto/skcipher.h + :doc: Symmetric Key Cipher API + +.. kernel-doc:: include/crypto/skcipher.h + :functions: crypto_alloc_skcipher crypto_free_skcipher crypto_has_skcipher crypto_skcipher_ivsize crypto_skcipher_blocksize crypto_skcipher_setkey crypto_skcipher_reqtfm crypto_skcipher_encrypt crypto_skcipher_decrypt + +Symmetric Key Cipher Request Handle +----------------------------------- + +.. kernel-doc:: include/crypto/skcipher.h + :doc: Symmetric Key Cipher Request Handle + +.. kernel-doc:: include/crypto/skcipher.h + :functions: crypto_skcipher_reqsize skcipher_request_set_tfm skcipher_request_alloc skcipher_request_free skcipher_request_set_callback skcipher_request_set_crypt + +Single Block Cipher API +----------------------- + +.. kernel-doc:: include/crypto/internal/cipher.h + :doc: Single Block Cipher API + +.. kernel-doc:: include/crypto/internal/cipher.h + :functions: crypto_alloc_cipher crypto_free_cipher crypto_has_cipher crypto_cipher_blocksize crypto_cipher_setkey crypto_cipher_encrypt_one crypto_cipher_decrypt_one diff --git a/Documentation/crypto/api.rst b/Documentation/crypto/api.rst new file mode 100644 index 000000000..8b2a90521 --- /dev/null +++ b/Documentation/crypto/api.rst @@ -0,0 +1,14 @@ +Programming Interface +===================== + +.. toctree:: + :caption: Table of contents + :maxdepth: 2 + + api-skcipher + api-aead + api-digest + api-rng + api-akcipher + api-sig + api-kpp diff --git a/Documentation/crypto/architecture.rst b/Documentation/crypto/architecture.rst new file mode 100644 index 000000000..ec2e99d99 --- /dev/null +++ b/Documentation/crypto/architecture.rst @@ -0,0 +1,414 @@ +Kernel Crypto API Architecture +============================== + +Cipher algorithm types +---------------------- + +The kernel crypto API provides different API calls for the following +cipher types: + +- Symmetric ciphers + +- AEAD ciphers + +- Message digest, including keyed message digest + +- Random number generation + +- User space interface + +Ciphers And Templates +--------------------- + +The kernel crypto API provides implementations of single block ciphers +and message digests. In addition, the kernel crypto API provides +numerous "templates" that can be used in conjunction with the single +block ciphers and message digests. Templates include all types of block +chaining mode, the HMAC mechanism, etc. + +Single block ciphers and message digests can either be directly used by +a caller or invoked together with a template to form multi-block ciphers +or keyed message digests. + +A single block cipher may even be called with multiple templates. +However, templates cannot be used without a single cipher. + +See /proc/crypto and search for "name". For example: + +- aes + +- ecb(aes) + +- cmac(aes) + +- ccm(aes) + +- rfc4106(gcm(aes)) + +- sha1 + +- hmac(sha1) + +- authenc(hmac(sha1),cbc(aes)) + +In these examples, "aes" and "sha1" are the ciphers and all others are +the templates. + +Synchronous And Asynchronous Operation +-------------------------------------- + +The kernel crypto API provides synchronous and asynchronous API +operations. + +When using the synchronous API operation, the caller invokes a cipher +operation which is performed synchronously by the kernel crypto API. +That means, the caller waits until the cipher operation completes. +Therefore, the kernel crypto API calls work like regular function calls. +For synchronous operation, the set of API calls is small and +conceptually similar to any other crypto library. + +Asynchronous operation is provided by the kernel crypto API which +implies that the invocation of a cipher operation will complete almost +instantly. That invocation triggers the cipher operation but it does not +signal its completion. Before invoking a cipher operation, the caller +must provide a callback function the kernel crypto API can invoke to +signal the completion of the cipher operation. Furthermore, the caller +must ensure it can handle such asynchronous events by applying +appropriate locking around its data. The kernel crypto API does not +perform any special serialization operation to protect the caller's data +integrity. + +Crypto API Cipher References And Priority +----------------------------------------- + +A cipher is referenced by the caller with a string. That string has the +following semantics: + +:: + + template(single block cipher) + + +where "template" and "single block cipher" is the aforementioned +template and single block cipher, respectively. If applicable, +additional templates may enclose other templates, such as + +:: + + template1(template2(single block cipher)) + + +The kernel crypto API may provide multiple implementations of a template +or a single block cipher. For example, AES on newer Intel hardware has +the following implementations: AES-NI, assembler implementation, or +straight C. Now, when using the string "aes" with the kernel crypto API, +which cipher implementation is used? The answer to that question is the +priority number assigned to each cipher implementation by the kernel +crypto API. When a caller uses the string to refer to a cipher during +initialization of a cipher handle, the kernel crypto API looks up all +implementations providing an implementation with that name and selects +the implementation with the highest priority. + +Now, a caller may have the need to refer to a specific cipher +implementation and thus does not want to rely on the priority-based +selection. To accommodate this scenario, the kernel crypto API allows +the cipher implementation to register a unique name in addition to +common names. When using that unique name, a caller is therefore always +sure to refer to the intended cipher implementation. + +The list of available ciphers is given in /proc/crypto. However, that +list does not specify all possible permutations of templates and +ciphers. Each block listed in /proc/crypto may contain the following +information -- if one of the components listed as follows are not +applicable to a cipher, it is not displayed: + +- name: the generic name of the cipher that is subject to the + priority-based selection -- this name can be used by the cipher + allocation API calls (all names listed above are examples for such + generic names) + +- driver: the unique name of the cipher -- this name can be used by the + cipher allocation API calls + +- module: the kernel module providing the cipher implementation (or + "kernel" for statically linked ciphers) + +- priority: the priority value of the cipher implementation + +- refcnt: the reference count of the respective cipher (i.e. the number + of current consumers of this cipher) + +- selftest: specification whether the self test for the cipher passed + +- type: + + - skcipher for symmetric key ciphers + + - cipher for single block ciphers that may be used with an + additional template + + - shash for synchronous message digest + + - ahash for asynchronous message digest + + - aead for AEAD cipher type + + - compression for compression type transformations + + - rng for random number generator + + - kpp for a Key-agreement Protocol Primitive (KPP) cipher such as + an ECDH or DH implementation + +- blocksize: blocksize of cipher in bytes + +- keysize: key size in bytes + +- ivsize: IV size in bytes + +- seedsize: required size of seed data for random number generator + +- digestsize: output size of the message digest + +- geniv: IV generator (obsolete) + +Key Sizes +--------- + +When allocating a cipher handle, the caller only specifies the cipher +type. Symmetric ciphers, however, typically support multiple key sizes +(e.g. AES-128 vs. AES-192 vs. AES-256). These key sizes are determined +with the length of the provided key. Thus, the kernel crypto API does +not provide a separate way to select the particular symmetric cipher key +size. + +Cipher Allocation Type And Masks +-------------------------------- + +The different cipher handle allocation functions allow the specification +of a type and mask flag. Both parameters have the following meaning (and +are therefore not covered in the subsequent sections). + +The type flag specifies the type of the cipher algorithm. The caller +usually provides a 0 when the caller wants the default handling. +Otherwise, the caller may provide the following selections which match +the aforementioned cipher types: + +- CRYPTO_ALG_TYPE_CIPHER Single block cipher + +- CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Data + (MAC) + +- CRYPTO_ALG_TYPE_KPP Key-agreement Protocol Primitive (KPP) such as + an ECDH or DH implementation + +- CRYPTO_ALG_TYPE_HASH Raw message digest + +- CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash + +- CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash + +- CRYPTO_ALG_TYPE_RNG Random Number Generation + +- CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher + +- CRYPTO_ALG_TYPE_SIG Asymmetric signature + +- CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of + CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / + decompression instead of performing the operation on one segment + only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace + CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted. + +The mask flag restricts the type of cipher. The only allowed flag is +CRYPTO_ALG_ASYNC to restrict the cipher lookup function to +asynchronous ciphers. Usually, a caller provides a 0 for the mask flag. + +When the caller provides a mask and type specification, the caller +limits the search the kernel crypto API can perform for a suitable +cipher implementation for the given cipher name. That means, even when a +caller uses a cipher name that exists during its initialization call, +the kernel crypto API may not select it due to the used type and mask +field. + +Internal Structure of Kernel Crypto API +--------------------------------------- + +The kernel crypto API has an internal structure where a cipher +implementation may use many layers and indirections. This section shall +help to clarify how the kernel crypto API uses various components to +implement the complete cipher. + +The following subsections explain the internal structure based on +existing cipher implementations. The first section addresses the most +complex scenario where all other scenarios form a logical subset. + +Generic AEAD Cipher Structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following ASCII art decomposes the kernel crypto API layers when +using the AEAD cipher with the automated IV generation. The shown +example is used by the IPSEC layer. + +For other use cases of AEAD ciphers, the ASCII art applies as well, but +the caller may not use the AEAD cipher with a separate IV generator. In +this case, the caller must generate the IV. + +The depicted example decomposes the AEAD cipher of GCM(AES) based on the +generic C implementations (gcm.c, aes-generic.c, ctr.c, ghash-generic.c, +seqiv.c). The generic implementation serves as an example showing the +complete logic of the kernel crypto API. + +It is possible that some streamlined cipher implementations (like +AES-NI) provide implementations merging aspects which in the view of the +kernel crypto API cannot be decomposed into layers any more. In case of +the AES-NI implementation, the CTR mode, the GHASH implementation and +the AES cipher are all merged into one cipher implementation registered +with the kernel crypto API. In this case, the concept described by the +following ASCII art applies too. However, the decomposition of GCM into +the individual sub-components by the kernel crypto API is not done any +more. + +Each block in the following ASCII art is an independent cipher instance +obtained from the kernel crypto API. Each block is accessed by the +caller or by other blocks using the API functions defined by the kernel +crypto API for the cipher implementation type. + +The blocks below indicate the cipher type as well as the specific logic +implemented in the cipher. + +The ASCII art picture also indicates the call structure, i.e. who calls +which component. The arrows point to the invoked block where the caller +uses the API applicable to the cipher type specified for the block. + +:: + + + kernel crypto API | IPSEC Layer + | + +-----------+ | + | | (1) + | aead | <----------------------------------- esp_output + | (seqiv) | ---+ + +-----------+ | + | (2) + +-----------+ | + | | <--+ (2) + | aead | <----------------------------------- esp_input + | (gcm) | ------------+ + +-----------+ | + | (3) | (5) + v v + +-----------+ +-----------+ + | | | | + | skcipher | | ahash | + | (ctr) | ---+ | (ghash) | + +-----------+ | +-----------+ + | + +-----------+ | (4) + | | <--+ + | cipher | + | (aes) | + +-----------+ + + + +The following call sequence is applicable when the IPSEC layer triggers +an encryption operation with the esp_output function. During +configuration, the administrator set up the use of seqiv(rfc4106(gcm(aes))) +as the cipher for ESP. The following call sequence is now depicted in +the ASCII art above: + +1. esp_output() invokes crypto_aead_encrypt() to trigger an + encryption operation of the AEAD cipher with IV generator. + + The SEQIV generates the IV. + +2. Now, SEQIV uses the AEAD API function calls to invoke the associated + AEAD cipher. In our case, during the instantiation of SEQIV, the + cipher handle for GCM is provided to SEQIV. This means that SEQIV + invokes AEAD cipher operations with the GCM cipher handle. + + During instantiation of the GCM handle, the CTR(AES) and GHASH + ciphers are instantiated. The cipher handles for CTR(AES) and GHASH + are retained for later use. + + The GCM implementation is responsible to invoke the CTR mode AES and + the GHASH cipher in the right manner to implement the GCM + specification. + +3. The GCM AEAD cipher type implementation now invokes the SKCIPHER API + with the instantiated CTR(AES) cipher handle. + + During instantiation of the CTR(AES) cipher, the CIPHER type + implementation of AES is instantiated. The cipher handle for AES is + retained. + + That means that the SKCIPHER implementation of CTR(AES) only + implements the CTR block chaining mode. After performing the block + chaining operation, the CIPHER implementation of AES is invoked. + +4. The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES + cipher handle to encrypt one block. + +5. The GCM AEAD implementation also invokes the GHASH cipher + implementation via the AHASH API. + +When the IPSEC layer triggers the esp_input() function, the same call +sequence is followed with the only difference that the operation starts +with step (2). + +Generic Block Cipher Structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Generic block ciphers follow the same concept as depicted with the ASCII +art picture above. + +For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The +ASCII art picture above applies as well with the difference that only +step (4) is used and the SKCIPHER block chaining mode is CBC. + +Generic Keyed Message Digest Structure +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Keyed message digest implementations again follow the same concept as +depicted in the ASCII art picture above. + +For example, HMAC(SHA256) is implemented with hmac.c and +sha256_generic.c. The following ASCII art illustrates the +implementation: + +:: + + + kernel crypto API | Caller + | + +-----------+ (1) | + | | <------------------ some_function + | ahash | + | (hmac) | ---+ + +-----------+ | + | (2) + +-----------+ | + | | <--+ + | shash | + | (sha256) | + +-----------+ + + + +The following call sequence is applicable when a caller triggers an HMAC +operation: + +1. The AHASH API functions are invoked by the caller. The HMAC + implementation performs its operation as needed. + + During initialization of the HMAC cipher, the SHASH cipher type of + SHA256 is instantiated. The cipher handle for the SHA256 instance is + retained. + + At one time, the HMAC implementation requires a SHA256 operation + where the SHA256 cipher handle is used. + +2. The HMAC instance now invokes the SHASH API with the SHA256 cipher + handle to calculate the message digest. diff --git a/Documentation/crypto/asymmetric-keys.rst b/Documentation/crypto/asymmetric-keys.rst new file mode 100644 index 000000000..349f44a29 --- /dev/null +++ b/Documentation/crypto/asymmetric-keys.rst @@ -0,0 +1,424 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============================================= +Asymmetric / Public-key Cryptography Key Type +============================================= + +.. Contents: + + - Overview. + - Key identification. + - Accessing asymmetric keys. + - Signature verification. + - Asymmetric key subtypes. + - Instantiation data parsers. + - Keyring link restrictions. + + +Overview +======== + +The "asymmetric" key type is designed to be a container for the keys used in +public-key cryptography, without imposing any particular restrictions on the +form or mechanism of the cryptography or form of the key. + +The asymmetric key is given a subtype that defines what sort of data is +associated with the key and provides operations to describe and destroy it. +However, no requirement is made that the key data actually be stored in the +key. + +A completely in-kernel key retention and operation subtype can be defined, but +it would also be possible to provide access to cryptographic hardware (such as +a TPM) that might be used to both retain the relevant key and perform +operations using that key. In such a case, the asymmetric key would then +merely be an interface to the TPM driver. + +Also provided is the concept of a data parser. Data parsers are responsible +for extracting information from the blobs of data passed to the instantiation +function. The first data parser that recognises the blob gets to set the +subtype of the key and define the operations that can be done on that key. + +A data parser may interpret the data blob as containing the bits representing a +key, or it may interpret it as a reference to a key held somewhere else in the +system (for example, a TPM). + + +Key Identification +================== + +If a key is added with an empty name, the instantiation data parsers are given +the opportunity to pre-parse a key and to determine the description the key +should be given from the content of the key. + +This can then be used to refer to the key, either by complete match or by +partial match. The key type may also use other criteria to refer to a key. + +The asymmetric key type's match function can then perform a wider range of +comparisons than just the straightforward comparison of the description with +the criterion string: + + 1) If the criterion string is of the form "id:<hexdigits>" then the match + function will examine a key's fingerprint to see if the hex digits given + after the "id:" match the tail. For instance:: + + keyctl search @s asymmetric id:5acc2142 + + will match a key with fingerprint:: + + 1A00 2040 7601 7889 DE11 882C 3823 04AD 5ACC 2142 + + 2) If the criterion string is of the form "<subtype>:<hexdigits>" then the + match will match the ID as in (1), but with the added restriction that + only keys of the specified subtype (e.g. tpm) will be matched. For + instance:: + + keyctl search @s asymmetric tpm:5acc2142 + +Looking in /proc/keys, the last 8 hex digits of the key fingerprint are +displayed, along with the subtype:: + + 1a39e171 I----- 1 perm 3f010000 0 0 asymmetric modsign.0: DSA 5acc2142 [] + + +Accessing Asymmetric Keys +========================= + +For general access to asymmetric keys from within the kernel, the following +inclusion is required:: + + #include <crypto/public_key.h> + +This gives access to functions for dealing with asymmetric / public keys. +Three enums are defined there for representing public-key cryptography +algorithms:: + + enum pkey_algo + +digest algorithms used by those:: + + enum pkey_hash_algo + +and key identifier representations:: + + enum pkey_id_type + +Note that the key type representation types are required because key +identifiers from different standards aren't necessarily compatible. For +instance, PGP generates key identifiers by hashing the key data plus some +PGP-specific metadata, whereas X.509 has arbitrary certificate identifiers. + +The operations defined upon a key are: + + 1) Signature verification. + +Other operations are possible (such as encryption) with the same key data +required for verification, but not currently supported, and others +(eg. decryption and signature generation) require extra key data. + + +Signature Verification +---------------------- + +An operation is provided to perform cryptographic signature verification, using +an asymmetric key to provide or to provide access to the public key:: + + int verify_signature(const struct key *key, + const struct public_key_signature *sig); + +The caller must have already obtained the key from some source and can then use +it to check the signature. The caller must have parsed the signature and +transferred the relevant bits to the structure pointed to by sig:: + + struct public_key_signature { + u8 *digest; + u8 digest_size; + enum pkey_hash_algo pkey_hash_algo : 8; + u8 nr_mpi; + union { + MPI mpi[2]; + ... + }; + }; + +The algorithm used must be noted in sig->pkey_hash_algo, and all the MPIs that +make up the actual signature must be stored in sig->mpi[] and the count of MPIs +placed in sig->nr_mpi. + +In addition, the data must have been digested by the caller and the resulting +hash must be pointed to by sig->digest and the size of the hash be placed in +sig->digest_size. + +The function will return 0 upon success or -EKEYREJECTED if the signature +doesn't match. + +The function may also return -ENOTSUPP if an unsupported public-key algorithm +or public-key/hash algorithm combination is specified or the key doesn't +support the operation; -EBADMSG or -ERANGE if some of the parameters have weird +data; or -ENOMEM if an allocation can't be performed. -EINVAL can be returned +if the key argument is the wrong type or is incompletely set up. + + +Asymmetric Key Subtypes +======================= + +Asymmetric keys have a subtype that defines the set of operations that can be +performed on that key and that determines what data is attached as the key +payload. The payload format is entirely at the whim of the subtype. + +The subtype is selected by the key data parser and the parser must initialise +the data required for it. The asymmetric key retains a reference on the +subtype module. + +The subtype definition structure can be found in:: + + #include <keys/asymmetric-subtype.h> + +and looks like the following:: + + struct asymmetric_key_subtype { + struct module *owner; + const char *name; + + void (*describe)(const struct key *key, struct seq_file *m); + void (*destroy)(void *payload); + int (*query)(const struct kernel_pkey_params *params, + struct kernel_pkey_query *info); + int (*eds_op)(struct kernel_pkey_params *params, + const void *in, void *out); + int (*verify_signature)(const struct key *key, + const struct public_key_signature *sig); + }; + +Asymmetric keys point to this with their payload[asym_subtype] member. + +The owner and name fields should be set to the owning module and the name of +the subtype. Currently, the name is only used for print statements. + +There are a number of operations defined by the subtype: + + 1) describe(). + + Mandatory. This allows the subtype to display something in /proc/keys + against the key. For instance the name of the public key algorithm type + could be displayed. The key type will display the tail of the key + identity string after this. + + 2) destroy(). + + Mandatory. This should free the memory associated with the key. The + asymmetric key will look after freeing the fingerprint and releasing the + reference on the subtype module. + + 3) query(). + + Mandatory. This is a function for querying the capabilities of a key. + + 4) eds_op(). + + Optional. This is the entry point for the encryption, decryption and + signature creation operations (which are distinguished by the operation ID + in the parameter struct). The subtype may do anything it likes to + implement an operation, including offloading to hardware. + + 5) verify_signature(). + + Optional. This is the entry point for signature verification. The + subtype may do anything it likes to implement an operation, including + offloading to hardware. + +Instantiation Data Parsers +========================== + +The asymmetric key type doesn't generally want to store or to deal with a raw +blob of data that holds the key data. It would have to parse it and error +check it each time it wanted to use it. Further, the contents of the blob may +have various checks that can be performed on it (eg. self-signatures, validity +dates) and may contain useful data about the key (identifiers, capabilities). + +Also, the blob may represent a pointer to some hardware containing the key +rather than the key itself. + +Examples of blob formats for which parsers could be implemented include: + + - OpenPGP packet stream [RFC 4880]. + - X.509 ASN.1 stream. + - Pointer to TPM key. + - Pointer to UEFI key. + - PKCS#8 private key [RFC 5208]. + - PKCS#5 encrypted private key [RFC 2898]. + +During key instantiation each parser in the list is tried until one doesn't +return -EBADMSG. + +The parser definition structure can be found in:: + + #include <keys/asymmetric-parser.h> + +and looks like the following:: + + struct asymmetric_key_parser { + struct module *owner; + const char *name; + + int (*parse)(struct key_preparsed_payload *prep); + }; + +The owner and name fields should be set to the owning module and the name of +the parser. + +There is currently only a single operation defined by the parser, and it is +mandatory: + + 1) parse(). + + This is called to preparse the key from the key creation and update paths. + In particular, it is called during the key creation _before_ a key is + allocated, and as such, is permitted to provide the key's description in + the case that the caller declines to do so. + + The caller passes a pointer to the following struct with all of the fields + cleared, except for data, datalen and quotalen [see + Documentation/security/keys/core.rst]:: + + struct key_preparsed_payload { + char *description; + void *payload[4]; + const void *data; + size_t datalen; + size_t quotalen; + }; + + The instantiation data is in a blob pointed to by data and is datalen in + size. The parse() function is not permitted to change these two values at + all, and shouldn't change any of the other values _unless_ they are + recognise the blob format and will not return -EBADMSG to indicate it is + not theirs. + + If the parser is happy with the blob, it should propose a description for + the key and attach it to ->description, ->payload[asym_subtype] should be + set to point to the subtype to be used, ->payload[asym_crypto] should be + set to point to the initialised data for that subtype, + ->payload[asym_key_ids] should point to one or more hex fingerprints and + quotalen should be updated to indicate how much quota this key should + account for. + + When clearing up, the data attached to ->payload[asym_key_ids] and + ->description will be kfree()'d and the data attached to + ->payload[asm_crypto] will be passed to the subtype's ->destroy() method + to be disposed of. A module reference for the subtype pointed to by + ->payload[asym_subtype] will be put. + + + If the data format is not recognised, -EBADMSG should be returned. If it + is recognised, but the key cannot for some reason be set up, some other + negative error code should be returned. On success, 0 should be returned. + + The key's fingerprint string may be partially matched upon. For a + public-key algorithm such as RSA and DSA this will likely be a printable + hex version of the key's fingerprint. + +Functions are provided to register and unregister parsers:: + + int register_asymmetric_key_parser(struct asymmetric_key_parser *parser); + void unregister_asymmetric_key_parser(struct asymmetric_key_parser *subtype); + +Parsers may not have the same name. The names are otherwise only used for +displaying in debugging messages. + + +Keyring Link Restrictions +========================= + +Keyrings created from userspace using add_key can be configured to check the +signature of the key being linked. Keys without a valid signature are not +allowed to link. + +Several restriction methods are available: + + 1) Restrict using the kernel builtin trusted keyring + + - Option string used with KEYCTL_RESTRICT_KEYRING: + - "builtin_trusted" + + The kernel builtin trusted keyring will be searched for the signing key. + If the builtin trusted keyring is not configured, all links will be + rejected. The ca_keys kernel parameter also affects which keys are used + for signature verification. + + 2) Restrict using the kernel builtin and secondary trusted keyrings + + - Option string used with KEYCTL_RESTRICT_KEYRING: + - "builtin_and_secondary_trusted" + + The kernel builtin and secondary trusted keyrings will be searched for the + signing key. If the secondary trusted keyring is not configured, this + restriction will behave like the "builtin_trusted" option. The ca_keys + kernel parameter also affects which keys are used for signature + verification. + + 3) Restrict using a separate key or keyring + + - Option string used with KEYCTL_RESTRICT_KEYRING: + - "key_or_keyring:<key or keyring serial number>[:chain]" + + Whenever a key link is requested, the link will only succeed if the key + being linked is signed by one of the designated keys. This key may be + specified directly by providing a serial number for one asymmetric key, or + a group of keys may be searched for the signing key by providing the + serial number for a keyring. + + When the "chain" option is provided at the end of the string, the keys + within the destination keyring will also be searched for signing keys. + This allows for verification of certificate chains by adding each + certificate in order (starting closest to the root) to a keyring. For + instance, one keyring can be populated with links to a set of root + certificates, with a separate, restricted keyring set up for each + certificate chain to be validated:: + + # Create and populate a keyring for root certificates + root_id=`keyctl add keyring root-certs "" @s` + keyctl padd asymmetric "" $root_id < root1.cert + keyctl padd asymmetric "" $root_id < root2.cert + + # Create and restrict a keyring for the certificate chain + chain_id=`keyctl add keyring chain "" @s` + keyctl restrict_keyring $chain_id asymmetric key_or_keyring:$root_id:chain + + # Attempt to add each certificate in the chain, starting with the + # certificate closest to the root. + keyctl padd asymmetric "" $chain_id < intermediateA.cert + keyctl padd asymmetric "" $chain_id < intermediateB.cert + keyctl padd asymmetric "" $chain_id < end-entity.cert + + If the final end-entity certificate is successfully added to the "chain" + keyring, we can be certain that it has a valid signing chain going back to + one of the root certificates. + + A single keyring can be used to verify a chain of signatures by + restricting the keyring after linking the root certificate:: + + # Create a keyring for the certificate chain and add the root + chain2_id=`keyctl add keyring chain2 "" @s` + keyctl padd asymmetric "" $chain2_id < root1.cert + + # Restrict the keyring that already has root1.cert linked. The cert + # will remain linked by the keyring. + keyctl restrict_keyring $chain2_id asymmetric key_or_keyring:0:chain + + # Attempt to add each certificate in the chain, starting with the + # certificate closest to the root. + keyctl padd asymmetric "" $chain2_id < intermediateA.cert + keyctl padd asymmetric "" $chain2_id < intermediateB.cert + keyctl padd asymmetric "" $chain2_id < end-entity.cert + + If the final end-entity certificate is successfully added to the "chain2" + keyring, we can be certain that there is a valid signing chain going back + to the root certificate that was added before the keyring was restricted. + + +In all of these cases, if the signing key is found the signature of the key to +be linked will be verified using the signing key. The requested key is added +to the keyring only if the signature is successfully verified. -ENOKEY is +returned if the parent certificate could not be found, or -EKEYREJECTED is +returned if the signature check fails or the key is blacklisted. Other errors +may be returned if the signature check could not be performed. diff --git a/Documentation/crypto/async-tx-api.rst b/Documentation/crypto/async-tx-api.rst new file mode 100644 index 000000000..49fcfc663 --- /dev/null +++ b/Documentation/crypto/async-tx-api.rst @@ -0,0 +1,270 @@ +.. SPDX-License-Identifier: GPL-2.0 + +===================================== +Asynchronous Transfers/Transforms API +===================================== + +.. Contents + + 1. INTRODUCTION + + 2 GENEALOGY + + 3 USAGE + 3.1 General format of the API + 3.2 Supported operations + 3.3 Descriptor management + 3.4 When does the operation execute? + 3.5 When does the operation complete? + 3.6 Constraints + 3.7 Example + + 4 DMAENGINE DRIVER DEVELOPER NOTES + 4.1 Conformance points + 4.2 "My application needs exclusive control of hardware channels" + + 5 SOURCE + +1. Introduction +=============== + +The async_tx API provides methods for describing a chain of asynchronous +bulk memory transfers/transforms with support for inter-transactional +dependencies. It is implemented as a dmaengine client that smooths over +the details of different hardware offload engine implementations. Code +that is written to the API can optimize for asynchronous operation and +the API will fit the chain of operations to the available offload +resources. + +2.Genealogy +=========== + +The API was initially designed to offload the memory copy and +xor-parity-calculations of the md-raid5 driver using the offload engines +present in the Intel(R) Xscale series of I/O processors. It also built +on the 'dmaengine' layer developed for offloading memory copies in the +network stack using Intel(R) I/OAT engines. The following design +features surfaced as a result: + +1. implicit synchronous path: users of the API do not need to know if + the platform they are running on has offload capabilities. The + operation will be offloaded when an engine is available and carried out + in software otherwise. +2. cross channel dependency chains: the API allows a chain of dependent + operations to be submitted, like xor->copy->xor in the raid5 case. The + API automatically handles cases where the transition from one operation + to another implies a hardware channel switch. +3. dmaengine extensions to support multiple clients and operation types + beyond 'memcpy' + +3. Usage +======== + +3.1 General format of the API +----------------------------- + +:: + + struct dma_async_tx_descriptor * + async_<operation>(<op specific parameters>, struct async_submit_ctl *submit) + +3.2 Supported operations +------------------------ + +======== ==================================================================== +memcpy memory copy between a source and a destination buffer +memset fill a destination buffer with a byte value +xor xor a series of source buffers and write the result to a + destination buffer +xor_val xor a series of source buffers and set a flag if the + result is zero. The implementation attempts to prevent + writes to memory +pq generate the p+q (raid6 syndrome) from a series of source buffers +pq_val validate that a p and or q buffer are in sync with a given series of + sources +datap (raid6_recov_datap) recover a raid6 data block and the p block + from the given sources +2data (raid6_recov_2data) recover 2 raid6 data blocks from the given + sources +======== ==================================================================== + +3.3 Descriptor management +------------------------- + +The return value is non-NULL and points to a 'descriptor' when the operation +has been queued to execute asynchronously. Descriptors are recycled +resources, under control of the offload engine driver, to be reused as +operations complete. When an application needs to submit a chain of +operations it must guarantee that the descriptor is not automatically recycled +before the dependency is submitted. This requires that all descriptors be +acknowledged by the application before the offload engine driver is allowed to +recycle (or free) the descriptor. A descriptor can be acked by one of the +following methods: + +1. setting the ASYNC_TX_ACK flag if no child operations are to be submitted +2. submitting an unacknowledged descriptor as a dependency to another + async_tx call will implicitly set the acknowledged state. +3. calling async_tx_ack() on the descriptor. + +3.4 When does the operation execute? +------------------------------------ + +Operations do not immediately issue after return from the +async_<operation> call. Offload engine drivers batch operations to +improve performance by reducing the number of mmio cycles needed to +manage the channel. Once a driver-specific threshold is met the driver +automatically issues pending operations. An application can force this +event by calling async_tx_issue_pending_all(). This operates on all +channels since the application has no knowledge of channel to operation +mapping. + +3.5 When does the operation complete? +------------------------------------- + +There are two methods for an application to learn about the completion +of an operation. + +1. Call dma_wait_for_async_tx(). This call causes the CPU to spin while + it polls for the completion of the operation. It handles dependency + chains and issuing pending operations. +2. Specify a completion callback. The callback routine runs in tasklet + context if the offload engine driver supports interrupts, or it is + called in application context if the operation is carried out + synchronously in software. The callback can be set in the call to + async_<operation>, or when the application needs to submit a chain of + unknown length it can use the async_trigger_callback() routine to set a + completion interrupt/callback at the end of the chain. + +3.6 Constraints +--------------- + +1. Calls to async_<operation> are not permitted in IRQ context. Other + contexts are permitted provided constraint #2 is not violated. +2. Completion callback routines cannot submit new operations. This + results in recursion in the synchronous case and spin_locks being + acquired twice in the asynchronous case. + +3.7 Example +----------- + +Perform a xor->copy->xor operation where each operation depends on the +result from the previous operation:: + + #include <linux/async_tx.h> + + static void callback(void *param) + { + complete(param); + } + + #define NDISKS 2 + + static void run_xor_copy_xor(struct page **xor_srcs, + struct page *xor_dest, + size_t xor_len, + struct page *copy_src, + struct page *copy_dest, + size_t copy_len) + { + struct dma_async_tx_descriptor *tx; + struct async_submit_ctl submit; + addr_conv_t addr_conv[NDISKS]; + struct completion cmp; + + init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST, NULL, NULL, NULL, + addr_conv); + tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit); + + submit.depend_tx = tx; + tx = async_memcpy(copy_dest, copy_src, 0, 0, copy_len, &submit); + + init_completion(&cmp); + init_async_submit(&submit, ASYNC_TX_XOR_DROP_DST | ASYNC_TX_ACK, tx, + callback, &cmp, addr_conv); + tx = async_xor(xor_dest, xor_srcs, 0, NDISKS, xor_len, &submit); + + async_tx_issue_pending_all(); + + wait_for_completion(&cmp); + } + +See include/linux/async_tx.h for more information on the flags. See the +ops_run_* and ops_complete_* routines in drivers/md/raid5.c for more +implementation examples. + +4. Driver Development Notes +=========================== + +4.1 Conformance points +---------------------- + +There are a few conformance points required in dmaengine drivers to +accommodate assumptions made by applications using the async_tx API: + +1. Completion callbacks are expected to happen in tasklet context +2. dma_async_tx_descriptor fields are never manipulated in IRQ context +3. Use async_tx_run_dependencies() in the descriptor clean up path to + handle submission of dependent operations + +4.2 "My application needs exclusive control of hardware channels" +----------------------------------------------------------------- + +Primarily this requirement arises from cases where a DMA engine driver +is being used to support device-to-memory operations. A channel that is +performing these operations cannot, for many platform specific reasons, +be shared. For these cases the dma_request_channel() interface is +provided. + +The interface is:: + + struct dma_chan *dma_request_channel(dma_cap_mask_t mask, + dma_filter_fn filter_fn, + void *filter_param); + +Where dma_filter_fn is defined as:: + + typedef bool (*dma_filter_fn)(struct dma_chan *chan, void *filter_param); + +When the optional 'filter_fn' parameter is set to NULL +dma_request_channel simply returns the first channel that satisfies the +capability mask. Otherwise, when the mask parameter is insufficient for +specifying the necessary channel, the filter_fn routine can be used to +disposition the available channels in the system. The filter_fn routine +is called once for each free channel in the system. Upon seeing a +suitable channel filter_fn returns DMA_ACK which flags that channel to +be the return value from dma_request_channel. A channel allocated via +this interface is exclusive to the caller, until dma_release_channel() +is called. + +The DMA_PRIVATE capability flag is used to tag dma devices that should +not be used by the general-purpose allocator. It can be set at +initialization time if it is known that a channel will always be +private. Alternatively, it is set when dma_request_channel() finds an +unused "public" channel. + +A couple caveats to note when implementing a driver and consumer: + +1. Once a channel has been privately allocated it will no longer be + considered by the general-purpose allocator even after a call to + dma_release_channel(). +2. Since capabilities are specified at the device level a dma_device + with multiple channels will either have all channels public, or all + channels private. + +5. Source +--------- + +include/linux/dmaengine.h: + core header file for DMA drivers and api users +drivers/dma/dmaengine.c: + offload engine channel management routines +drivers/dma/: + location for offload engine drivers +include/linux/async_tx.h: + core header file for the async_tx api +crypto/async_tx/async_tx.c: + async_tx interface to dmaengine and common code +crypto/async_tx/async_memcpy.c: + copy offload +crypto/async_tx/async_xor.c: + xor and xor zero sum offload diff --git a/Documentation/crypto/crypto_engine.rst b/Documentation/crypto/crypto_engine.rst new file mode 100644 index 000000000..7ef850e28 --- /dev/null +++ b/Documentation/crypto/crypto_engine.rst @@ -0,0 +1,80 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Crypto Engine +============= + +Overview +-------- +The crypto engine (CE) API is a crypto queue manager. + +Requirement +----------- +You must put, at the start of your transform context your_tfm_ctx, the structure +crypto_engine: + +:: + + struct your_tfm_ctx { + struct crypto_engine engine; + ... + }; + +The crypto engine only manages asynchronous requests in the form of +crypto_async_request. It cannot know the underlying request type and thus only +has access to the transform structure. It is not possible to access the context +using container_of. In addition, the engine knows nothing about your +structure "``struct your_tfm_ctx``". The engine assumes (requires) the placement +of the known member ``struct crypto_engine`` at the beginning. + +Order of operations +------------------- +You are required to obtain a struct crypto_engine via ``crypto_engine_alloc_init()``. +Start it via ``crypto_engine_start()``. When finished with your work, shut down the +engine using ``crypto_engine_stop()`` and destroy the engine with +``crypto_engine_exit()``. + +Before transferring any request, you have to fill the context enginectx by +providing functions for the following: + +* ``prepare_cipher_request``/``prepare_hash_request``: Called before each + corresponding request is performed. If some processing or other preparatory + work is required, do it here. + +* ``unprepare_cipher_request``/``unprepare_hash_request``: Called after each + request is handled. Clean up / undo what was done in the prepare function. + +* ``cipher_one_request``/``hash_one_request``: Handle the current request by + performing the operation. + +Note that these functions access the crypto_async_request structure +associated with the received request. You are able to retrieve the original +request by using: + +:: + + container_of(areq, struct yourrequesttype_request, base); + +When your driver receives a crypto_request, you must to transfer it to +the crypto engine via one of: + +* crypto_transfer_aead_request_to_engine() + +* crypto_transfer_akcipher_request_to_engine() + +* crypto_transfer_hash_request_to_engine() + +* crypto_transfer_kpp_request_to_engine() + +* crypto_transfer_skcipher_request_to_engine() + +At the end of the request process, a call to one of the following functions is needed: + +* crypto_finalize_aead_request() + +* crypto_finalize_akcipher_request() + +* crypto_finalize_hash_request() + +* crypto_finalize_kpp_request() + +* crypto_finalize_skcipher_request() diff --git a/Documentation/crypto/descore-readme.rst b/Documentation/crypto/descore-readme.rst new file mode 100644 index 000000000..45bd9c8ba --- /dev/null +++ b/Documentation/crypto/descore-readme.rst @@ -0,0 +1,414 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: <isonum.txt> + +=========================================== +Fast & Portable DES encryption & decryption +=========================================== + +.. note:: + + Below is the original README file from the descore.shar package, + converted to ReST format. + +------------------------------------------------------------------------------ + +des - fast & portable DES encryption & decryption. + +Copyright |copy| 1992 Dana L. How + +This program is free software; you can redistribute it and/or modify +it under the terms of the GNU Library General Public License as published by +the Free Software Foundation; either version 2 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Library General Public License for more details. + +You should have received a copy of the GNU Library General Public License +along with this program; if not, write to the Free Software +Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. + +Author's address: how@isl.stanford.edu + +.. README,v 1.15 1992/05/20 00:25:32 how E + +==>> To compile after untarring/unsharring, just ``make`` <<== + +This package was designed with the following goals: + +1. Highest possible encryption/decryption PERFORMANCE. +2. PORTABILITY to any byte-addressable host with a 32bit unsigned C type +3. Plug-compatible replacement for KERBEROS's low-level routines. + +This second release includes a number of performance enhancements for +register-starved machines. My discussions with Richard Outerbridge, +71755.204@compuserve.com, sparked a number of these enhancements. + +To more rapidly understand the code in this package, inspect desSmallFips.i +(created by typing ``make``) BEFORE you tackle desCode.h. The latter is set +up in a parameterized fashion so it can easily be modified by speed-daemon +hackers in pursuit of that last microsecond. You will find it more +illuminating to inspect one specific implementation, +and then move on to the common abstract skeleton with this one in mind. + + +performance comparison to other available des code which i could +compile on a SPARCStation 1 (cc -O4, gcc -O2): + +this code (byte-order independent): + + - 30us per encryption (options: 64k tables, no IP/FP) + - 33us per encryption (options: 64k tables, FIPS standard bit ordering) + - 45us per encryption (options: 2k tables, no IP/FP) + - 48us per encryption (options: 2k tables, FIPS standard bit ordering) + - 275us to set a new key (uses 1k of key tables) + + this has the quickest encryption/decryption routines i've seen. + since i was interested in fast des filters rather than crypt(3) + and password cracking, i haven't really bothered yet to speed up + the key setting routine. also, i have no interest in re-implementing + all the other junk in the mit kerberos des library, so i've just + provided my routines with little stub interfaces so they can be + used as drop-in replacements with mit's code or any of the mit- + compatible packages below. (note that the first two timings above + are highly variable because of cache effects). + +kerberos des replacement from australia (version 1.95): + + - 53us per encryption (uses 2k of tables) + - 96us to set a new key (uses 2.25k of key tables) + + so despite the author's inclusion of some of the performance + improvements i had suggested to him, this package's + encryption/decryption is still slower on the sparc and 68000. + more specifically, 19-40% slower on the 68020 and 11-35% slower + on the sparc, depending on the compiler; + in full gory detail (ALT_ECB is a libdes variant): + + =============== ============== =============== ================= + compiler machine desCore libdes ALT_ECB slower by + =============== ============== =============== ================= + gcc 2.1 -O2 Sun 3/110 304 uS 369.5uS 461.8uS 22% + cc -O1 Sun 3/110 336 uS 436.6uS 399.3uS 19% + cc -O2 Sun 3/110 360 uS 532.4uS 505.1uS 40% + cc -O4 Sun 3/110 365 uS 532.3uS 505.3uS 38% + gcc 2.1 -O2 Sun 4/50 48 uS 53.4uS 57.5uS 11% + cc -O2 Sun 4/50 48 uS 64.6uS 64.7uS 35% + cc -O4 Sun 4/50 48 uS 64.7uS 64.9uS 35% + =============== ============== =============== ================= + + (my time measurements are not as accurate as his). + + the comments in my first release of desCore on version 1.92: + + - 68us per encryption (uses 2k of tables) + - 96us to set a new key (uses 2.25k of key tables) + + this is a very nice package which implements the most important + of the optimizations which i did in my encryption routines. + it's a bit weak on common low-level optimizations which is why + it's 39%-106% slower. because he was interested in fast crypt(3) and + password-cracking applications, he also used the same ideas to + speed up the key-setting routines with impressive results. + (at some point i may do the same in my package). he also implements + the rest of the mit des library. + + (code from eay@psych.psy.uq.oz.au via comp.sources.misc) + +fast crypt(3) package from denmark: + + the des routine here is buried inside a loop to do the + crypt function and i didn't feel like ripping it out and measuring + performance. his code takes 26 sparc instructions to compute one + des iteration; above, Quick (64k) takes 21 and Small (2k) takes 37. + he claims to use 280k of tables but the iteration calculation seems + to use only 128k. his tables and code are machine independent. + + (code from glad@daimi.aau.dk via alt.sources or comp.sources.misc) + +swedish reimplementation of Kerberos des library + + - 108us per encryption (uses 34k worth of tables) + - 134us to set a new key (uses 32k of key tables to get this speed!) + + the tables used seem to be machine-independent; + he seems to have included a lot of special case code + so that, e.g., ``long`` loads can be used instead of 4 ``char`` loads + when the machine's architecture allows it. + + (code obtained from chalmers.se:pub/des) + +crack 3.3c package from england: + + as in crypt above, the des routine is buried in a loop. it's + also very modified for crypt. his iteration code uses 16k + of tables and appears to be slow. + + (code obtained from aem@aber.ac.uk via alt.sources or comp.sources.misc) + +``highly optimized`` and tweaked Kerberos/Athena code (byte-order dependent): + + - 165us per encryption (uses 6k worth of tables) + - 478us to set a new key (uses <1k of key tables) + + so despite the comments in this code, it was possible to get + faster code AND smaller tables, as well as making the tables + machine-independent. + (code obtained from prep.ai.mit.edu) + +UC Berkeley code (depends on machine-endedness): + - 226us per encryption + - 10848us to set a new key + + table sizes are unclear, but they don't look very small + (code obtained from wuarchive.wustl.edu) + + +motivation and history +====================== + +a while ago i wanted some des routines and the routines documented on sun's +man pages either didn't exist or dumped core. i had heard of kerberos, +and knew that it used des, so i figured i'd use its routines. but once +i got it and looked at the code, it really set off a lot of pet peeves - +it was too convoluted, the code had been written without taking +advantage of the regular structure of operations such as IP, E, and FP +(i.e. the author didn't sit down and think before coding), +it was excessively slow, the author had attempted to clarify the code +by adding MORE statements to make the data movement more ``consistent`` +instead of simplifying his implementation and cutting down on all data +movement (in particular, his use of L1, R1, L2, R2), and it was full of +idiotic ``tweaks`` for particular machines which failed to deliver significant +speedups but which did obfuscate everything. so i took the test data +from his verification program and rewrote everything else. + +a while later i ran across the great crypt(3) package mentioned above. +the fact that this guy was computing 2 sboxes per table lookup rather +than one (and using a MUCH larger table in the process) emboldened me to +do the same - it was a trivial change from which i had been scared away +by the larger table size. in his case he didn't realize you don't need to keep +the working data in TWO forms, one for easy use of half the sboxes in +indexing, the other for easy use of the other half; instead you can keep +it in the form for the first half and use a simple rotate to get the other +half. this means i have (almost) half the data manipulation and half +the table size. in fairness though he might be encoding something particular +to crypt(3) in his tables - i didn't check. + +i'm glad that i implemented it the way i did, because this C version is +portable (the ifdef's are performance enhancements) and it is faster +than versions hand-written in assembly for the sparc! + + +porting notes +============= + +one thing i did not want to do was write an enormous mess +which depended on endedness and other machine quirks, +and which necessarily produced different code and different lookup tables +for different machines. see the kerberos code for an example +of what i didn't want to do; all their endedness-specific ``optimizations`` +obfuscate the code and in the end were slower than a simpler machine +independent approach. however, there are always some portability +considerations of some kind, and i have included some options +for varying numbers of register variables. +perhaps some will still regard the result as a mess! + +1) i assume everything is byte addressable, although i don't actually + depend on the byte order, and that bytes are 8 bits. + i assume word pointers can be freely cast to and from char pointers. + note that 99% of C programs make these assumptions. + i always use unsigned char's if the high bit could be set. +2) the typedef ``word`` means a 32 bit unsigned integral type. + if ``unsigned long`` is not 32 bits, change the typedef in desCore.h. + i assume sizeof(word) == 4 EVERYWHERE. + +the (worst-case) cost of my NOT doing endedness-specific optimizations +in the data loading and storing code surrounding the key iterations +is less than 12%. also, there is the added benefit that +the input and output work areas do not need to be word-aligned. + + +OPTIONAL performance optimizations +================================== + +1) you should define one of ``i386,`` ``vax,`` ``mc68000,`` or ``sparc,`` + whichever one is closest to the capabilities of your machine. + see the start of desCode.h to see exactly what this selection implies. + note that if you select the wrong one, the des code will still work; + these are just performance tweaks. +2) for those with functional ``asm`` keywords: you should change the + ROR and ROL macros to use machine rotate instructions if you have them. + this will save 2 instructions and a temporary per use, + or about 32 to 40 instructions per en/decryption. + + note that gcc is smart enough to translate the ROL/R macros into + machine rotates! + +these optimizations are all rather persnickety, yet with them you should +be able to get performance equal to assembly-coding, except that: + +1) with the lack of a bit rotate operator in C, rotates have to be synthesized + from shifts. so access to ``asm`` will speed things up if your machine + has rotates, as explained above in (3) (not necessary if you use gcc). +2) if your machine has less than 12 32-bit registers i doubt your compiler will + generate good code. + + ``i386`` tries to configure the code for a 386 by only declaring 3 registers + (it appears that gcc can use ebx, esi and edi to hold register variables). + however, if you like assembly coding, the 386 does have 7 32-bit registers, + and if you use ALL of them, use ``scaled by 8`` address modes with displacement + and other tricks, you can get reasonable routines for DesQuickCore... with + about 250 instructions apiece. For DesSmall... it will help to rearrange + des_keymap, i.e., now the sbox # is the high part of the index and + the 6 bits of data is the low part; it helps to exchange these. + + since i have no way to conveniently test it i have not provided my + shoehorned 386 version. note that with this release of desCore, gcc is able + to put everything in registers(!), and generate about 370 instructions apiece + for the DesQuickCore... routines! + +coding notes +============ + +the en/decryption routines each use 6 necessary register variables, +with 4 being actively used at once during the inner iterations. +if you don't have 4 register variables get a new machine. +up to 8 more registers are used to hold constants in some configurations. + +i assume that the use of a constant is more expensive than using a register: + +a) additionally, i have tried to put the larger constants in registers. + registering priority was by the following: + + - anything more than 12 bits (bad for RISC and CISC) + - greater than 127 in value (can't use movq or byte immediate on CISC) + - 9-127 (may not be able to use CISC shift immediate or add/sub quick), + - 1-8 were never registered, being the cheapest constants. + +b) the compiler may be too stupid to realize table and table+256 should + be assigned to different constant registers and instead repetitively + do the arithmetic, so i assign these to explicit ``m`` register variables + when possible and helpful. + +i assume that indexing is cheaper or equivalent to auto increment/decrement, +where the index is 7 bits unsigned or smaller. +this assumption is reversed for 68k and vax. + +i assume that addresses can be cheaply formed from two registers, +or from a register and a small constant. +for the 68000, the ``two registers and small offset`` form is used sparingly. +all index scaling is done explicitly - no hidden shifts by log2(sizeof). + +the code is written so that even a dumb compiler +should never need more than one hidden temporary, +increasing the chance that everything will fit in the registers. +KEEP THIS MORE SUBTLE POINT IN MIND IF YOU REWRITE ANYTHING. + +(actually, there are some code fragments now which do require two temps, +but fixing it would either break the structure of the macros or +require declaring another temporary). + + +special efficient data format +============================== + +bits are manipulated in this arrangement most of the time (S7 S5 S3 S1):: + + 003130292827xxxx242322212019xxxx161514131211xxxx080706050403xxxx + +(the x bits are still there, i'm just emphasizing where the S boxes are). +bits are rotated left 4 when computing S6 S4 S2 S0:: + + 282726252423xxxx201918171615xxxx121110090807xxxx040302010031xxxx + +the rightmost two bits are usually cleared so the lower byte can be used +as an index into an sbox mapping table. the next two x'd bits are set +to various values to access different parts of the tables. + + +how to use the routines + +datatypes: + pointer to 8 byte area of type DesData + used to hold keys and input/output blocks to des. + + pointer to 128 byte area of type DesKeys + used to hold full 768-bit key. + must be long-aligned. + +DesQuickInit() + call this before using any other routine with ``Quick`` in its name. + it generates the special 64k table these routines need. +DesQuickDone() + frees this table + +DesMethod(m, k) + m points to a 128byte block, k points to an 8 byte des key + which must have odd parity (or -1 is returned) and which must + not be a (semi-)weak key (or -2 is returned). + normally DesMethod() returns 0. + + m is filled in from k so that when one of the routines below + is called with m, the routine will act like standard des + en/decryption with the key k. if you use DesMethod, + you supply a standard 56bit key; however, if you fill in + m yourself, you will get a 768bit key - but then it won't + be standard. it's 768bits not 1024 because the least significant + two bits of each byte are not used. note that these two bits + will be set to magic constants which speed up the encryption/decryption + on some machines. and yes, each byte controls + a specific sbox during a specific iteration. + + you really shouldn't use the 768bit format directly; i should + provide a routine that converts 128 6-bit bytes (specified in + S-box mapping order or something) into the right format for you. + this would entail some byte concatenation and rotation. + +Des{Small|Quick}{Fips|Core}{Encrypt|Decrypt}(d, m, s) + performs des on the 8 bytes at s into the 8 bytes at + ``d. (d,s: char *)``. + + uses m as a 768bit key as explained above. + + the Encrypt|Decrypt choice is obvious. + + Fips|Core determines whether a completely standard FIPS initial + and final permutation is done; if not, then the data is loaded + and stored in a nonstandard bit order (FIPS w/o IP/FP). + + Fips slows down Quick by 10%, Small by 9%. + + Small|Quick determines whether you use the normal routine + or the crazy quick one which gobbles up 64k more of memory. + Small is 50% slower then Quick, but Quick needs 32 times as much + memory. Quick is included for programs that do nothing but DES, + e.g., encryption filters, etc. + + +Getting it to compile on your machine +===================================== + +there are no machine-dependencies in the code (see porting), +except perhaps the ``now()`` macro in desTest.c. +ALL generated tables are machine independent. +you should edit the Makefile with the appropriate optimization flags +for your compiler (MAX optimization). + + +Speeding up kerberos (and/or its des library) +============================================= + +note that i have included a kerberos-compatible interface in desUtil.c +through the functions des_key_sched() and des_ecb_encrypt(). +to use these with kerberos or kerberos-compatible code put desCore.a +ahead of the kerberos-compatible library on your linker's command line. +you should not need to #include desCore.h; just include the header +file provided with the kerberos library. + +Other uses +========== + +the macros in desCode.h would be very useful for putting inline des +functions in more complicated encryption routines. diff --git a/Documentation/crypto/devel-algos.rst b/Documentation/crypto/devel-algos.rst new file mode 100644 index 000000000..9b7782f4f --- /dev/null +++ b/Documentation/crypto/devel-algos.rst @@ -0,0 +1,238 @@ +Developing Cipher Algorithms +============================ + +Registering And Unregistering Transformation +-------------------------------------------- + +There are three distinct types of registration functions in the Crypto +API. One is used to register a generic cryptographic transformation, +while the other two are specific to HASH transformations and +COMPRESSion. We will discuss the latter two in a separate chapter, here +we will only look at the generic ones. + +Before discussing the register functions, the data structure to be +filled with each, struct crypto_alg, must be considered -- see below +for a description of this data structure. + +The generic registration functions can be found in +include/linux/crypto.h and their definition can be seen below. The +former function registers a single transformation, while the latter +works on an array of transformation descriptions. The latter is useful +when registering transformations in bulk, for example when a driver +implements multiple transformations. + +:: + + int crypto_register_alg(struct crypto_alg *alg); + int crypto_register_algs(struct crypto_alg *algs, int count); + + +The counterparts to those functions are listed below. + +:: + + void crypto_unregister_alg(struct crypto_alg *alg); + void crypto_unregister_algs(struct crypto_alg *algs, int count); + + +The registration functions return 0 on success, or a negative errno +value on failure. crypto_register_algs() succeeds only if it +successfully registered all the given algorithms; if it fails partway +through, then any changes are rolled back. + +The unregistration functions always succeed, so they don't have a +return value. Don't try to unregister algorithms that aren't +currently registered. + +Single-Block Symmetric Ciphers [CIPHER] +--------------------------------------- + +Example of transformations: aes, serpent, ... + +This section describes the simplest of all transformation +implementations, that being the CIPHER type used for symmetric ciphers. +The CIPHER type is used for transformations which operate on exactly one +block at a time and there are no dependencies between blocks at all. + +Registration specifics +~~~~~~~~~~~~~~~~~~~~~~ + +The registration of [CIPHER] algorithm is specific in that struct +crypto_alg field .cra_type is empty. The .cra_u.cipher has to be +filled in with proper callbacks to implement this transformation. + +See struct cipher_alg below. + +Cipher Definition With struct cipher_alg +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Struct cipher_alg defines a single block cipher. + +Here are schematics of how these functions are called when operated from +other part of the kernel. Note that the .cia_setkey() call might happen +before or after any of these schematics happen, but must not happen +during any of these are in-flight. + +:: + + KEY ---. PLAINTEXT ---. + v v + .cia_setkey() -> .cia_encrypt() + | + '-----> CIPHERTEXT + + +Please note that a pattern where .cia_setkey() is called multiple times +is also valid: + +:: + + + KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. + v v v v + .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() + | | + '---> CIPHERTEXT1 '---> CIPHERTEXT2 + + +Multi-Block Ciphers +------------------- + +Example of transformations: cbc(aes), chacha20, ... + +This section describes the multi-block cipher transformation +implementations. The multi-block ciphers are used for transformations +which operate on scatterlists of data supplied to the transformation +functions. They output the result into a scatterlist of data as well. + +Registration Specifics +~~~~~~~~~~~~~~~~~~~~~~ + +The registration of multi-block cipher algorithms is one of the most +standard procedures throughout the crypto API. + +Note, if a cipher implementation requires a proper alignment of data, +the caller should use the functions of crypto_skcipher_alignmask() to +identify a memory alignment mask. The kernel crypto API is able to +process requests that are unaligned. This implies, however, additional +overhead as the kernel crypto API needs to perform the realignment of +the data which may imply moving of data. + +Cipher Definition With struct skcipher_alg +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Struct skcipher_alg defines a multi-block cipher, or more generally, a +length-preserving symmetric cipher algorithm. + +Scatterlist handling +~~~~~~~~~~~~~~~~~~~~ + +Some drivers will want to use the Generic ScatterWalk in case the +hardware needs to be fed separate chunks of the scatterlist which +contains the plaintext and will contain the ciphertext. Please refer +to the ScatterWalk interface offered by the Linux kernel scatter / +gather list implementation. + +Hashing [HASH] +-------------- + +Example of transformations: crc32, md5, sha1, sha256,... + +Registering And Unregistering The Transformation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +There are multiple ways to register a HASH transformation, depending on +whether the transformation is synchronous [SHASH] or asynchronous +[AHASH] and the amount of HASH transformations we are registering. You +can find the prototypes defined in include/crypto/internal/hash.h: + +:: + + int crypto_register_ahash(struct ahash_alg *alg); + + int crypto_register_shash(struct shash_alg *alg); + int crypto_register_shashes(struct shash_alg *algs, int count); + + +The respective counterparts for unregistering the HASH transformation +are as follows: + +:: + + void crypto_unregister_ahash(struct ahash_alg *alg); + + void crypto_unregister_shash(struct shash_alg *alg); + void crypto_unregister_shashes(struct shash_alg *algs, int count); + + +Cipher Definition With struct shash_alg and ahash_alg +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Here are schematics of how these functions are called when operated from +other part of the kernel. Note that the .setkey() call might happen +before or after any of these schematics happen, but must not happen +during any of these are in-flight. Please note that calling .init() +followed immediately by .final() is also a perfectly valid +transformation. + +:: + + I) DATA -----------. + v + .init() -> .update() -> .final() ! .update() might not be called + ^ | | at all in this scenario. + '----' '---> HASH + + II) DATA -----------.-----------. + v v + .init() -> .update() -> .finup() ! .update() may not be called + ^ | | at all in this scenario. + '----' '---> HASH + + III) DATA -----------. + v + .digest() ! The entire process is handled + | by the .digest() call. + '---------------> HASH + + +Here is a schematic of how the .export()/.import() functions are called +when used from another part of the kernel. + +:: + + KEY--. DATA--. + v v ! .update() may not be called + .setkey() -> .init() -> .update() -> .export() at all in this scenario. + ^ | | + '-----' '--> PARTIAL_HASH + + ----------- other transformations happen here ----------- + + PARTIAL_HASH--. DATA1--. + v v + .import -> .update() -> .final() ! .update() may not be called + ^ | | at all in this scenario. + '----' '--> HASH1 + + PARTIAL_HASH--. DATA2-. + v v + .import -> .finup() + | + '---------------> HASH2 + +Note that it is perfectly legal to "abandon" a request object: +- call .init() and then (as many times) .update() +- _not_ call any of .final(), .finup() or .export() at any point in future + +In other words implementations should mind the resource allocation and clean-up. +No resources related to request objects should remain allocated after a call +to .init() or .update(), since there might be no chance to free them. + + +Specifics Of Asynchronous HASH Transformation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Some of the drivers will want to use the Generic ScatterWalk in case the +implementation needs to be fed separate chunks of the scatterlist which +contains the input data. diff --git a/Documentation/crypto/device_drivers/index.rst b/Documentation/crypto/device_drivers/index.rst new file mode 100644 index 000000000..c81d311ac --- /dev/null +++ b/Documentation/crypto/device_drivers/index.rst @@ -0,0 +1,9 @@ +.. SPDX-License-Identifier: GPL-2.0 + +Hardware Device Driver Specific Documentation +--------------------------------------------- + +.. toctree:: + :maxdepth: 1 + + octeontx2 diff --git a/Documentation/crypto/device_drivers/octeontx2.rst b/Documentation/crypto/device_drivers/octeontx2.rst new file mode 100644 index 000000000..7e469b173 --- /dev/null +++ b/Documentation/crypto/device_drivers/octeontx2.rst @@ -0,0 +1,25 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================= +octeontx2 devlink support +========================= + +This document describes the devlink features implemented by the ``octeontx2 CPT`` +device drivers. + +Parameters +========== + +The ``octeontx2`` driver implements the following driver-specific parameters. + +.. list-table:: Driver-specific parameters implemented + :widths: 5 5 5 85 + + * - Name + - Type + - Mode + - Description + * - ``t106_mode`` + - u8 + - runtime + - Used to configure CN10KA B0/CN10KB CPT to work as CN10KA A0/A1. diff --git a/Documentation/crypto/index.rst b/Documentation/crypto/index.rst new file mode 100644 index 000000000..705f186d6 --- /dev/null +++ b/Documentation/crypto/index.rst @@ -0,0 +1,30 @@ +========== +Crypto API +========== + +:Author: Stephan Mueller +:Author: Marek Vasut + +This documentation outlines the Linux kernel crypto API with its +concepts, details about developing cipher implementations, employment of the API +for cryptographic use cases, as well as programming examples. + +.. toctree:: + :caption: Table of contents + :maxdepth: 2 + + libcrypto + intro + api-intro + architecture + + async-tx-api + asymmetric-keys + devel-algos + userspace-if + crypto_engine + api + api-samples + descore-readme + device_drivers/index + krb5 diff --git a/Documentation/crypto/intro.rst b/Documentation/crypto/intro.rst new file mode 100644 index 000000000..9aa89ebbf --- /dev/null +++ b/Documentation/crypto/intro.rst @@ -0,0 +1,74 @@ +Kernel Crypto API Interface Specification +========================================= + +Introduction +------------ + +The kernel crypto API offers a rich set of cryptographic ciphers as well +as other data transformation mechanisms and methods to invoke these. +This document contains a description of the API and provides example +code. + +To understand and properly use the kernel crypto API a brief explanation +of its structure is given. Based on the architecture, the API can be +separated into different components. Following the architecture +specification, hints to developers of ciphers are provided. Pointers to +the API function call documentation are given at the end. + +The kernel crypto API refers to all algorithms as "transformations". +Therefore, a cipher handle variable usually has the name "tfm". Besides +cryptographic operations, the kernel crypto API also knows compression +transformations and handles them the same way as ciphers. + +The kernel crypto API serves the following entity types: + +- consumers requesting cryptographic services + +- data transformation implementations (typically ciphers) that can be + called by consumers using the kernel crypto API + +This specification is intended for consumers of the kernel crypto API as +well as for developers implementing ciphers. This API specification, +however, does not discuss all API calls available to data transformation +implementations (i.e. implementations of ciphers and other +transformations (such as CRC or even compression algorithms) that can +register with the kernel crypto API). + +Note: The terms "transformation" and cipher algorithm are used +interchangeably. + +Terminology +----------- + +The transformation implementation is an actual code or interface to +hardware which implements a certain transformation with precisely +defined behavior. + +The transformation object (TFM) is an instance of a transformation +implementation. There can be multiple transformation objects associated +with a single transformation implementation. Each of those +transformation objects is held by a crypto API consumer or another +transformation. Transformation object is allocated when a crypto API +consumer requests a transformation implementation. The consumer is then +provided with a structure, which contains a transformation object (TFM). + +The structure that contains transformation objects may also be referred +to as a "cipher handle". Such a cipher handle is always subject to the +following phases that are reflected in the API calls applicable to such +a cipher handle: + +1. Initialization of a cipher handle. + +2. Execution of all intended cipher operations applicable for the handle + where the cipher handle must be furnished to every API call. + +3. Destruction of a cipher handle. + +When using the initialization API calls, a cipher handle is created and +returned to the consumer. Therefore, please refer to all initialization +API calls that refer to the data structure type a consumer is expected +to receive and subsequently to use. The initialization API calls have +all the same naming conventions of crypto_alloc\*. + +The transformation context is private data associated with the +transformation object. diff --git a/Documentation/crypto/krb5.rst b/Documentation/crypto/krb5.rst new file mode 100644 index 000000000..f62e07ac6 --- /dev/null +++ b/Documentation/crypto/krb5.rst @@ -0,0 +1,271 @@ +.. SPDX-License-Identifier: GPL-2.0 + +=========================== +Kerberos V Cryptography API +=========================== + +.. Contents: + + - Overview. + - Small Buffer. + - Encoding Type. + - Key Derivation. + - PRF+ Calculation. + - Kc, Ke And Ki Derivation. + - Crypto Functions. + - Preparation Functions. + - Encryption Mode. + - Checksum Mode. + - The krb5enc AEAD algorithm + +Overview +======== + +This API provides Kerberos 5-style cryptography for key derivation, encryption +and checksumming for use in network filesystems and can be used to implement +the low-level crypto that's needed for GSSAPI. + +The following crypto types are supported:: + + KRB5_ENCTYPE_AES128_CTS_HMAC_SHA1_96 + KRB5_ENCTYPE_AES256_CTS_HMAC_SHA1_96 + KRB5_ENCTYPE_AES128_CTS_HMAC_SHA256_128 + KRB5_ENCTYPE_AES256_CTS_HMAC_SHA384_192 + KRB5_ENCTYPE_CAMELLIA128_CTS_CMAC + KRB5_ENCTYPE_CAMELLIA256_CTS_CMAC + + KRB5_CKSUMTYPE_HMAC_SHA1_96_AES128 + KRB5_CKSUMTYPE_HMAC_SHA1_96_AES256 + KRB5_CKSUMTYPE_CMAC_CAMELLIA128 + KRB5_CKSUMTYPE_CMAC_CAMELLIA256 + KRB5_CKSUMTYPE_HMAC_SHA256_128_AES128 + KRB5_CKSUMTYPE_HMAC_SHA384_192_AES256 + +The API can be included by:: + + #include <crypto/krb5.h> + +Small Buffer +------------ + +To pass small pieces of data about, such as keys, a buffer structure is +defined, giving a pointer to the data and the size of that data:: + + struct krb5_buffer { + unsigned int len; + void *data; + }; + +Encoding Type +============= + +The encoding type is defined by the following structure:: + + struct krb5_enctype { + int etype; + int ctype; + const char *name; + u16 key_bytes; + u16 key_len; + u16 Kc_len; + u16 Ke_len; + u16 Ki_len; + u16 prf_len; + u16 block_len; + u16 conf_len; + u16 cksum_len; + ... + }; + +The fields of interest to the user of the API are as follows: + + * ``etype`` and ``ctype`` indicate the protocol number for this encoding + type for encryption and checksumming respectively. They hold + ``KRB5_ENCTYPE_*`` and ``KRB5_CKSUMTYPE_*`` constants. + + * ``name`` is the formal name of the encoding. + + * ``key_len`` and ``key_bytes`` are the input key length and the derived key + length. (I think they only differ for DES, which isn't supported here). + + * ``Kc_len``, ``Ke_len`` and ``Ki_len`` are the sizes of the derived Kc, Ke + and Ki keys. Kc is used for in checksum mode; Ke and Ki are used in + encryption mode. + + * ``prf_len`` is the size of the result from the PRF+ function calculation. + + * ``block_len``, ``conf_len`` and ``cksum_len`` are the encryption block + length, confounder length and checksum length respectively. All three are + used in encryption mode, but only the checksum length is used in checksum + mode. + +The encoding type is looked up by number using the following function:: + + const struct krb5_enctype *crypto_krb5_find_enctype(u32 enctype); + +Key Derivation +============== + +Once the application has selected an encryption type, the keys that will be +used to do the actual crypto can be derived from the transport key. + +PRF+ Calculation +---------------- + +To aid in key derivation, a function to calculate the Kerberos GSSAPI +mechanism's PRF+ is provided:: + + int crypto_krb5_calc_PRFplus(const struct krb5_enctype *krb5, + const struct krb5_buffer *K, + unsigned int L, + const struct krb5_buffer *S, + struct krb5_buffer *result, + gfp_t gfp); + +This can be used to derive the transport key from a source key plus additional +data to limit its use. + +Crypto Functions +================ + +Once the keys have been derived, crypto can be performed on the data. The +caller must leave gaps in the buffer for the storage of the confounder (if +needed) and the checksum when preparing a message for transmission. An enum +and a pair of functions are provided to aid in this:: + + enum krb5_crypto_mode { + KRB5_CHECKSUM_MODE, + KRB5_ENCRYPT_MODE, + }; + + size_t crypto_krb5_how_much_buffer(const struct krb5_enctype *krb5, + enum krb5_crypto_mode mode, + size_t data_size, size_t *_offset); + + size_t crypto_krb5_how_much_data(const struct krb5_enctype *krb5, + enum krb5_crypto_mode mode, + size_t *_buffer_size, size_t *_offset); + +All these functions take the encoding type and an indication the mode of crypto +(checksum-only or full encryption). + +The first function returns how big the buffer will need to be to house a given +amount of data; the second function returns how much data will fit in a buffer +of a particular size, and adjusts down the size of the required buffer +accordingly. In both cases, the offset of the data within the buffer is also +returned. + +When a message has been received, the location and size of the data with the +message can be determined by calling:: + + int crypto_krb5_where_is_the_data(const struct krb5_enctype *krb5, + enum krb5_crypto_mode mode, + size_t *_offset, size_t *_len); + +The caller provides the offset and length of the message to the function, which +then alters those values to indicate the region containing the data (plus any +padding). It is up to the caller to determine how much padding there is. The +function returns an error if the length is too small or if the mode is +unsupported. An additional function:: + + int crypto_krb5_check_data_len(const struct krb5_enctype *krb5, + enum krb5_crypto_mode mode, + size_t len, size_t min_content); + +is provided to just do a basic check that the decrypted/verified message would +have a sufficient minimum payload. + +Preparation Functions +--------------------- + +Two functions are provided to allocated and prepare a crypto object for use by +the action functions:: + + struct crypto_aead * + crypto_krb5_prepare_encryption(const struct krb5_enctype *krb5, + const struct krb5_buffer *TK, + u32 usage, gfp_t gfp); + struct crypto_shash * + crypto_krb5_prepare_checksum(const struct krb5_enctype *krb5, + const struct krb5_buffer *TK, + u32 usage, gfp_t gfp); + +Both of these functions take the encoding type, the transport key and the usage +value used to derive the appropriate subkey(s). They create an appropriate +crypto object, an AEAD template for encryption and a synchronous hash for +checksumming, set the key(s) on it and configure it. The caller is expected to +pass these handles to the action functions below. + +Encryption Mode +--------------- + +A pair of functions are provided to encrypt and decrypt a message:: + + ssize_t crypto_krb5_encrypt(const struct krb5_enctype *krb5, + struct crypto_aead *aead, + struct scatterlist *sg, unsigned int nr_sg, + size_t sg_len, + size_t data_offset, size_t data_len, + bool preconfounded); + int crypto_krb5_decrypt(const struct krb5_enctype *krb5, + struct crypto_aead *aead, + struct scatterlist *sg, unsigned int nr_sg, + size_t *_offset, size_t *_len); + +In both cases, the input and output buffers are indicated by the same +scatterlist. + +For the encryption function, the output buffer may be larger than is needed +(the amount of output generated is returned) and the location and size of the +data are indicated (which must match the encoding). If no confounder is set, +the function will insert one. + +For the decryption function, the offset and length of the message in buffer are +supplied and these are shrunk to fit the data. The decryption function will +verify any checksums within the message and give an error if they don't match. + +Checksum Mode +------------- + +A pair of function are provided to generate the checksum on a message and to +verify that checksum:: + + ssize_t crypto_krb5_get_mic(const struct krb5_enctype *krb5, + struct crypto_shash *shash, + const struct krb5_buffer *metadata, + struct scatterlist *sg, unsigned int nr_sg, + size_t sg_len, + size_t data_offset, size_t data_len); + int crypto_krb5_verify_mic(const struct krb5_enctype *krb5, + struct crypto_shash *shash, + const struct krb5_buffer *metadata, + struct scatterlist *sg, unsigned int nr_sg, + size_t *_offset, size_t *_len); + +In both cases, the input and output buffers are indicated by the same +scatterlist. Additional metadata can be passed in which will get added to the +hash before the data. + +For the get_mic function, the output buffer may be larger than is needed (the +amount of output generated is returned) and the location and size of the data +are indicated (which must match the encoding). + +For the verification function, the offset and length of the message in buffer +are supplied and these are shrunk to fit the data. An error will be returned +if the checksums don't match. + +The krb5enc AEAD algorithm +========================== + +A template AEAD crypto algorithm, called "krb5enc", is provided that hashes the +plaintext before encrypting it (the reverse of authenc). The handle returned +by ``crypto_krb5_prepare_encryption()`` may be one of these, but there's no +requirement for the user of this API to interact with it directly. + +For reference, its key format begins with a BE32 of the format number. Only +format 1 is provided and that continues with a BE32 of the Ke key length +followed by a BE32 of the Ki key length, followed by the bytes from the Ke key +and then the Ki key. + +Using specifically ordered words means that the static test data doesn't +require byteswapping. diff --git a/Documentation/crypto/libcrypto-auth-encryption.rst b/Documentation/crypto/libcrypto-auth-encryption.rst new file mode 100644 index 000000000..1e527685a --- /dev/null +++ b/Documentation/crypto/libcrypto-auth-encryption.rst @@ -0,0 +1,20 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Authenticated encryption +======================== + +These APIs provide support for authenticated encryption and decryption. + +AES-CCM +------- + +This API provides support for AES in the CCM mode of operation. + +.. kernel-doc:: include/crypto/aes-ccm.h + +AES-GCM +------- + +This API provides support for AES in the GCM mode of operation. + +.. kernel-doc:: include/crypto/aes-gcm.h diff --git a/Documentation/crypto/libcrypto-blockcipher.rst b/Documentation/crypto/libcrypto-blockcipher.rst new file mode 100644 index 000000000..fd85e27fa --- /dev/null +++ b/Documentation/crypto/libcrypto-blockcipher.rst @@ -0,0 +1,19 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Block ciphers +============= + +AES +--- + +This API provides support for the AES block cipher. + +.. kernel-doc:: include/crypto/aes.h + +DES +--- + +This API provides support for the DES block cipher. This algorithm is obsolete +and is supported only for backwards compatibility. + +.. kernel-doc:: include/crypto/des.h diff --git a/Documentation/crypto/libcrypto-hash.rst b/Documentation/crypto/libcrypto-hash.rst new file mode 100644 index 000000000..fa4c54236 --- /dev/null +++ b/Documentation/crypto/libcrypto-hash.rst @@ -0,0 +1,88 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Hash functions, MACs, and XOFs +============================== + +AES-CMAC and AES-XCBC-MAC +------------------------- + +This API provides support for the AES-CMAC and AES-XCBC-MAC message +authentication codes. + +.. kernel-doc:: include/crypto/aes-cbc-macs.h + +BLAKE2b +------- + +This API provides support for the BLAKE2b cryptographic hash function. + +.. kernel-doc:: include/crypto/blake2b.h + +BLAKE2s +------- + +This API provides support for the BLAKE2s cryptographic hash function. + +.. kernel-doc:: include/crypto/blake2s.h + +GHASH and POLYVAL +----------------- + +This API provides support for the GHASH and POLYVAL universal hash functions. +These algorithms are used only as internal components of other algorithms. + +.. kernel-doc:: include/crypto/gf128hash.h + +MD5 +--- + +This API provides support for the MD5 cryptographic hash function and HMAC-MD5. +This algorithm is obsolete and is supported only for backwards compatibility. + +.. kernel-doc:: include/crypto/md5.h + +NH +-- + +This API provides support for the NH universal hash function. This algorithm is +used only as an internal component of other algorithms. + +.. kernel-doc:: include/crypto/nh.h + +Poly1305 +-------- + +This API provides support for the Poly1305 universal hash function. This +algorithm is used only as an internal component of other algorithms. + +.. kernel-doc:: include/crypto/poly1305.h + +SHA-1 +----- + +This API provides support for the SHA-1 cryptographic hash function and +HMAC-SHA1. This algorithm is obsolete and is supported only for backwards +compatibility. + +.. kernel-doc:: include/crypto/sha1.h + +SHA-2 +----- + +This API provides support for the SHA-2 family of cryptographic hash functions, +including SHA-224, SHA-256, SHA-384, and SHA-512. This also includes their +corresponding HMACs: HMAC-SHA224, HMAC-SHA256, HMAC-SHA384, and HMAC-SHA512. + +.. kernel-doc:: include/crypto/sha2.h + +SHA-3 +----- + +The SHA-3 API is documented in :ref:`sha3`. + +SM3 +--- + +This API provides support for the SM3 cryptographic hash function. + +.. kernel-doc:: include/crypto/sm3.h diff --git a/Documentation/crypto/libcrypto-signature.rst b/Documentation/crypto/libcrypto-signature.rst new file mode 100644 index 000000000..2a6dc793f --- /dev/null +++ b/Documentation/crypto/libcrypto-signature.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Digital signature algorithms +============================ + +ML-DSA +------ + +This API provides support for the ML-DSA digital signature algorithm. + +.. kernel-doc:: include/crypto/mldsa.h diff --git a/Documentation/crypto/libcrypto-unauth-encryption.rst b/Documentation/crypto/libcrypto-unauth-encryption.rst new file mode 100644 index 000000000..b4639b892 --- /dev/null +++ b/Documentation/crypto/libcrypto-unauth-encryption.rst @@ -0,0 +1,49 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Unauthenticated encryption +========================== + +These APIs provide support for unauthenticated encryption and decryption, +including bare stream ciphers and other length-preserving algorithms such as +block ciphers in XTS mode. The legitimate use cases for these algorithms are: + +- Support for legacy protocols that really should have chosen an authenticated + mode (or even another primitive entirely) but didn't. + +- Internal components of authenticated modes. For example, AES-CTR is used by + AES-GCM and AES-CCM internally. + +- Storage encryption that cannot accommodate ciphertext expansion. Usually + AES-XTS is used for this. + +- Stream ciphers for key derivation and random number generation. + +Besides the above, these shouldn't be used. + +AES-CBC and AES-CBC-CTS +----------------------- + +This API provides support for AES in the CBC and CBC-CTS modes of operation. + +.. kernel-doc:: include/crypto/aes-cbc.h + +AES-CTR and AES-XCTR +-------------------- + +This API provides support for AES in the CTR and XCTR modes of operation. + +.. kernel-doc:: include/crypto/aes-ctr.h + +AES-ECB +------- + +This API provides support for AES in the ECB mode of operation. + +.. kernel-doc:: include/crypto/aes-ecb.h + +AES-XTS +------- + +This API provides support for AES in the XTS mode of operation. + +.. kernel-doc:: include/crypto/aes-xts.h diff --git a/Documentation/crypto/libcrypto-utils.rst b/Documentation/crypto/libcrypto-utils.rst new file mode 100644 index 000000000..9d833f47e --- /dev/null +++ b/Documentation/crypto/libcrypto-utils.rst @@ -0,0 +1,6 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +Utility functions +================= + +.. kernel-doc:: include/crypto/utils.h diff --git a/Documentation/crypto/libcrypto.rst b/Documentation/crypto/libcrypto.rst new file mode 100644 index 000000000..e911e0521 --- /dev/null +++ b/Documentation/crypto/libcrypto.rst @@ -0,0 +1,168 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +============== +Crypto library +============== + +The Linux kernel's crypto library (``lib/crypto/``) provides kernel-internal +users of cryptographic algorithms with faster and easier access to those +algorithms than the traditional kernel crypto API. + +Each cryptographic algorithm is supported via a set of dedicated functions. +"Crypto agility", where needed, is left to calling code. + +The crypto library functions are intended to be boring and straightforward, and +to follow familiar conventions. Their primary documentation is their (fairly +extensive) kernel-doc. This page just provides some extra high-level context. + +Note that the crypto library isn't entirely new. ``lib/`` has contained some +crypto functions since 2005. Rather, it's just an approach that's been expanded +over time as it's been found to work well. It also largely just matches how the +kernel already does things elsewhere. + +Scope and intended audience +=========================== + +The crypto library documentation is primarily meant for kernel developers who +need to use a particular cryptographic algorithm(s) in kernel code. For +example, "I just need to compute a SHA-256 hash." A secondary audience is +developers working on the crypto algorithm implementations themselves. + +If you're looking for more general information about cryptography, like the +differences between the different crypto algorithms or how to select an +appropriate algorithm, you should refer to external sources which cover that +type of information much more comprehensively. If you need help selecting +algorithms for a new kernel feature that doesn't already have its algorithms +predefined, please reach out to ``linux-crypto@vger.kernel.org`` for advice. + +Code organization +================= + +- ``lib/crypto/*.c``: the crypto algorithm implementations + +- ``lib/crypto/$(SRCARCH)/``: architecture-specific code for crypto algorithms. + It is here rather than somewhere in ``arch/`` partly because this allows + generic and architecture-optimized code to be easily built into a single + loadable module (when the algorithm is set to 'm' in the kconfig). + +- ``lib/crypto/tests/``: KUnit tests for the crypto algorithms + +- ``include/crypto/``: crypto headers, for both the crypto library and the + traditional crypto API + +Generally, there is one kernel module per algorithm. Sometimes related +algorithms are grouped into one module. There is intentionally no common +framework, though there are some utility functions that multiple algorithms use. + +Each algorithm module is controlled by a tristate kconfig symbol +``CRYPTO_LIB_$(ALGORITHM)``. As is the norm for library functions in the +kernel, these are hidden symbols which don't show up in the kconfig menu. +Instead, they are just selected by all the kconfig symbols that need them. + +Many of the algorithms have multiple implementations: a generic implementation +and architecture-optimized implementation(s). Each module initialization +function, or initcall in the built-in case, automatically enables the best +implementation based on the available CPU features. + +Note that the crypto library doesn't use the ``crypto/``, +``arch/$(SRCARCH)/crypto/``, or ``drivers/crypto/`` directories. These +directories are used by the traditional crypto API. When possible, algorithms +in the traditional crypto API are implemented by calls into the library. + +Advantages +========== + +Some of the advantages of the library over the traditional crypto API are: + +- The library functions tend to be much easier to use. For example, a hash + value can be computed using only a single function call. Most of the library + functions always succeed and return void, eliminating the need to write + error-handling code. Most also accept standard virtual addresses, rather than + scatterlists which are difficult and less efficient to work with. + +- The library functions are usually faster, especially for short inputs. They + call the crypto algorithms directly without inefficient indirect calls, memory + allocations, string parsing, lookups in an algorithm registry, and other + unnecessary API overhead. Architecture-optimized code is enabled by default. + +- The library functions use standard link-time dependencies instead of + error-prone dynamic loading by name. There's no need for workarounds such as + forcing algorithms to be built-in or adding module soft dependencies. + +- The library focuses on the approach that works the best on the vast majority + of systems: CPU-based implementations of the crypto algorithms, utilizing + on-CPU acceleration (such as AES instructions) when available. + +- The library uses standard KUnit tests, rather than custom ad-hoc tests. + +- The library tends to have higher assurance implementations of the crypto + algorithms. This is both due to its simpler design and because more of its + code is being regularly tested. + +- The library supports features that don't fit into the rigid framework of the + traditional crypto API, for example interleaved hashing and XOFs. + +When to use it +============== + +In-kernel users should use the library (rather than the traditional crypto API) +whenever possible. Many subsystems have already been converted. It usually +simplifies their code significantly and improves performance. + +Some kernel features allow userspace to provide an arbitrary string that selects +an arbitrary algorithm from the traditional crypto API by name. These features +generally will have to keep using the traditional crypto API for backwards +compatibility. + +Note: new kernel features shouldn't support every algorithm, but rather make a +deliberate choice about what algorithm(s) to support. History has shown that +making a deliberate, thoughtful choice greatly simplifies code maintenance, +reduces the chance for mistakes (such as using an obsolete, insecure, or +inappropriate algorithm), and makes your feature easier to use. + +Testing +======= + +The crypto library uses standard KUnit tests. Like many of the kernel's other +KUnit tests, they are included in the set of tests that is run by +``tools/testing/kunit/kunit.py run --alltests``. + +A ``.kunitconfig`` file is also provided to run just the crypto library tests. +For example, here's how to run them in user-mode Linux: + +.. code-block:: sh + + tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/ + +Many of the crypto algorithms have architecture-optimized implementations. +Testing those requires building an appropriate kernel and running the tests +either in QEMU or on appropriate hardware. Here's one example with QEMU: + +.. code-block:: sh + + tools/testing/kunit/kunit.py run --kunitconfig=lib/crypto/ --arch=arm64 --make_options LLVM=1 + +Depending on the code being tested, flags may need to be passed to QEMU to +emulate the correct type of hardware for the code to be reached. + +Since correctness is essential in cryptographic code, new architecture-optimized +code is accepted only if it can be tested in QEMU. + +Note: the crypto library also includes FIPS 140 self-tests. These are +lightweight, are designed specifically to meet FIPS 140 requirements, and exist +*only* to meet those requirements. Normal testing done by kernel developers and +integrators should use the much more comprehensive KUnit tests instead. + +API documentation +================= + +.. toctree:: + :maxdepth: 2 + + libcrypto-auth-encryption + libcrypto-blockcipher + libcrypto-hash + libcrypto-signature + libcrypto-unauth-encryption + libcrypto-utils + sha3 diff --git a/Documentation/crypto/sha3.rst b/Documentation/crypto/sha3.rst new file mode 100644 index 000000000..250669c98 --- /dev/null +++ b/Documentation/crypto/sha3.rst @@ -0,0 +1,132 @@ +.. SPDX-License-Identifier: GPL-2.0-or-later + +.. _sha3: + +========================== +SHA-3 Algorithm Collection +========================== + +.. contents:: + +Overview +======== + +The SHA-3 family of algorithms, as specified in NIST FIPS-202 [1]_, contains six +algorithms based on the Keccak sponge function. The differences between them +are: the "rate" (how much of the state buffer gets updated with new data between +invocations of the Keccak function and analogous to the "block size"), what +domain separation suffix gets appended to the input data, and how much output +data is extracted at the end. The Keccak sponge function is designed such that +arbitrary amounts of output can be obtained for certain algorithms. + +Four digest algorithms are provided: + + - SHA3-224 + - SHA3-256 + - SHA3-384 + - SHA3-512 + +Additionally, two Extendable-Output Functions (XOFs) are provided: + + - SHAKE128 + - SHAKE256 + +The SHA-3 library API supports all six of these algorithms. The four digest +algorithms are also supported by the crypto_shash and crypto_ahash APIs. + +This document describes the SHA-3 library API. + + +Digests +======= + +The following functions compute SHA-3 digests:: + + void sha3_224(const u8 *in, size_t in_len, u8 out[SHA3_224_DIGEST_SIZE]); + void sha3_256(const u8 *in, size_t in_len, u8 out[SHA3_256_DIGEST_SIZE]); + void sha3_384(const u8 *in, size_t in_len, u8 out[SHA3_384_DIGEST_SIZE]); + void sha3_512(const u8 *in, size_t in_len, u8 out[SHA3_512_DIGEST_SIZE]); + +For users that need to pass in data incrementally, an incremental API is also +provided. The incremental API uses the following struct:: + + struct sha3_ctx { ... }; + +Initialization is done with one of:: + + void sha3_224_init(struct sha3_ctx *ctx); + void sha3_256_init(struct sha3_ctx *ctx); + void sha3_384_init(struct sha3_ctx *ctx); + void sha3_512_init(struct sha3_ctx *ctx); + +Input data is then added with any number of calls to:: + + void sha3_update(struct sha3_ctx *ctx, const u8 *in, size_t in_len); + +Finally, the digest is generated using:: + + void sha3_final(struct sha3_ctx *ctx, u8 *out); + +which also zeroizes the context. The length of the digest is determined by the +initialization function that was called. + + +Extendable-Output Functions +=========================== + +The following functions compute the SHA-3 extendable-output functions (XOFs):: + + void shake128(const u8 *in, size_t in_len, u8 *out, size_t out_len); + void shake256(const u8 *in, size_t in_len, u8 *out, size_t out_len); + +For users that need to provide the input data incrementally and/or receive the +output data incrementally, an incremental API is also provided. The incremental +API uses the following struct:: + + struct shake_ctx { ... }; + +Initialization is done with one of:: + + void shake128_init(struct shake_ctx *ctx); + void shake256_init(struct shake_ctx *ctx); + +Input data is then added with any number of calls to:: + + void shake_update(struct shake_ctx *ctx, const u8 *in, size_t in_len); + +Finally, the output data is extracted with any number of calls to:: + + void shake_squeeze(struct shake_ctx *ctx, u8 *out, size_t out_len); + +and telling it how much data should be extracted. Note that performing multiple +squeezes, with the output laid consecutively in a buffer, gets exactly the same +output as doing a single squeeze for the combined amount over the same buffer. + +More input data cannot be added after squeezing has started. + +Once all the desired output has been extracted, zeroize the context:: + + void shake_zeroize_ctx(struct shake_ctx *ctx); + + +Testing +======= + +To test the SHA-3 code, use sha3_kunit (CONFIG_CRYPTO_LIB_SHA3_KUNIT_TEST). + +Since the SHA-3 algorithms are FIPS-approved, when the kernel is booted in FIPS +mode the SHA-3 library also performs a simple self-test. This is purely to meet +a FIPS requirement. Normal testing done by kernel developers and integrators +should use the much more comprehensive KUnit test suite instead. + + +References +========== + +.. [1] https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.202.pdf + + +API Function Reference +====================== + +.. kernel-doc:: include/crypto/sha3.h diff --git a/Documentation/crypto/userspace-if.rst b/Documentation/crypto/userspace-if.rst new file mode 100644 index 000000000..d6194346e --- /dev/null +++ b/Documentation/crypto/userspace-if.rst @@ -0,0 +1,455 @@ +.. _crypto_userspace_interface: + +User Space Interface +==================== + +Introduction +------------ + +AF_ALG provides unprivileged userspace programs access to arbitrary hash, +symmetric cipher, AEAD, and RNG algorithms that are implemented in kernel-mode +code. + +AF_ALG is insecure and is deprecated. Originally added to the kernel in 2010, +most kernel developers now consider it to be a mistake. Support for hardware +accelerators, which was the original purpose of AF_ALG, has been removed. + +AF_ALG continues to be supported only for backwards compatibility. + +Starting in Linux v7.3, the set of algorithms supported by AF_ALG is limited by +default. See :ref:`/proc/sys/crypto/af_alg_restrict <af_alg_restrict>`. + +On systems where no programs using AF_ALG remain, the support for it should be +disabled entirely by setting ``/proc/sys/crypto/af_alg_restrict`` to 2 or by +disabling ``CONFIG_CRYPTO_USER_API_*`` in the kernel configuration. + +Deprecation +----------- + +AF_ALG was originally intended to provide userspace programs access to crypto +accelerators that they wouldn't otherwise have access to. + +However, that capability turned out to not be useful on very many systems. More +significantly, the actual implementation exposes a vastly greater amount of +functionality than that. It actually provides access to all software algorithms. + +This includes arbitrary compositions of different algorithms created via a +complex template system, as well as algorithms that only make sense as internal +implementation details of other algorithms. In the past, it also included full +zero-copy support, which was difficult for the kernel to implement securely. + +Ultimately, these algorithms are just math computations. They use the same +instructions that userspace programs already have access to, just accessed in a +much more convoluted and less efficient way. + +Indeed, userspace code is nearly always what is being used anyway. These same +algorithms are widely implemented in userspace crypto libraries. + +Even when zero-copy and off-CPU accelerators were supported, AF_ALG was usually +much slower than optimized software cryptography in userspace. This was +especially true for the small message sizes usually seen in performance-critical +workloads. While it was possible to demonstrate performance wins for hashing +large files on embedded devices, it is hard to imagine a situation where this +would be performance-critical. + +Nowadays, AF_ALG no longer supports zero-copy or off-CPU accelerators. +Therefore, it is *always* slower than an optimized userspace implementation, +even for large messages. The only possible advantage left is that it avoids +duplicating code between kernel and userspace. However, userspace +implementations, especially hardware-accelerated ones, do not need to be large. +Just because OpenSSL is huge does not mean that all userspace cryptography +libraries are. + +Meanwhile, AF_ALG hasn't been withstanding modern vulnerability discovery tools +such as syzbot and large language models. It receives a steady stream of CVEs. +Some of the examples include: + +- CVE-2026-31677 +- CVE-2026-31431 (https://copy.fail) +- CVE-2025-38079 +- CVE-2025-37808 +- CVE-2024-26824 +- CVE-2022-48781 +- CVE-2019-8912 +- CVE-2018-14619 +- CVE-2017-18075 +- CVE-2017-17806 +- CVE-2017-17805 +- CVE-2016-10147 +- CVE-2015-8970 +- CVE-2015-3331 +- CVE-2014-9644 +- CVE-2013-7421 +- CVE-2011-4081 + +Hardware accelerator drivers are frequently buggy. To reduce attack surface, +AF_ALG now only provides access to algorithms implemented in software. This +means that AF_ALG no longer fulfills its original purpose. + +It is recommended that, whenever possible, userspace programs be migrated to +userspace crypto code (which again, is what is normally used anyway) and +``CONFIG_CRYPTO_USER_API_*`` be disabled. On systems that use SELinux, SELinux +can also be used to restrict the use of AF_ALG to trusted programs. + +The remainder of this documentation provides the historical documentation for +the deprecated AF_ALG interface. + +User Space API General Remarks +------------------------------ + +The kernel crypto API is accessible from user space. Currently, the +following ciphers are accessible: + +- Message digest including keyed message digest (HMAC, CMAC) + +- Symmetric ciphers + +- AEAD ciphers + +- Random Number Generators + +The interface is provided via socket type using the type AF_ALG. In +addition, the setsockopt option type is SOL_ALG. In case the user space +header files do not export these flags yet, use the following macros: + +:: + + #ifndef AF_ALG + #define AF_ALG 38 + #endif + #ifndef SOL_ALG + #define SOL_ALG 279 + #endif + + +A cipher is accessed with the same name as done for the in-kernel API +calls. This includes the generic vs. unique naming schema for ciphers as +well as the enforcement of priorities for generic names. + +To interact with the kernel crypto API, a socket must be created by the +user space application. User space invokes the cipher operation with the +send()/write() system call family. The result of the cipher operation is +obtained with the read()/recv() system call family. + +The following API calls assume that the socket descriptor is already +opened by the user space application and discusses only the kernel +crypto API specific invocations. + +To initialize the socket interface, the following sequence has to be +performed by the consumer: + +1. Create a socket of type AF_ALG with the struct sockaddr_alg + parameter specified below for the different cipher types. + +2. Invoke bind with the socket descriptor + +3. Invoke accept with the socket descriptor. The accept system call + returns a new file descriptor that is to be used to interact with the + particular cipher instance. When invoking send/write or recv/read + system calls to send data to the kernel or obtain data from the + kernel, the file descriptor returned by accept must be used. + +In-place Cipher operation +------------------------- + +Just like the in-kernel operation of the kernel crypto API, the user +space interface allows the cipher operation in-place. That means that +the input buffer used for the send/write system call and the output +buffer used by the read/recv system call may be one and the same. This +is of particular interest for symmetric cipher operations where a +copying of the output data to its final destination can be avoided. + +If a consumer on the other hand wants to maintain the plaintext and the +ciphertext in different memory locations, all a consumer needs to do is +to provide different memory pointers for the encryption and decryption +operation. + +Message Digest API +------------------ + +The message digest type to be used for the cipher operation is selected +when invoking the bind syscall. bind requires the caller to provide a +filled struct sockaddr data structure. This data structure must be +filled as follows: + +:: + + struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "hash", /* this selects the hash logic in the kernel */ + .salg_name = "sha1" /* this is the cipher name */ + }; + + +The salg_type value "hash" applies to message digests and keyed message +digests. Though, a keyed message digest is referenced by the appropriate +salg_name. Please see below for the setsockopt interface that explains +how the key can be set for a keyed message digest. + +Using the send() system call, the application provides the data that +should be processed with the message digest. The send system call allows +the following flags to be specified: + +- MSG_MORE: If this flag is set, the send system call acts like a + message digest update function where the final hash is not yet + calculated. If the flag is not set, the send system call calculates + the final message digest immediately. + +With the recv() system call, the application can read the message digest +from the kernel crypto API. If the buffer is too small for the message +digest, the flag MSG_TRUNC is set by the kernel. + +In order to set a message digest key, the calling application must use +the setsockopt() option of ALG_SET_KEY or ALG_SET_KEY_BY_KEY_SERIAL. If the +key is not set the HMAC operation is performed without the initial HMAC state +change caused by the key. + +Symmetric Cipher API +-------------------- + +The operation is very similar to the message digest discussion. During +initialization, the struct sockaddr data structure must be filled as +follows: + +:: + + struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "skcipher", /* this selects the symmetric cipher */ + .salg_name = "cbc(aes)" /* this is the cipher name */ + }; + + +Before data can be sent to the kernel using the write/send system call +family, the consumer must set the key. The key setting is described with +the setsockopt invocation below. + +Using the sendmsg() system call, the application provides the data that +should be processed for encryption or decryption. In addition, the IV is +specified with the data structure provided by the sendmsg() system call. + +The sendmsg system call parameter of struct msghdr is embedded into the +struct cmsghdr data structure. See recv(2) and cmsg(3) for more +information on how the cmsghdr data structure is used together with the +send/recv system call family. That cmsghdr data structure holds the +following information specified with a separate header instances: + +- specification of the cipher operation type with one of these flags: + + - ALG_OP_ENCRYPT - encryption of data + + - ALG_OP_DECRYPT - decryption of data + +- specification of the IV information marked with the flag ALG_SET_IV + +The send system call family allows the following flag to be specified: + +- MSG_MORE: If this flag is set, the send system call acts like a + cipher update function where more input data is expected with a + subsequent invocation of the send system call. + +Note: The kernel reports -EINVAL for any unexpected data. The caller +must make sure that all data matches the constraints given in +/proc/crypto for the selected cipher. + +With the recv() system call, the application can read the result of the +cipher operation from the kernel crypto API. The output buffer must be +at least as large as to hold all blocks of the encrypted or decrypted +data. If the output data size is smaller, only as many blocks are +returned that fit into that output buffer size. + +AEAD Cipher API +--------------- + +The operation is very similar to the symmetric cipher discussion. During +initialization, the struct sockaddr data structure must be filled as +follows: + +:: + + struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "aead", /* this selects the symmetric cipher */ + .salg_name = "gcm(aes)" /* this is the cipher name */ + }; + + +Before data can be sent to the kernel using the write/send system call +family, the consumer must set the key. The key setting is described with +the setsockopt invocation below. + +In addition, before data can be sent to the kernel using the write/send +system call family, the consumer must set the authentication tag size. +To set the authentication tag size, the caller must use the setsockopt +invocation described below. + +Using the sendmsg() system call, the application provides the data that +should be processed for encryption or decryption. In addition, the IV is +specified with the data structure provided by the sendmsg() system call. + +The sendmsg system call parameter of struct msghdr is embedded into the +struct cmsghdr data structure. See recv(2) and cmsg(3) for more +information on how the cmsghdr data structure is used together with the +send/recv system call family. That cmsghdr data structure holds the +following information specified with a separate header instances: + +- specification of the cipher operation type with one of these flags: + + - ALG_OP_ENCRYPT - encryption of data + + - ALG_OP_DECRYPT - decryption of data + +- specification of the IV information marked with the flag ALG_SET_IV + +- specification of the associated authentication data (AAD) with the + flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together + with the plaintext / ciphertext. See below for the memory structure. + +The send system call family allows the following flag to be specified: + +- MSG_MORE: If this flag is set, the send system call acts like a + cipher update function where more input data is expected with a + subsequent invocation of the send system call. + +Note: The kernel reports -EINVAL for any unexpected data. The caller +must make sure that all data matches the constraints given in +/proc/crypto for the selected cipher. + +With the recv() system call, the application can read the result of the +cipher operation from the kernel crypto API. The output buffer must be +at least as large as defined with the memory structure below. If the +output data size is smaller, the cipher operation is not performed. + +The authenticated decryption operation may indicate an integrity error. +Such breach in integrity is marked with the -EBADMSG error code. + +AEAD Memory Structure +~~~~~~~~~~~~~~~~~~~~~ + +The AEAD cipher operates with the following information that is +communicated between user and kernel space as one data stream: + +- plaintext or ciphertext + +- associated authentication data (AAD) + +- authentication tag + +The sizes of the AAD and the authentication tag are provided with the +sendmsg and setsockopt calls (see there). As the kernel knows the size +of the entire data stream, the kernel is now able to calculate the right +offsets of the data components in the data stream. + +The user space caller must arrange the aforementioned information in the +following order: + +- AEAD encryption input: AAD \|\| plaintext + +- AEAD decryption input: AAD \|\| ciphertext \|\| authentication tag + +The output buffer the user space caller provides must be at least as +large to hold the following data: + +- AEAD encryption output: ciphertext \|\| authentication tag + +- AEAD decryption output: plaintext + +Random Number Generator API +--------------------------- + +Again, the operation is very similar to the other APIs. During +initialization, the struct sockaddr data structure must be filled as +follows: + +:: + + struct sockaddr_alg sa = { + .salg_family = AF_ALG, + .salg_type = "rng", /* this selects the random number generator */ + .salg_name = "stdrng" /* this is the RNG name */ + }; + + +Depending on the RNG type, the RNG must be seeded. The seed is provided +using the setsockopt interface to set the key. The SP800-90A DRBGs do +not require a seed, but may be seeded. The seed is also known as a +*Personalization String* in NIST SP 800-90A standard. + +Using the read()/recvmsg() system calls, random numbers can be obtained. +The kernel generates at most 128 bytes in one call. If user space +requires more data, multiple calls to read()/recvmsg() must be made. + +WARNING: The user space caller may invoke the initially mentioned accept +system call multiple times. In this case, the returned file descriptors +have the same state. + +Following CAVP testing interfaces are enabled when kernel is built with +CRYPTO_USER_API_RNG_CAVP option: + +- the concatenation of *Entropy* and *Nonce* can be provided to the RNG via + ALG_SET_DRBG_ENTROPY setsockopt interface. Setting the entropy requires + CAP_SYS_ADMIN permission. + +- *Additional Data* can be provided using the send()/sendmsg() system calls, + but only after the entropy has been set. + +Zero-Copy Interface +------------------- + +AF_ALG used to have zero-copy support, but it was removed due to it being a +frequent source of vulnerabilities. For backwards compatibility the splice() +and sendfile() system calls are still supported, but the kernel will make an +internal copy of the data before passing it to the crypto code. + + +Setsockopt Interface +-------------------- + +In addition to the read/recv and send/write system call handling to send +and retrieve data subject to the cipher operation, a consumer also needs +to set the additional information for the cipher operation. This +additional information is set using the setsockopt system call that must +be invoked with the file descriptor of the open cipher (i.e. the file +descriptor returned by the accept system call). + +Each setsockopt invocation must use the level SOL_ALG. + +The setsockopt interface allows setting the following data using the +mentioned optname: + +- ALG_SET_KEY -- Setting the key. Key setting is applicable to: + + - the skcipher cipher type (symmetric ciphers) + + - the hash cipher type (keyed message digests) + + - the AEAD cipher type + + - the RNG cipher type to provide the seed + +- ALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t. + This operation behaves the same as ALG_SET_KEY. The decrypted + data is copied from a keyring key, and uses that data as the + key for symmetric encryption. + + The passed in key_serial_t must have the KEY_(POS|USR|GRP|OTH)_SEARCH + permission set, otherwise -EPERM is returned. Supports key types: user, + logon, encrypted, and trusted. + +- ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for + AEAD ciphers. For a encryption operation, the authentication tag of + the given size will be generated. For a decryption operation, the + provided ciphertext is assumed to contain an authentication tag of + the given size (see section about AEAD memory layout below). + +- ALG_SET_DRBG_ENTROPY -- Setting the entropy of the random number generator. + This option is applicable to RNG cipher type only. + +User space API example +---------------------- + +Please see [1] for libkcapi which provides an easy-to-use wrapper around +the aforementioned Netlink kernel interface. [1] also contains a test +application that invokes all libkcapi API calls. + +[1] https://www.chronox.de/libkcapi/index.html |