crypto: doc - convert crypto API documentation to Sphinx

With the conversion of the kernel crypto API DocBook to Sphinx, the
monolithic document is broken up into individual documents. The
documentation is unchanged with the exception of a slight reordering to
keep the individual document parts self-contained.
Signed-off-by: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Documentation/crypto/api-aead.rst

+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
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: aead_alg
+
+Authenticated Encryption With Associated Data (AEAD) Cipher API
+---------------------------------------------------------------
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: crypto_alloc_aead
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: crypto_free_aead
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: crypto_aead_ivsize
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: crypto_aead_authsize
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: crypto_aead_blocksize
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: crypto_aead_setkey
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: crypto_aead_setauthsize
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: crypto_aead_encrypt
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: 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
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: aead_request_set_tfm
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: aead_request_alloc
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: aead_request_free
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: aead_request_set_callback
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: aead_request_set_crypt
+
+.. kernel-doc:: include/crypto/aead.h
+   :functions: aead_request_set_ad

Documentation/crypto/api-akcipher.rst

+Asymmetric Cipher Algorithm Definitions
+---------------------------------------
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: akcipher_alg
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: akcipher_request
+
+Asymmetric Cipher API
+---------------------
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :doc: Generic Public Key API
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: crypto_alloc_akcipher
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: crypto_free_akcipher
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: crypto_akcipher_set_pub_key
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: crypto_akcipher_set_priv_key
+
+Asymmetric Cipher Request Handle
+--------------------------------
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: akcipher_request_alloc
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: akcipher_request_free
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: akcipher_request_set_callback
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: akcipher_request_set_crypt
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: crypto_akcipher_maxsize
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: crypto_akcipher_encrypt
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: crypto_akcipher_decrypt
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: crypto_akcipher_sign
+
+.. kernel-doc:: include/crypto/akcipher.h
+   :functions: crypto_akcipher_verify

Documentation/crypto/api-digest.rst

+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
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: ahash_alg
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: 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
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_free_ahash
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_ahash_init
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_ahash_digestsize
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_ahash_reqtfm
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_ahash_reqsize
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_ahash_setkey
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_ahash_finup
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_ahash_final
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_ahash_digest
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_ahash_export
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: 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
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: ahash_request_alloc
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: ahash_request_free
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: ahash_request_set_callback
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: 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
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_free_shash
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_blocksize
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_digestsize
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_descsize
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_setkey
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_digest
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_export
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_import
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_init
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_update
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_final
+
+.. kernel-doc:: include/crypto/hash.h
+   :functions: crypto_shash_finup

Documentation/crypto/api-rng.rst

+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
+
+.. kernel-doc:: include/crypto/rng.h
+   :functions: crypto_rng_alg
+
+.. kernel-doc:: include/crypto/rng.h
+   :functions: crypto_free_rng
+
+.. kernel-doc:: include/crypto/rng.h
+   :functions: crypto_rng_generate
+
+.. kernel-doc:: include/crypto/rng.h
+   :functions: crypto_rng_get_bytes
+
+.. kernel-doc:: include/crypto/rng.h
+   :functions: crypto_rng_reset
+
+.. kernel-doc:: include/crypto/rng.h
+   :functions: crypto_rng_seedsize

Documentation/crypto/api-samples.rst

