crypto: doc - cipher data structures
authorStephan Mueller <smueller@chronox.de>
Wed, 12 Nov 2014 04:27:49 +0000 (05:27 +0100)
committerHerbert Xu <herbert@gondor.apana.org.au>
Thu, 13 Nov 2014 14:31:40 +0000 (22:31 +0800)
The data structure of struct crypto_alg together with various other
data structures needed by cipher developers is documented wit all
parameters that can be set by a developer of a transformation. All
parameters that are internal to the crypto API are marked as such.

Signed-off-by: Stephan Mueller <smueller@chronox.de>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
include/linux/crypto.h

index d45e949699ea26370efafa682d5c7c5c39c39108..752360e1e8fe48c90e69c853426fc48ea5233afc 100644 (file)
@@ -127,6 +127,13 @@ struct skcipher_givcrypt_request;
 
 typedef void (*crypto_completion_t)(struct crypto_async_request *req, int err);
 
+/**
+ * DOC: Block Cipher Context Data Structures
+ *
+ * These data structures define the operating context for each block cipher
+ * type.
+ */
+
 struct crypto_async_request {
        struct list_head list;
        crypto_completion_t complete;
@@ -194,9 +201,63 @@ struct hash_desc {
        u32 flags;
 };
 
-/*
- * Algorithms: modular crypto algorithm implementations, managed
- * via crypto_register_alg() and crypto_unregister_alg().
+/**
+ * DOC: Block Cipher Algorithm Definitions
+ *
+ * These data structures define modular crypto algorithm implementations,
+ * managed via crypto_register_alg() and crypto_unregister_alg().
+ */
+
+/**
+ * struct ablkcipher_alg - asynchronous block cipher definition
+ * @min_keysize: Minimum key size supported by the transformation. This is the
+ *              smallest key length supported by this transformation algorithm.
+ *              This must be set to one of the pre-defined values as this is
+ *              not hardware specific. Possible values for this field can be
+ *              found via git grep "_MIN_KEY_SIZE" include/crypto/
+ * @max_keysize: Maximum key size supported by the transformation. This is the
+ *              largest key length supported by this transformation algorithm.
+ *              This must be set to one of the pre-defined values as this is
+ *              not hardware specific. Possible values for this field can be
+ *              found via git grep "_MAX_KEY_SIZE" include/crypto/
+ * @setkey: Set key for the transformation. This function is used to either
+ *         program a supplied key into the hardware or store the key in the
+ *         transformation context for programming it later. Note that this
+ *         function does modify the transformation context. This function can
+ *         be called multiple times during the existence of the transformation
+ *         object, so one must make sure the key is properly reprogrammed into
+ *         the hardware. This function is also responsible for checking the key
+ *         length for validity. In case a software fallback was put in place in
+ *         the @cra_init call, this function might need to use the fallback if
+ *         the algorithm doesn't support all of the key sizes.
+ * @encrypt: Encrypt a scatterlist of blocks. This function is used to encrypt
+ *          the supplied scatterlist containing the blocks of data. The crypto
+ *          API consumer is responsible for aligning the entries of the
+ *          scatterlist properly and making sure the chunks are correctly
+ *          sized. In case a software fallback was put in place in the
+ *          @cra_init call, this function might need to use the fallback if
+ *          the algorithm doesn't support all of the key sizes. In case the
+ *          key was stored in transformation context, the key might need to be
+ *          re-programmed into the hardware in this function. This function
+ *          shall not modify the transformation context, as this function may
+ *          be called in parallel with the same transformation object.
+ * @decrypt: Decrypt a single block. This is a reverse counterpart to @encrypt
+ *          and the conditions are exactly the same.
+ * @givencrypt: Update the IV for encryption. With this function, a cipher
+ *             implementation may provide the function on how to update the IV
+ *             for encryption.
+ * @givdecrypt: Update the IV for decryption. This is the reverse of
+ *             @givencrypt .
+ * @geniv: The transformation implementation may use an "IV generator" provided
+ *        by the kernel crypto API. Several use cases have a predefined
+ *        approach how IVs are to be updated. For such use cases, the kernel
+ *        crypto API provides ready-to-use implementations that can be
+ *        referenced with this variable.
+ * @ivsize: IV size applicable for transformation. The consumer must provide an
+ *         IV of exactly that size to perform the encrypt or decrypt operation.
+ *
+ * All fields except @givencrypt , @givdecrypt , @geniv and @ivsize are
+ * mandatory and must be filled.
  */
 struct ablkcipher_alg {
        int (*setkey)(struct crypto_ablkcipher *tfm, const u8 *key,
@@ -213,6 +274,32 @@ struct ablkcipher_alg {
        unsigned int ivsize;
 };
 
+/**
+ * struct aead_alg - AEAD cipher definition
+ * @maxauthsize: Set the maximum authentication tag size supported by the
+ *              transformation. A transformation may support smaller tag sizes.
+ *              As the authentication tag is a message digest to ensure the
+ *              integrity of the encrypted data, a consumer typically wants the
+ *              largest authentication tag possible as defined by this
+ *              variable.
+ * @setauthsize: Set authentication size for the AEAD transformation. This
+ *              function is used to specify the consumer requested size of the
+ *              authentication tag to be either generated by the transformation
+ *              during encryption or the size of the authentication tag to be
+ *              supplied during the decryption operation. This function is also
+ *              responsible for checking the authentication tag size for
+ *              validity.
+ * @setkey: see struct ablkcipher_alg
+ * @encrypt: see struct ablkcipher_alg
+ * @decrypt: see struct ablkcipher_alg
+ * @givencrypt: see struct ablkcipher_alg
+ * @givdecrypt: see struct ablkcipher_alg
+ * @geniv: see struct ablkcipher_alg
+ * @ivsize: see struct ablkcipher_alg
+ *
+ * All fields except @givencrypt , @givdecrypt , @geniv and @ivsize are
+ * mandatory and must be filled.
+ */
 struct aead_alg {
        int (*setkey)(struct crypto_aead *tfm, const u8 *key,
                      unsigned int keylen);
@@ -228,6 +315,18 @@ struct aead_alg {
        unsigned int maxauthsize;
 };
 
+/**
+ * struct blkcipher_alg - synchronous block cipher definition
+ * @min_keysize: see struct ablkcipher_alg
+ * @max_keysize: see struct ablkcipher_alg
+ * @setkey: see struct ablkcipher_alg
+ * @encrypt: see struct ablkcipher_alg
+ * @decrypt: see struct ablkcipher_alg
+ * @geniv: see struct ablkcipher_alg
+ * @ivsize: see struct ablkcipher_alg
+ *
+ * All fields except @geniv and @ivsize are mandatory and must be filled.
+ */
 struct blkcipher_alg {
        int (*setkey)(struct crypto_tfm *tfm, const u8 *key,
                      unsigned int keylen);
@@ -245,6 +344,53 @@ struct blkcipher_alg {
        unsigned int ivsize;
 };
 
+/**
+ * struct cipher_alg - single-block symmetric ciphers definition
+ * @cia_min_keysize: Minimum key size supported by the transformation. This is
+ *                  the smallest key length supported by this transformation
+ *                  algorithm. This must be set to one of the pre-defined
+ *                  values as this is not hardware specific. Possible values
+ *                  for this field can be found via git grep "_MIN_KEY_SIZE"
+ *                  include/crypto/
+ * @cia_max_keysize: Maximum key size supported by the transformation. This is
+ *                 the largest key length supported by this transformation
+ *                 algorithm. This must be set to one of the pre-defined values
+ *                 as this is not hardware specific. Possible values for this
+ *                 field can be found via git grep "_MAX_KEY_SIZE"
+ *                 include/crypto/
+ * @cia_setkey: Set key for the transformation. This function is used to either
+ *             program a supplied key into the hardware or store the key in the
+ *             transformation context for programming it later. Note that this
+ *             function does modify the transformation context. This function
+ *             can be called multiple times during the existence of the
+ *             transformation object, so one must make sure the key is properly
+ *             reprogrammed into the hardware. This function is also
+ *             responsible for checking the key length for validity.
+ * @cia_encrypt: Encrypt a single block. This function is used to encrypt a
+ *              single block of data, which must be @cra_blocksize big. This
+ *              always operates on a full @cra_blocksize and it is not possible
+ *              to encrypt a block of smaller size. The supplied buffers must
+ *              therefore also be at least of @cra_blocksize size. Both the
+ *              input and output buffers are always aligned to @cra_alignmask.
+ *              In case either of the input or output buffer supplied by user
+ *              of the crypto API is not aligned to @cra_alignmask, the crypto
+ *              API will re-align the buffers. The re-alignment means that a
+ *              new buffer will be allocated, the data will be copied into the
+ *              new buffer, then the processing will happen on the new buffer,
+ *              then the data will be copied back into the original buffer and
+ *              finally the new buffer will be freed. In case a software
+ *              fallback was put in place in the @cra_init call, this function
+ *              might need to use the fallback if the algorithm doesn't support
+ *              all of the key sizes. In case the key was stored in
+ *              transformation context, the key might need to be re-programmed
+ *              into the hardware in this function. This function shall not
+ *              modify the transformation context, as this function may be
+ *              called in parallel with the same transformation object.
+ * @cia_decrypt: Decrypt a single block. This is a reverse counterpart to
+ *              @cia_encrypt, and the conditions are exactly the same.
+ *
+ * All fields are mandatory and must be filled.
+ */
 struct cipher_alg {
        unsigned int cia_min_keysize;
        unsigned int cia_max_keysize;
@@ -261,6 +407,25 @@ struct compress_alg {
                              unsigned int slen, u8 *dst, unsigned int *dlen);
 };
 
+/**
+ * struct rng_alg - random number generator definition
+ * @rng_make_random: The function defined by this variable obtains a random
+ *                  number. The random number generator transform must generate
+ *                  the random number out of the context provided with this
+ *                  call.
+ * @rng_reset: Reset of the random number generator by clearing the entire state.
+ *            With the invocation of this function call, the random number
+ *             generator shall completely reinitialize its state. If the random
+ *            number generator requires a seed for setting up a new state,
+ *            the seed must be provided by the consumer while invoking this
+ *            function. The required size of the seed is defined with
+ *            @seedsize .
+ * @seedsize: The seed size required for a random number generator
+ *           initialization defined with this variable. Some random number
+ *           generators like the SP800-90A DRBG does not require a seed as the
+ *           seeding is implemented internally without the need of support by
+ *           the consumer. In this case, the seed size is set to zero.
+ */
 struct rng_alg {
        int (*rng_make_random)(struct crypto_rng *tfm, u8 *rdata,
                               unsigned int dlen);
@@ -277,6 +442,81 @@ struct rng_alg {
 #define cra_compress   cra_u.compress
 #define cra_rng                cra_u.rng
 
+/**
+ * struct crypto_alg - definition of a cryptograpic cipher algorithm
+ * @cra_flags: Flags describing this transformation. See include/linux/crypto.h
+ *            CRYPTO_ALG_* flags for the flags which go in here. Those are
+ *            used for fine-tuning the description of the transformation
+ *            algorithm.
+ * @cra_blocksize: Minimum block size of this transformation. The size in bytes
+ *                of the smallest possible unit which can be transformed with
+ *                this algorithm. The users must respect this value.
+ *                In case of HASH transformation, it is possible for a smaller
+ *                block than @cra_blocksize to be passed to the crypto API for
+ *                transformation, in case of any other transformation type, an
+ *                error will be returned upon any attempt to transform smaller
+ *                than @cra_blocksize chunks.
+ * @cra_ctxsize: Size of the operational context of the transformation. This
+ *              value informs the kernel crypto API about the memory size
+ *              needed to be allocated for the transformation context.
+ * @cra_alignmask: Alignment mask for the input and output data buffer. The data
+ *                buffer containing the input data for the algorithm must be
+ *                aligned to this alignment mask. The data buffer for the
+ *                output data must be aligned to this alignment mask. Note that
+ *                the Crypto API will do the re-alignment in software, but
+ *                only under special conditions and there is a performance hit.
+ *                The re-alignment happens at these occasions for different
+ *                @cra_u types: cipher -- For both input data and output data
+ *                buffer; ahash -- For output hash destination buf; shash --
+ *                For output hash destination buf.
+ *                This is needed on hardware which is flawed by design and
+ *                cannot pick data from arbitrary addresses.
+ * @cra_priority: Priority of this transformation implementation. In case
+ *               multiple transformations with same @cra_name are available to
+ *               the Crypto API, the kernel will use the one with highest
+ *               @cra_priority.
+ * @cra_name: Generic name (usable by multiple implementations) of the
+ *           transformation algorithm. This is the name of the transformation
+ *           itself. This field is used by the kernel when looking up the
+ *           providers of particular transformation.
+ * @cra_driver_name: Unique name of the transformation provider. This is the
+ *                  name of the provider of the transformation. This can be any
+ *                  arbitrary value, but in the usual case, this contains the
+ *                  name of the chip or provider and the name of the
+ *                  transformation algorithm.
+ * @cra_type: Type of the cryptographic transformation. This is a pointer to
+ *           struct crypto_type, which implements callbacks common for all
+ *           trasnformation types. There are multiple options:
+ *           &crypto_blkcipher_type, &crypto_ablkcipher_type,
+ *           &crypto_ahash_type, &crypto_aead_type, &crypto_rng_type.
+ *           This field might be empty. In that case, there are no common
+ *           callbacks. This is the case for: cipher, compress, shash.
+ * @cra_u: Callbacks implementing the transformation. This is a union of
+ *        multiple structures. Depending on the type of transformation selected
+ *        by @cra_type and @cra_flags above, the associated structure must be
+ *        filled with callbacks. This field might be empty. This is the case
+ *        for ahash, shash.
+ * @cra_init: Initialize the cryptographic transformation object. This function
+ *           is used to initialize the cryptographic transformation object.
+ *           This function is called only once at the instantiation time, right
+ *           after the transformation context was allocated. In case the
+ *           cryptographic hardware has some special requirements which need to
+ *           be handled by software, this function shall check for the precise
+ *           requirement of the transformation and put any software fallbacks
+ *           in place.
+ * @cra_exit: Deinitialize the cryptographic transformation object. This is a
+ *           counterpart to @cra_init, used to remove various changes set in
+ *           @cra_init.
+ * @cra_module: Owner of this transformation implementation. Set to THIS_MODULE
+ * @cra_list: internally used
+ * @cra_users: internally used
+ * @cra_refcnt: internally used
+ * @cra_destroy: internally used
+ *
+ * The struct crypto_alg describes a generic Crypto API algorithm and is common
+ * for all of the transformations. Any variable not documented here shall not
+ * be used by a cipher implementation as it is internal to the Crypto API.
+ */
 struct crypto_alg {
        struct list_head cra_list;
        struct list_head cra_users;