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

Commit 0d7f488f authored by Stephan Mueller's avatar Stephan Mueller Committed by Herbert Xu
Browse files

crypto: doc - cipher data structures 



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: default avatarStephan Mueller <smueller@chronox.de>
Signed-off-by: default avatarHerbert Xu <herbert@gondor.apana.org.au>
parent 968ab291

include/linux/crypto.h

+243 −3
Original line number Diff line number Diff line
@@ -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;