+Code Examples
+=============
+
+Code Example For Symmetric Key Cipher Operation
+-----------------------------------------------
+
+::
+
+
+    struct tcrypt_result {
+        struct completion completion;
+        int err;
+    };
+
+    /* tie all data structures together */
+    struct skcipher_def {
+        struct scatterlist sg;
+        struct crypto_skcipher *tfm;
+        struct skcipher_request *req;
+        struct tcrypt_result result;
+    };
+
+    /* Callback function */
+    static void test_skcipher_cb(struct crypto_async_request *req, int error)
+    {
+        struct tcrypt_result *result = req->data;
+
+        if (error == -EINPROGRESS)
+            return;
+        result->err = error;
+        complete(&result->completion);
+        pr_info("Encryption finished successfully\n");
+    }
+
+    /* Perform cipher operation */
+    static unsigned int test_skcipher_encdec(struct skcipher_def *sk,
+                         int enc)
+    {
+        int rc = 0;
+
+        if (enc)
+            rc = crypto_skcipher_encrypt(sk->req);
+        else
+            rc = crypto_skcipher_decrypt(sk->req);
+
+        switch (rc) {
+        case 0:
+            break;
+        case -EINPROGRESS:
+        case -EBUSY:
+            rc = wait_for_completion_interruptible(
+                &sk->result.completion);
+            if (!rc && !sk->result.err) {
+                reinit_completion(&sk->result.completion);
+                break;
+            }
+        default:
+            pr_info("skcipher encrypt returned with %d result %d\n",
+                rc, sk->result.err);
+            break;
+        }
+        init_completion(&sk->result.completion);
+
+        return rc;
+    }
+
+    /* Initialize and trigger cipher operation */
+    static int test_skcipher(void)
+    {
+        struct skcipher_def sk;
+        struct crypto_skcipher *skcipher = NULL;
+        struct skcipher_request *req = NULL;
+        char *scratchpad = NULL;
+        char *ivdata = NULL;
+        unsigned char key[32];
+        int ret = -EFAULT;
+
+        skcipher = crypto_alloc_skcipher("cbc-aes-aesni", 0, 0);
+        if (IS_ERR(skcipher)) {
+            pr_info("could not allocate skcipher handle\n");
+            return PTR_ERR(skcipher);
+        }
+
+        req = skcipher_request_alloc(skcipher, GFP_KERNEL);
+        if (!req) {
+            pr_info("could not allocate skcipher request\n");
+            ret = -ENOMEM;
+            goto out;
+        }
+
+        skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,
+                          test_skcipher_cb,
+                          &sk.result);
+
+        /* AES 256 with random key */
+        get_random_bytes(&key, 32);
+        if (crypto_skcipher_setkey(skcipher, key, 32)) {
+            pr_info("key could not be set\n");
+            ret = -EAGAIN;
+            goto out;
+        }
+
+        /* IV will be random */
+        ivdata = kmalloc(16, GFP_KERNEL);
+        if (!ivdata) {
+            pr_info("could not allocate ivdata\n");
+            goto out;
+        }
+        get_random_bytes(ivdata, 16);
+
+        /* Input data will be random */
+        scratchpad = kmalloc(16, GFP_KERNEL);
+        if (!scratchpad) {
+            pr_info("could not allocate scratchpad\n");
+            goto out;
+        }
+        get_random_bytes(scratchpad, 16);
+
+        sk.tfm = skcipher;
+        sk.req = req;
+
+        /* We encrypt one block */
+        sg_init_one(&sk.sg, scratchpad, 16);
+        skcipher_request_set_crypt(req, &sk.sg, &sk.sg, 16, ivdata);
+        init_completion(&sk.result.completion);
+
+        /* encrypt data */
+        ret = test_skcipher_encdec(&sk, 1);
+        if (ret)
+            goto out;
+
+        pr_info("Encryption triggered successfully\n");
+
+    out:
+        if (skcipher)
+            crypto_free_skcipher(skcipher);
+        if (req)
+            skcipher_request_free(req);
+        if (ivdata)
+            kfree(ivdata);
+        if (scratchpad)
+            kfree(scratchpad);
+        return ret;
+    }
+
+
+Code Example For Use of Operational State Memory With SHASH
+-----------------------------------------------------------
+
+::
+
+
+    struct sdesc {
+        struct shash_desc shash;
+        char ctx[];
+    };
+
+    static struct sdescinit_sdesc(struct crypto_shash *alg)
+    {
+        struct sdescsdesc;
+        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;
+        sdesc->shash.flags = 0x0;
+        return sdesc;
+    }
+
+    static int calc_hash(struct crypto_shashalg,
+                 const unsigned chardata, unsigned int datalen,
+                 unsigned chardigest) {
+        struct sdescsdesc;
+        int ret;
+
+        sdesc = init_sdesc(alg);
+        if (IS_ERR(sdesc)) {
+            pr_info("trusted_key: can't alloc %s\n", hash_alg);
+            return PTR_ERR(sdesc);
+        }
+
+        ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest);
+        kfree(sdesc);
+        return ret;
+    }
+
+
+Code Example For Random Number Generator Usage
+----------------------------------------------
+
+::
+
+
+    static int get_random_numbers(u8 *buf, unsigned int len)
+    {
+        struct crypto_rngrng = NULL;
+        chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */
+        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;
+    }

Documentation/crypto/api-skcipher.rst

