Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 3b72c814 authored by Stephan Mueller's avatar Stephan Mueller Committed by Jonathan Corbet
Browse files

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: default avatarStephan Mueller <smueller@chronox.de>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent 868c97a8

Documentation/crypto/api-aead.rst

0 → 100644
+68 −0
Original line number Diff line number Diff line 
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

0 → 100644
+56 −0
Original line number Diff line number Diff line 
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

0 → 100644
+122 −0
Original line number Diff line number Diff line 
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

0 → 100644
+32 −0
Original line number Diff line number Diff line 
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

0 → 100644
+224 −0
Original line number Diff line number Diff line 
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;

    }