From: "Joy M. Latten" Subject: Re: [PATCH v2 01/11] crypto: Documentation - crypto API high level spec Date: Wed, 05 Nov 2014 16:21:22 -0600 Message-ID: <1415226082.5083.24.camel@oc8377654763.ibm.com> References: <6375771.bx7QqLJLuR@tachyon.chronox.de> <4163724.RCMDlx8dmE@tachyon.chronox.de> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: QUOTED-PRINTABLE Cc: Herbert Xu , "David S. Miller" , Marek Vasut , Jason Cooper , Grant Likely , Geert Uytterhoeven , Linux Kernel Developers List , linux-crypto@vger.kernel.org To: Stephan Mueller Return-path: Received: from e39.co.us.ibm.com ([32.97.110.160]:33324 "EHLO e39.co.us.ibm.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750877AbaKEWVa (ORCPT ); Wed, 5 Nov 2014 17:21:30 -0500 Received: from /spool/local by e39.co.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Wed, 5 Nov 2014 15:21:29 -0700 In-Reply-To: <4163724.RCMDlx8dmE@tachyon.chronox.de> Sender: linux-crypto-owner@vger.kernel.org List-ID: Hi Stephan, Great docs! I think they will be very useful! Thanks! I only have 2 comments below. regards, Joy On Sun, 2014-11-02 at 21:35 +0100, Stephan Mueller wrote: > The design of the kernel crypto API as well as hints to program with > the kernel crypto API are given. >=20 > The documentation contains: > * design aspects of crypto API > * develper specific hints > * references to the API function description >=20 > Signed-off-by: Stephan Mueller > CC: Marek Vasut > --- > Documentation/crypto/crypto-API-spec.txt | 721 +++++++++++++++++++++= ++++++++++ > 1 file changed, 721 insertions(+) > create mode 100644 Documentation/crypto/crypto-API-spec.txt >=20 > diff --git a/Documentation/crypto/crypto-API-spec.txt b/Documentation= /crypto/crypto-API-spec.txt > new file mode 100644 > index 0000000..8a24c98 > --- /dev/null > +++ b/Documentation/crypto/crypto-API-spec.txt > @@ -0,0 +1,721 @@ > +Kernel Crypto API Interface Specification > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +The kernel crypto API offers a rich set of cryptographic ciphers as = well as > +other data transformation mechanisms and methods to invoke these. Th= is document > +contains a description of the API and provides example code. > + > +To understand and properly use the kernel crypto API a brief explana= tion of its > +structure is given. Based on the architecture, the API can be separa= ted into > +different components. Following the architecture specification, hint= s to > +developers of ciphers are provided. Pointers to the API function cal= l > +documentation are given at the end. > + > +The kernel crypto API refers to all algorithms as "transformation". = Therefore, a > +cipher handle variable usually has the name "tfm". Besides cryptogra= phic > +operations, the kernel crypto API also knows compression transforms = 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 AP= I as well > +as for developers implementing ciphers. This API specification, howe= ver, does > +not discusses all API calls available to data transformation impleme= ntations > +((i.e. implementations of ciphers and other transformations (such as= CRC or > +even compression algorithms) that can register with the kernel crypt= o API). > + > +Note: The terms "transformation" and cipher algorithm are used inter= changably. > + > + > +Terminology > +----------- > + > +The transformation implementation is an actual code or interface to = hardware > +which implements a certain transformation with precisely defined beh= avior. > + > +The transformation object (TFM) is an instance of a transformation > +implementation. There can be multiple transformation objects associa= ted with > +a single transformation implementation. Each of those transformation= objects > +is held by a crypto API consumer or another transformation. Transfor= mation > +object is allocated when a crypto API consumer requests a transforma= tion > +implementation. The consumer is then provided with a structure, whic= h contains > +a transformation object (TFM). > + > +The transformation context is private data associated with the trans= formation > +object. > + > + > +Kernel Crypto API Architecture > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D > + > +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 ciphe= rs and > +message digests. In addition, the kernel crypto API provides numerou= s > +"templates" that can be used in conjunction with the single block ci= phers 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 ciphe= rs or keyed > +message digests. > + > +A single block cipher may even be called with multiple templates. Ho= wever, > +templates cannot be used without a single cipher. Although you go into further explanation shortly, I think an example or two here might help reader to immediately grab concept. i.e. aes, cbc(aes), ... > + > + > +Synchronous and asynchronous operation > +-------------------------------------- > + > +The kernel crypto API provides synchronous and asynchronous API oper= ations. > + > +When using the synchronous API operation, the caller invokes a ciphe= r operation > +which is performed synchronously by the kernel crypto API. That mean= s, the > +caller waits until the cipher operation completes. Therefore, the ke= rnel crypto > +API calls work like regular function calls. For synchronous operatio= n, the set > +of API calls is small and conceptually similar to any other crypto l= ibrary. > + > +Asynchronous operation is provided by the kernel crypto API which im= plies 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 callba= ck function > +the kernel crypto API can invoke to signal the completion of the cip= her > +operation. Furthermore, the caller must ensure it can handle such as= ynchronous > +events by applying appropriate locking around its data. The kernel c= rypto API > +does not perform any special serialization operation to protect the = caller's > +data integrity. > + > + > +Kernel 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 tem= plate and > +single block cipher, respectively. If applicable, additional templat= es may > +enclose other templates, such as > + > + template1(template2(single block cipher))) > + > +The kernel crypto API may provide multiple implementations of a temp= late or a > +single block cipher. For example, AES on newer Intel hardware has th= e following > +implementations: AES-NI, assembler implementation, or straight C. No= w, when > +using the string "aes" with the kernel crypto API, which cipher impl= ementation > +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 t= he string to > +refer to a cipher during initialization of a cipher handle, the kern= el crypto > +API looks up all implementations providing an implementation with th= at name and > +selects the implementation with the highest priority. > + > +Now, a caller may have the need to refer to a specific cipher implem= entation and > +thus does not want to rely on the priority-based selection. To accom= modate 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 implementat= ion. > + > +The list of available ciphers is given in /proc/crypto. When reading= that file, > +all available ciphers are listed. However, that list does not specif= y all > +possible permutations of templates and ciphers. Each block listed in > +/proc/crypto contains the following information: > + > + * 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 > + > + * 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 nu= mber > + of current consumers of this cipher) > + > + * selftest: specification whether the self test for the cipher pass= ed > + > + * type: > + - blkcipher for symmetric block ciphers > + - ablkcipher for asymmetric block ciphers > + - cipher for single block ciphers that may be used with an > + additional template > + - shash for symmetric message digest > + - ahash for asymmetric message digest > + - aead for AEAD cipher type > + - compression for compression type transforms > + - rng for random number generator > + - givcipher for cipher with associated IV generator > + > + * 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 generation type: > + - eseqiv for encrypted sequence number based IV generation > + - seqiv for sequence number based IV generation > + - chainiv for chain iv generation > + - is a marker that the cipher implements IV generation > + and handling as it is specific to the given cipher > + > + > +Key sizes > +--------- > + > +When allocating a cipher handle, the caller only specifies the ciphe= r 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 le= ngth of the > +provided key. Thus, the kernel crypto API does not provide a separat= e way to > +select the particular symmetric cipher key size. > + > + > +Cipher allocation type and masks > +-------------------------------- > + > +The different cipher handle allocation functions allow the specifica= tion 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 the aforementio= ned cipher > +types: > + > + * CRYPTO_ALG_TYPE_CIPHER Raw block cipher > + * CRYPTO_ALG_TYPE_COMPRESS Compression > + * CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with Associated Da= ta (MAC) > + * CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher > + * CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher > + * CRYPTO_ALG_TYPE_GIVCIPHER > + * CRYPTO_ALG_TYPE_DIGEST Raw message digest > + * CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_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_PCOMPRESS > + > +The mask flag restricts the type of cipher. The only allowed flag is > +CRYPTO_ALG_ASYNC to restrict the cipher lookup function to asynchron= ous ciphers. > +Usually, a caller provides a 0 for the mask flag. > + > +When the caller provides a mask and type specification, the caller l= imits the > +kernel crypto API=C2=B4s search 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. > + > + > +Developing Cipher Algorithms > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D > + > +Registering and unregistering transformation > +--------------------------------------------- > + > +There are three distinct types of registration functions in the Cryp= to API. > +One is used to register a generic cryptographic transformation, whil= e the > +other two are specific to HASH transformations and COMPRESSion. We w= ill > +discuss the latter two in a separate chapter, here we will only look= at > +the generic ones. > + > +The generic registration functions can be found in include/linux/cry= pto.h > +and their definition can be seen below. The former function register= s a > +single transformation, while the latter works on an array of transfo= rmation > +descriptions. The latter is useful when registering transformations = in bulk. > + > + 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. > + > +The bulk registration / unregistration functions require that struct= crypto_alg > +is an array of count size. These functions simply loop over that arr= ay and > +register / unregister each individual algorithm. If an error occurs,= the > +loop is terminated at the offending algorithm definition. That means= , the > +algorithms prior to the offending algorithm are successfully registe= red. > + > +Single-block ciphers [CIPHER] > +----------------------------- > +Example of transformations: aes, arc4, ... > + > +This section describes the simplest of all transformation implementa= tions, > +that being the CIPHER type. The CIPHER type is used for transformati= ons > +which operate on exactly one block at a time and there are no depend= encies > +between blocks at all. > + Picky, but I think maybe transitioning reader to the symmetric ciphers might be a bit helpful here... because I was still interpreting "cipher= " as meaning everything. But after scanning below I think we are only talking about symmetric ciphers now... > +Registration specifics > +...................... > + > +The registration of [CIPHER] algorithm is specific in that struct cr= ypto_alg > +field .cra_type is empty. The .cra_u.cipher has to be filled in with= proper > +callbacks to implement this transformation. > + > +Fields in struct cipher_alg explained > +..................................... > + > +This section explains the .cra_u.cipher fields and how they are call= ed. > +All of the fields are mandatory and must be filled: > + > + .cia_min_keysize ... Minimum key size supported by the transforma= tion. > + - 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 h= ardware > + specific. > + - Possible values for this field can be foun= d via: > + $ git grep "_MIN_KEY_SIZE" include/crypto/ > + .cia_max_keysize ... Maximum key size supported by the transforma= tion. > + - This is the largest key length supported b= y this > + transformation algorithm. This must be set= to one > + of the pre-defined values as this is not h= ardware > + specific. > + - Possible values for this field can be foun= d 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 transfo= rmation > + context. > + - This function can be called multiple times= during > + the existence of the transformation object= , so one > + must make sure the key is properly reprogr= ammed > + into the hardware. > + - This function is also responsible for chec= king the > + key length for validity. > + - In case a software fallback was put in pla= ce in > + the .cra_init() call, this function might = need to > + use the fallback if the algorithm doesn't = support > + all of the key sizes. > + .cia_encrypt() ..... Encrypt a single block. > + - This function is used to encrypt a single = block of > + data, which must be .cra_blocksize big. Th= is always > + operates on a full .cra_blocksize and it i= s not > + possible to encrypt a block of smaller siz= e. The > + supplied buffers must therefore also be at= least > + of .cra_blocksize size. > + - Both the input and output buffers are alwa= ys aligned > + to .cra_alignmask . In case either of the = input or > + output buffer supplied by user of the cryp= to API is > + not aligned to .cra_alignmask, the crypto = API will > + re-align the buffers. The re-alignment mea= ns that a > + new buffer will be allocated, the data wil= l be copied > + into the new buffer, then the processing w= ill happen > + on the new buffer, then the data will be c= opied back > + into the original buffer and finally the n= ew buffer > + will be freed. > + - In case a software fallback was put in pla= ce 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 transformati= on context, > + the key might need to be re-programmed int= o the > + hardware in this function. > + - This function shall not modify the transfo= rmation > + 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_encr= ypt(), and > + the conditions are exactly the same. > + > +Here are schematics of how these functions are called when operated = from > +other part of the kernel. Note that the .cia_setkey() call might hap= pen > +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 ti= mes > +is also valid: > + > + KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. > + v v v v > + .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt(= ) > + | | > + '---> CIPHERTEXT1 '---> = CIPHERTEXT2 > + > + > +Multi-block ciphers [BLKCIPHER] [ABLKCIPHER] > +-------------------------------------------- > + > +Example of transformations: cbc(aes), ecb(arc4), ... > + > +This section describes the multi-block cipher transformation impleme= ntations > +for both synchronous [BLKCIPHER] and asynchronous [ABLKCIPHER] case.= The > +multi-block ciphers are used for transformations which operate on sc= atterlists > +of data supplied to the transformation functions. They output the re= sult into > +a scatterlist of data as well. > + > +Registration specifics > +...................... > + > +The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms is one of= the most > +standard procedures throughout the crypto API. There are no specific= s for > +this case other that re-aligning of input and output buffers does no= t happen > +automatically within the crypto API, but is the responsibility of th= e crypto > +API consumer. The crypto API consumer shall use crypto_blkcipher_ali= gnmask() > +or crypto_ablkcipher_alignmask() respectively to determine the needs= of the > +transformation object and prepare the scatterlist with data accordin= gly. > + > +Fields in struct blkcipher_alg and struct ablkcipher_alg explained > +.................................................................. > + > +This section explains the .cra_u.blkcipher and .cra_u.cra_ablkcipher= fields > +and how they are called. Please note that this is very similar to th= e basic > +CIPHER case for all but minor details. All of the fields but .geniv = are > +mandatory and must be filled: > + > + .min_keysize ... Minimum key size supported by the transformation= =2E > + - This is the smallest key length supported by t= his > + transformation algorithm. This must be set to = one > + of the pre-defined values as this is not hardw= are > + specific. > + - Possible values for this field can be found vi= a: > + $ git grep "_MIN_KEY_SIZE" include/crypto/ > + .max_keysize ... Maximum key size supported by the transformation= =2E > + - This is the largest key length supported by th= is > + transformation algorithm. This must be set to = one > + of the pre-defined values as this is not hardw= are > + specific. > + - Possible values for this field can be found vi= a: > + $ git grep "_MAX_KEY_SIZE" include/crypto/ > + .setkey() ...... Set key for the transformation. > + - This function is used to either program a supp= lied > + key into the hardware or store the key in the > + transformation context for programming it late= r. Note > + that this function does modify the transformat= ion > + context. > + - This function can be called multiple times dur= ing > + the existence of the transformation object, so= one > + must make sure the key is properly reprogramme= d > + into the hardware. > + - This function is also responsible for checking= the > + key length for validity. > + - In case a software fallback was put in place i= n > + the .cra_init() call, this function might need= to > + use the fallback if the algorithm doesn't supp= ort > + 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 e= ntries > + of the scatterlist properly and making sure th= e > + chunks are correctly sized. > + - In case a software fallback was put in place i= n > + the .cra_init() call, this function might need= to > + use the fallback if the algorithm doesn't supp= ort > + all of the key sizes. > + - In case the key was stored in transformation c= ontext, > + the key might need to be re-programmed into th= e > + hardware in this function. > + - This function shall not modify the transformat= ion > + context, as this function may be called in par= allel > + with the same transformation object. > + .decrypt() ..... Decrypt a single block. > + - This is a reverse counterpart to .encrypt(), a= nd the > + conditions are exactly the same. > + > +Please refer to the single block cipher description for schematics o= f the block > +cipher usage. The usage patterns are exactly the same for [ABLKCIPHE= R] and > +[BLKCIPHER] as they are for plain [CIPHER]. > + > +Specifics of asynchronous multi-block cipher > +............................................ > + > +There are a couple of specifics to the [ABLKCIPHER] interface. > + > +First of all, some of the drivers will want to use the Generic Scatt= erWalk > +in case the hardware needs to be fed separate chunks of the scatterl= ist > +which contains the plaintext and will contain the ciphertext. Please= refer > +below for a description and usage of the Generic ScatterWalk interfa= ce. > + > +It is recommended to enqueue cryptographic transformation requests i= nto > +generic crypto queues. This allows for these requests to be processe= d in > +sequence as the cryptographic hardware becomes free. > + > + > +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 [A= HASH] > +and the amount of HASH transformations we are registering. You can f= ind > +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 transformatio= n 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); > + > +Common fields of struct shash_alg and ahash_alg explained > +......................................................... > + > +For definition of these structures, please refer to include/crypto/h= ash.h . > +We will now explain the meaning of each field: > + > + .init() ......... Initialize the transformation context. > + - Intended only to initialize the state of the = HASH > + transformation at the begining. This shall fi= ll in > + the internal structures used during the entir= e duration > + of the whole transformation. > + - No data processing happens at this point. > + .update() ....... Push chunk of data into the driver for transfor= mation. > + - This function actually pushes blocks of data = from upper > + layers into the driver, which then passes tho= se to the > + hardware as seen fit. > + - This function must not finalize the HASH tran= sformation, > + this only adds more data into the transformat= ion. > + - This function shall not modify the transforma= tion > + context, as this function may be called in pa= rallel > + with the same transformation object. > + - Data processing can happen synchronously [SHA= SH] or > + asynchronously [AHASH] at this point. > + .final() ....... Retrieve result from the driver. > + - This function finalizes the transformation an= d retrieves > + the resulting hash from the driver and pushes= it back to > + upper layers. > + - No data processing happens at this point. > + .finup() ........ Combination of update()+final() . > + - This function is effectively a combination of= update() > + and final() calls issued in sequence. > + - As some hardware cannot do update() and final= () > + separately, this callback was added to allow = such > + hardware to be used at least by IPsec. > + - Data processing can happen synchronously [SHA= SH] or > + asynchronously [AHASH] at this point. > + .digest() ....... Combination of init()+update()+final() . > + - This function effectively behaves as the enti= re chain > + of operations, init(), update() and final() i= ssued in > + sequence. > + - Just like .finup(), this was added for hardwa= re which > + cannot do even the .finup(), but can only do = the whole > + transformation in one run. > + - Data processing can happen synchronously [SHA= SH] or > + asynchronously [AHASH] at this point. > + > + .setkey() ....... Set optional key used by the hashing algorithm = =2E > + - Intended to push optional key used by the has= hing > + algorithm from upper layers into the driver. > + - This function can store the key in the transf= ormation > + context or can outright program it into the h= ardware. > + In the former case, one must be careful to pr= ogram > + the key into the hardware at appropriate time= and one > + must be careful that .setkey() can be called = multiple > + times during the existence of the transformat= ion > + object. > + - Not all hashing algorithms do implement this = function. > + -> SHAx/MDx/CRCx do NOT implement this functi= on. > + -> HMAC(MDx)/HMAC(SHAx) do implement this fun= ction. > + - This function must be called before any other= of the > + init()/update()/final()/finup()/digest() is c= alled. > + Maybe it would be good to mention that setkey is only required for "keyed message digests" such as the hmacs. Although you do point this out above by naming them. > - No data processing happens at this point. > + > + .export() ....... Export partial state of the transformation . > + - This function dumps the entire state of the o= ngoing > + transformation into a provided block of data = so it > + can be .import()ed back later on. > + - This is useful in case you want to save parti= al result > + of the transformation after processing certai= n amount > + of data and reload this partial result multip= le times > + later on for multiple re-use. > + - No data processing happens at this point. > + .import() ....... Import partial state of the transformation . > + - This function loads the entire state of the o= ngoing > + transformation from a provided block of data = so the > + transformation can continue from this point o= nward. > + - No data processing happens at this point. > + > +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 immed= iatelly > +by .finish() is also a perfectly valid transformation. > + > + I) DATA -----------. > + v > + .init() -> .update() -> .final() ! .update() might not= be called > + ^ | | at all in this scen= ario. > + '----' '---> HASH > + > + II) DATA -----------.-----------. > + v v > + .init() -> .update() -> .finup() ! .update() may not b= e called > + ^ | | at all in this scen= ario. > + '----' '---> HASH > + > + III) DATA -----------. > + v > + .digest() ! The entire process = is handled > + | by the .digest() ca= ll. > + '---------------> HASH > + > +Here is a schematic of how the .export()/.import() functions are cal= led when > +used from another part of the kernel. > + > + KEY--. DATA--. > + v v ! .update() may n= ot 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 no= t be called > + ^ | | at all in this s= cenario. > + '----' '--> HASH1 > + > + PARTIAL_HASH--. DATA2-. > + v v > + .import -> .finup() > + | > + '---------------> HASH2 > + > +The struct hash_alg_common fields and it's mirror in struct shash_al= g > +....................................................................= =2E > + > +This structure defines various size constraints and generic properti= es of > +the hashing algorithm that is being implemented. Let us first inspec= t the > +size properties: > + > + digestsize .... Size of the result of the transformation. > + - A buffer of this size must be available to the = =2Efinal() > + and .finup() calls, so they can store the resul= ting hash > + into it. > + - For various predefined sizes, search include/cr= ypto/ > + using 'git grep _DIGEST_SIZE include/crypto' . > + statesize ..... Size of the block for partial state of the transf= ormation. > + - A buffer of this size must be passed to the .ex= port() > + function as it will save the partial state of t= he > + transformation into it. On the other side, the = =2Eimport() > + function will load the state from a buffer of t= his size > + as well. > + > + > +Specifics of asynchronous HASH transformation > +............................................. > + > +There are a couple of specifics to the [AHASH] interface. > + > +First of all, some of the drivers will want to use the Generic Scatt= erWalk > +in case the hardware needs to be fed separate chunks of the scatterl= ist > +which contains the input data. The buffer containing the resulting h= ash will > +always be properly aligned to .cra_alignmask so there is no need to = worry > +about this. Please refer to the section 9.1) of this document of the > +description and usage of the Generic ScatterWalk interface. > + > +It is recommended to enqueue cryptographic transformation requests i= nto > +generic crypto queues. This allows for these requests to be processe= d in > +sequence as the cryptographic hardware becomes free. > + > + > +Single block cipher API > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +See source code comments for the *_cipher* calls in include/linux/cr= ypto.h. > + > + > +Synchronous block cipher API > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D > + > +See source code comments for the *_blkcipher* calls in include/linux= /crypto.h. > + > + > +Asynchronous block cipher API > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D > + > +See source code comments for the *_ablkcipher* calls and "ablkcipher= _request_* > +calls in include/linux/crypto.h. > + > + > +Synchronous message digest API > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D > + > +See source code comments for the *_hash* calls in include/linux/cryp= to.h. > + > + > +Synchronous message digest API with caller-accessible state space > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > + > +See source code comments for the *_shash* calls in include/crypto/ha= sh.h. > + > + > +Asynchronous message digest API > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D > + > +See source code comments for the *_ahash* calls and "ahash_request_* > +calls in include/crypto/hash.h. > + > + > +Random number generation API > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D > + > +See source code comments for the *_rng* calls in include/crypto/hash= =2Eh. > + > + > +AEAD asynchronous cipher API > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D > + > +See source code comments for the *_aead* calls and "aead_request_* > +calls in include/linux/crypto.h. > + > + > +Authors > +=3D=3D=3D=3D=3D=3D=3D > + > +Stephan Mueller > +Marek Vasut