+Block Cipher Algorithm Definitions
+----------------------------------
+
+.. kernel-doc:: include/linux/crypto.h
+   :doc: Block Cipher Algorithm Definitions
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_alg
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: ablkcipher_alg
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: blkcipher_alg
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: cipher_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
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: crypto_free_skcipher
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: crypto_has_skcipher
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: crypto_skcipher_ivsize
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: crypto_skcipher_blocksize
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: crypto_skcipher_setkey
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: crypto_skcipher_reqtfm
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: crypto_skcipher_encrypt
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: 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
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: skcipher_request_set_tfm
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: skcipher_request_alloc
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: skcipher_request_free
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: skcipher_request_set_callback
+
+.. kernel-doc:: include/crypto/skcipher.h
+   :functions: skcipher_request_set_crypt
+
+Single Block Cipher API
+-----------------------
+
+.. kernel-doc:: include/linux/crypto.h
+   :doc: Single Block Cipher API
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_alloc_cipher
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_free_cipher
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_has_cipher
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_cipher_blocksize
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_cipher_setkey
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_cipher_encrypt_one
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_cipher_decrypt_one
+
+Asynchronous Block Cipher API - Deprecated
+------------------------------------------
+
+.. kernel-doc:: include/linux/crypto.h
+   :doc: Asynchronous Block Cipher API
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_alloc_ablkcipher
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_free_ablkcipher
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_has_ablkcipher
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_ablkcipher_ivsize
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_ablkcipher_blocksize
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_ablkcipher_setkey
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_ablkcipher_reqtfm
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_ablkcipher_encrypt
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_ablkcipher_decrypt
+
+Asynchronous Cipher Request Handle - Deprecated
+-----------------------------------------------
+
+.. kernel-doc:: include/linux/crypto.h
+   :doc: Asynchronous Cipher Request Handle
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_ablkcipher_reqsize
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: ablkcipher_request_set_tfm
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: ablkcipher_request_alloc
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: ablkcipher_request_free
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: ablkcipher_request_set_callback
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: ablkcipher_request_set_crypt
+
+Synchronous Block Cipher API - Deprecated
+-----------------------------------------
+
+.. kernel-doc:: include/linux/crypto.h
+   :doc: Synchronous Block Cipher API
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_alloc_blkcipher
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_free_blkcipher
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_has_blkcipher
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_name
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_ivsize
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_blocksize
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_setkey
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_encrypt
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_encrypt_iv
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_decrypt
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_decrypt_iv
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_set_iv
+
+.. kernel-doc:: include/linux/crypto.h
+   :functions: crypto_blkcipher_get_iv

Documentation/crypto/api.rst

+Programming Interface
+=====================
+
+Please note that the kernel crypto API contains the AEAD givcrypt API
+(crypto_aead_giv\* and aead_givcrypt\* function calls in
+include/crypto/aead.h). This API is obsolete and will be removed in the
+future. To obtain the functionality of an AEAD cipher with internal IV
+generation, use the IV generator as a regular cipher. For example,
+rfc4106(gcm(aes)) is the AEAD cipher with external IV generation and
+seqniv(rfc4106(gcm(aes))) implies that the kernel crypto API generates
+the IV. Different IV generators are available.
+
+.. class:: toc-title
+
+	   Table of contents
+
+.. toctree::
+   :maxdepth: 2
+
+   api-skcipher
+   api-aead
+   api-digest
+   api-rng
+   api-akcipher

Documentation/crypto/devel-algos.rst

+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.
+
+::
+
+       int crypto_unregister_alg(struct crypto_alg *alg);
+       int crypto_unregister_algs(struct crypto_alg *algs, int count);
+
+
+Notice that both registration and unregistration functions do return a
+value, so make sure to handle errors. A return code of zero implies
+success. Any return code < 0 implies an error.
+
+The bulk registration/unregistration functions register/unregister each
+transformation in the given array of length count. They handle errors as
+follows:
+
+-  crypto_register_algs() succeeds if and only if it successfully
+   registers all the given transformations. If an error occurs partway
+   through, then it rolls back successful registrations before returning
+   the error code. Note that if a driver needs to handle registration
+   errors for individual transformations, then it will need to use the
+   non-bulk function crypto_register_alg() instead.
+
+-  crypto_unregister_algs() tries to unregister all the given
+   transformations, continuing on error. It logs errors and always
+   returns zero.
+
+Single-Block Symmetric Ciphers [CIPHER]
+---------------------------------------
+
+Example of transformations: aes, arc4, ...
+
+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), ecb(arc4), ...
+
+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 blkcipher_alg and ablkcipher_alg
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Struct blkcipher_alg defines a synchronous block cipher whereas struct
+ablkcipher_alg defines an asynchronous block cipher.
+
+Please refer to the single block cipher description for schematics of
+the block cipher usage.
+
+Specifics Of Asynchronous Multi-Block Cipher
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are a couple of specifics to the asynchronous interface.
+
+First of all, some of the 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:
+
+::
+
+       int crypto_unregister_ahash(struct ahash_alg *alg);
+
+       int crypto_unregister_shash(struct shash_alg *alg);
+       int 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 .finish() 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
+
+
+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. The buffer containing the resulting hash will
+always be properly aligned to .cra_alignmask so there is no need to
+worry about this.

Documentation/crypto/index.rst

+=======================
+Linux Kernel 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.
+
+.. class:: toc-title
+
+	   Table of contents
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   architecture
+   devel-algos
+   userspace-if
+   api
+   api-samples

Documentation/crypto/intro.rst

+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.

Documentation/index.rst

@@ -58,6 +58,7 @@ needed).
    gpu/index
    security/index
    sound/index
+   crypto/index
 
 Korean translations
 -------------------