crypto: doc - AHASH API documentation

The API function calls exported by the kernel crypto API for AHASHes to be used by consumers are documented. Signed-off-by: Stephan Mueller <smueller@chronox.de> Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>

crypto: doc - AHASH API documentation
The API function calls exported by the kernel crypto API for AHASHes to be used by consumers are documented. Signed-off-by: Stephan Mueller <smueller@chronox.de> Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
Stephan Mueller · Herbert Xu
1 parent 5d8c723f61
Showing 1 changed file with 228 additions and 0 deletions Side-by-side Diff
include/crypto/hash.h
@@ -202,11 +202,35 @@
 	struct crypto_tfm base;
 };
  
+/**
+ * DOC: Asynchronous Message Digest API
+ *
+ * The asynchronous message digest API is used with the ciphers of type
+ * CRYPTO_ALG_TYPE_AHASH (listed as type "ahash" in /proc/crypto)
+ *
+ * The asynchronous cipher operation discussion provided for the
+ * CRYPTO_ALG_TYPE_ABLKCIPHER API applies here as well.
+ */
+
 static inline struct crypto_ahash *__crypto_ahash_cast(struct crypto_tfm *tfm)
 {
 	return container_of(tfm, struct crypto_ahash, base);
 }
  
+/**
+ * crypto_alloc_ahash() - allocate ahash cipher handle
+ * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
+ *	      ahash cipher
+ * @type: specifies the type of the cipher
+ * @mask: specifies the mask for the cipher
+ *
+ * Allocate a cipher handle for an ahash. The returned struct
+ * crypto_ahash is the cipher handle that is required for any subsequent
+ * API invocation for that ahash.
+ *
+ * Return: allocated cipher handle in case of success; IS_ERR() is true in case
+ *	   of an error, PTR_ERR() returns the error code.
+ */
 struct crypto_ahash *crypto_alloc_ahash(const char *alg_name, u32 type,
 					u32 mask);
  
@@ -215,6 +239,10 @@
 	return &tfm->base;
 }
  
+/**
+ * crypto_free_ahash() - zeroize and free the ahash handle
+ * @tfm: cipher handle to be freed
+ */
 static inline void crypto_free_ahash(struct crypto_ahash *tfm)
 {
 	crypto_destroy_tfm(tfm, crypto_ahash_tfm(tfm));
@@ -238,6 +266,16 @@
 	return __crypto_hash_alg_common(crypto_ahash_tfm(tfm)->__crt_alg);
 }
  
+/**
+ * crypto_ahash_digestsize() - obtain message digest size
+ * @tfm: cipher handle
+ *
+ * The size for the message digest created by the message digest cipher
+ * referenced with the cipher handle is returned.
+ *
+ *
+ * Return: message digest size of cipher
+ */
 static inline unsigned int crypto_ahash_digestsize(struct crypto_ahash *tfm)
 {
 	return crypto_hash_alg_common(tfm)->digestsize;
  
@@ -263,12 +301,32 @@
 	crypto_tfm_clear_flags(crypto_ahash_tfm(tfm), flags);
 }
  
+/**
+ * crypto_ahash_reqtfm() - obtain cipher handle from request
+ * @req: asynchronous request handle that contains the reference to the ahash
+ *	 cipher handle
+ *
+ * Return the ahash cipher handle that is registered with the asynchronous
+ * request handle ahash_request.
+ *
+ * Return: ahash cipher handle
+ */
 static inline struct crypto_ahash *crypto_ahash_reqtfm(
 	struct ahash_request *req)
 {
 	return __crypto_ahash_cast(req->base.tfm);
 }
  
+/**
+ * crypto_ahash_reqsize() - obtain size of the request data structure
+ * @tfm: cipher handle
+ *
+ * Return the size of the ahash state size. With the crypto_ahash_export
+ * function, the caller can export the state into a buffer whose size is
+ * defined with this function.
+ *
+ * Return: size of the ahash state
+ */
 static inline unsigned int crypto_ahash_reqsize(struct crypto_ahash *tfm)
 {
 	return tfm->reqsize;
  
  
  
  
  
  
  
  
  
@@ -279,38 +337,166 @@
 	return req->__ctx;
 }
  
+/**
+ * crypto_ahash_setkey - set key for cipher handle
+ * @tfm: cipher handle
+ * @key: buffer holding the key
+ * @keylen: length of the key in bytes
+ *
+ * The caller provided key is set for the ahash cipher. The cipher
+ * handle must point to a keyed hash in order for this function to succeed.
+ *
+ * Return: 0 if the setting of the key was successful; < 0 if an error occurred
+ */
 int crypto_ahash_setkey(struct crypto_ahash *tfm, const u8 *key,
 			unsigned int keylen);
+
+/**
+ * crypto_ahash_finup() - update and finalize message digest
+ * @req: reference to the ahash_request handle that holds all information
+ *	 needed to perform the cipher operation
+ *
+ * This function is a "short-hand" for the function calls of
+ * crypto_ahash_update and crypto_shash_final. The parameters have the same
+ * meaning as discussed for those separate functions.
+ *
+ * Return: 0 if the message digest creation was successful; < 0 if an error
+ *	   occurred
+ */
 int crypto_ahash_finup(struct ahash_request *req);
+
+/**
+ * crypto_ahash_final() - calculate message digest
+ * @req: reference to the ahash_request handle that holds all information
+ *	 needed to perform the cipher operation
+ *
+ * Finalize the message digest operation and create the message digest
+ * based on all data added to the cipher handle. The message digest is placed
+ * into the output buffer registered with the ahash_request handle.
+ *
+ * Return: 0 if the message digest creation was successful; < 0 if an error
+ *	   occurred
+ */
 int crypto_ahash_final(struct ahash_request *req);
+
+/**
+ * crypto_ahash_digest() - calculate message digest for a buffer
+ * @req: reference to the ahash_request handle that holds all information
+ *	 needed to perform the cipher operation
+ *
+ * This function is a "short-hand" for the function calls of crypto_ahash_init,
+ * crypto_ahash_update and crypto_ahash_final. The parameters have the same
+ * meaning as discussed for those separate three functions.
+ *
+ * Return: 0 if the message digest creation was successful; < 0 if an error
+ *	   occurred
+ */
 int crypto_ahash_digest(struct ahash_request *req);
  
+/**
+ * crypto_ahash_export() - extract current message digest state
+ * @req: reference to the ahash_request handle whose state is exported
+ * @out: output buffer of sufficient size that can hold the hash state
+ *
+ * This function exports the hash state of the ahash_request handle into the
+ * caller-allocated output buffer out which must have sufficient size (e.g. by
+ * calling crypto_ahash_reqsize).
+ *
+ * Return: 0 if the export was successful; < 0 if an error occurred
+ */
 static inline int crypto_ahash_export(struct ahash_request *req, void *out)
 {
 	return crypto_ahash_reqtfm(req)->export(req, out);
 }
  
+/**
+ * crypto_ahash_import() - import message digest state
+ * @req: reference to ahash_request handle the state is imported into
+ * @in: buffer holding the state
+ *
+ * This function imports the hash state into the ahash_request handle from the
+ * input buffer. That buffer should have been generated with the
+ * crypto_ahash_export function.
+ *
+ * Return: 0 if the import was successful; < 0 if an error occurred
+ */
 static inline int crypto_ahash_import(struct ahash_request *req, const void *in)
 {
 	return crypto_ahash_reqtfm(req)->import(req, in);
 }
  
+/**
+ * crypto_ahash_init() - (re)initialize message digest handle
+ * @req: ahash_request handle that already is initialized with all necessary
+ *	 data using the ahash_request_* API functions
+ *
+ * The call (re-)initializes the message digest referenced by the ahash_request
+ * handle. Any potentially existing state created by previous operations is
+ * discarded.
+ *
+ * Return: 0 if the message digest initialization was successful; < 0 if an
+ *	   error occurred
+ */
 static inline int crypto_ahash_init(struct ahash_request *req)
 {
 	return crypto_ahash_reqtfm(req)->init(req);
 }
  
+/**
+ * crypto_ahash_update() - add data to message digest for processing
+ * @req: ahash_request handle that was previously initialized with the
+ *	 crypto_ahash_init call.
+ *
+ * Updates the message digest state of the &ahash_request handle. The input data
+ * is pointed to by the scatter/gather list registered in the &ahash_request
+ * handle
+ *
+ * Return: 0 if the message digest update was successful; < 0 if an error
+ *	   occurred
+ */
 static inline int crypto_ahash_update(struct ahash_request *req)
 {
 	return crypto_ahash_reqtfm(req)->update(req);
 }
  
+/**
+ * DOC: Asynchronous Hash Request Handle
+ *
+ * The &ahash_request data structure contains all pointers to data
+ * required for the asynchronous cipher operation. This includes the cipher
+ * handle (which can be used by multiple &ahash_request instances), pointer
+ * to plaintext and the message digest output buffer, asynchronous callback
+ * function, etc. It acts as a handle to the ahash_request_* API calls in a
+ * similar way as ahash handle to the crypto_ahash_* API calls.
+ */
+
+/**
+ * ahash_request_set_tfm() - update cipher handle reference in request
+ * @req: request handle to be modified
+ * @tfm: cipher handle that shall be added to the request handle
+ *
+ * Allow the caller to replace the existing ahash handle in the request
+ * data structure with a different one.
+ */
 static inline void ahash_request_set_tfm(struct ahash_request *req,
 					 struct crypto_ahash *tfm)
 {
 	req->base.tfm = crypto_ahash_tfm(tfm);
 }
  
+/**
+ * ahash_request_alloc() - allocate request data structure
+ * @tfm: cipher handle to be registered with the request
+ * @gfp: memory allocation flag that is handed to kmalloc by the API call.
+ *
+ * Allocate the request data structure that must be used with the ahash
+ * message digest API calls. During
+ * the allocation, the provided ahash handle
+ * is registered in the request data structure.
+ *
+ * Return: allocated request handle in case of success; IS_ERR() is true in case
+ *	   of an error, PTR_ERR() returns the error code.
+ */
 static inline struct ahash_request *ahash_request_alloc(
 	struct crypto_ahash *tfm, gfp_t gfp)
 {
@@ -325,6 +511,10 @@
 	return req;
 }
  
+/**
+ * ahash_request_free() - zeroize and free the request data structure
+ * @req: request data structure cipher handle to be freed
+ */
 static inline void ahash_request_free(struct ahash_request *req)
 {
 	kzfree(req);
@@ -336,6 +526,31 @@
 	return container_of(req, struct ahash_request, base);
 }
  
+/**
+ * ahash_request_set_callback() - set asynchronous callback function
+ * @req: request handle
+ * @flags: specify zero or an ORing of the flags
+ *	   CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
+ *	   increase the wait queue beyond the initial maximum size;
+ *	   CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
+ * @compl: callback function pointer to be registered with the request handle
+ * @data: The data pointer refers to memory that is not used by the kernel
+ *	  crypto API, but provided to the callback function for it to use. Here,
+ *	  the caller can provide a reference to memory the callback function can
+ *	  operate on. As the callback function is invoked asynchronously to the
+ *	  related functionality, it may need to access data structures of the
+ *	  related functionality which can be referenced using this pointer. The
+ *	  callback function can access the memory via the "data" field in the
+ *	  &crypto_async_request data structure provided to the callback function.
+ *
+ * This function allows setting the callback function that is triggered once
+ * the cipher operation completes.
+ *
+ * The callback function is registered with the &ahash_request handle and
+ * must comply with the following template
+ *
+ *	void callback_function(struct crypto_async_request *req, int error)
+ */
 static inline void ahash_request_set_callback(struct ahash_request *req,
 					      u32 flags,
 					      crypto_completion_t compl,
@@ -346,6 +561,19 @@
 	req->base.flags = flags;
 }
  
+/**
+ * ahash_request_set_crypt() - set data buffers
+ * @req: ahash_request handle to be updated
+ * @src: source scatter/gather list
+ * @result: buffer that is filled with the message digest -- the caller must
+ *	    ensure that the buffer has sufficient space by, for example, calling
+ *	    crypto_ahash_digestsize()
+ * @nbytes: number of bytes to process from the source scatter/gather list
+ *
+ * By using this call, the caller references the source scatter/gather list.
+ * The source scatter/gather list points to the data the message digest is to
+ * be calculated for.
+ */
 static inline void ahash_request_set_crypt(struct ahash_request *req,
 					   struct scatterlist *src, u8 *result,
 					   unsigned int nbytes)
...	...	@@ -202,11 +202,35 @@
202	202	struct crypto_tfm base;
203	203	};
204	204
	205	+/**
	206	+ * DOC: Asynchronous Message Digest API
	207	+ *
	208	+ * The asynchronous message digest API is used with the ciphers of type
	209	+ * CRYPTO_ALG_TYPE_AHASH (listed as type "ahash" in /proc/crypto)
	210	+ *
	211	+ * The asynchronous cipher operation discussion provided for the
	212	+ * CRYPTO_ALG_TYPE_ABLKCIPHER API applies here as well.
	213	+ */
	214	+
205	215	static inline struct crypto_ahash __crypto_ahash_cast(struct crypto_tfm tfm)
206	216	{
207	217	return container_of(tfm, struct crypto_ahash, base);
208	218	}
209	219
	220	+/**
	221	+ * crypto_alloc_ahash() - allocate ahash cipher handle
	222	+ * @alg_name: is the cra_name / name or cra_driver_name / driver name of the
	223	+ * ahash cipher
	224	+ * @type: specifies the type of the cipher
	225	+ * @mask: specifies the mask for the cipher
	226	+ *
	227	+ * Allocate a cipher handle for an ahash. The returned struct
	228	+ * crypto_ahash is the cipher handle that is required for any subsequent
	229	+ * API invocation for that ahash.
	230	+ *
	231	+ * Return: allocated cipher handle in case of success; IS_ERR() is true in case
	232	+ * of an error, PTR_ERR() returns the error code.
	233	+ */
210	234	struct crypto_ahash crypto_alloc_ahash(const char alg_name, u32 type,
211	235	u32 mask);
212	236
...	...	@@ -215,6 +239,10 @@
215	239	return &tfm->base;
216	240	}
217	241
	242	+/**
	243	+ * crypto_free_ahash() - zeroize and free the ahash handle
	244	+ * @tfm: cipher handle to be freed
	245	+ */
218	246	static inline void crypto_free_ahash(struct crypto_ahash *tfm)
219	247	{
220	248	crypto_destroy_tfm(tfm, crypto_ahash_tfm(tfm));
...	...	@@ -238,6 +266,16 @@
238	266	return __crypto_hash_alg_common(crypto_ahash_tfm(tfm)->__crt_alg);
239	267	}
240	268
	269	+/**
	270	+ * crypto_ahash_digestsize() - obtain message digest size
	271	+ * @tfm: cipher handle
	272	+ *
	273	+ * The size for the message digest created by the message digest cipher
	274	+ * referenced with the cipher handle is returned.
	275	+ *
	276	+ *
	277	+ * Return: message digest size of cipher
	278	+ */
241	279	static inline unsigned int crypto_ahash_digestsize(struct crypto_ahash *tfm)
242	280	{
243	281	return crypto_hash_alg_common(tfm)->digestsize;
244	282
...	...	@@ -263,12 +301,32 @@
263	301	crypto_tfm_clear_flags(crypto_ahash_tfm(tfm), flags);
264	302	}
265	303
	304	+/**
	305	+ * crypto_ahash_reqtfm() - obtain cipher handle from request
	306	+ * @req: asynchronous request handle that contains the reference to the ahash
	307	+ * cipher handle
	308	+ *
	309	+ * Return the ahash cipher handle that is registered with the asynchronous
	310	+ * request handle ahash_request.
	311	+ *
	312	+ * Return: ahash cipher handle
	313	+ */
266	314	static inline struct crypto_ahash *crypto_ahash_reqtfm(
267	315	struct ahash_request *req)
268	316	{
269	317	return __crypto_ahash_cast(req->base.tfm);
270	318	}
271	319
	320	+/**
	321	+ * crypto_ahash_reqsize() - obtain size of the request data structure
	322	+ * @tfm: cipher handle
	323	+ *
	324	+ * Return the size of the ahash state size. With the crypto_ahash_export
	325	+ * function, the caller can export the state into a buffer whose size is
	326	+ * defined with this function.
	327	+ *
	328	+ * Return: size of the ahash state
	329	+ */
272	330	static inline unsigned int crypto_ahash_reqsize(struct crypto_ahash *tfm)
273	331	{
274	332	return tfm->reqsize;
275	333
276	334
277	335
278	336
279	337
280	338
281	339
282	340
283	341
...	...	@@ -279,38 +337,166 @@
279	337	return req->__ctx;
280	338	}
281	339
	340	+/**
	341	+ * crypto_ahash_setkey - set key for cipher handle
	342	+ * @tfm: cipher handle
	343	+ * @key: buffer holding the key
	344	+ * @keylen: length of the key in bytes
	345	+ *
	346	+ * The caller provided key is set for the ahash cipher. The cipher
	347	+ * handle must point to a keyed hash in order for this function to succeed.
	348	+ *
	349	+ * Return: 0 if the setting of the key was successful; < 0 if an error occurred
	350	+ */
282	351	int crypto_ahash_setkey(struct crypto_ahash tfm, const u8 key,
283	352	unsigned int keylen);
	353	+
	354	+/**
	355	+ * crypto_ahash_finup() - update and finalize message digest
	356	+ * @req: reference to the ahash_request handle that holds all information
	357	+ * needed to perform the cipher operation
	358	+ *
	359	+ * This function is a "short-hand" for the function calls of
	360	+ * crypto_ahash_update and crypto_shash_final. The parameters have the same
	361	+ * meaning as discussed for those separate functions.
	362	+ *
	363	+ * Return: 0 if the message digest creation was successful; < 0 if an error
	364	+ * occurred
	365	+ */
284	366	int crypto_ahash_finup(struct ahash_request *req);
	367	+
	368	+/**
	369	+ * crypto_ahash_final() - calculate message digest
	370	+ * @req: reference to the ahash_request handle that holds all information
	371	+ * needed to perform the cipher operation
	372	+ *
	373	+ * Finalize the message digest operation and create the message digest
	374	+ * based on all data added to the cipher handle. The message digest is placed
	375	+ * into the output buffer registered with the ahash_request handle.
	376	+ *
	377	+ * Return: 0 if the message digest creation was successful; < 0 if an error
	378	+ * occurred
	379	+ */
285	380	int crypto_ahash_final(struct ahash_request *req);
	381	+
	382	+/**
	383	+ * crypto_ahash_digest() - calculate message digest for a buffer
	384	+ * @req: reference to the ahash_request handle that holds all information
	385	+ * needed to perform the cipher operation
	386	+ *
	387	+ * This function is a "short-hand" for the function calls of crypto_ahash_init,
	388	+ * crypto_ahash_update and crypto_ahash_final. The parameters have the same
	389	+ * meaning as discussed for those separate three functions.
	390	+ *
	391	+ * Return: 0 if the message digest creation was successful; < 0 if an error
	392	+ * occurred
	393	+ */
286	394	int crypto_ahash_digest(struct ahash_request *req);
287	395
	396	+/**
	397	+ * crypto_ahash_export() - extract current message digest state
	398	+ * @req: reference to the ahash_request handle whose state is exported
	399	+ * @out: output buffer of sufficient size that can hold the hash state
	400	+ *
	401	+ * This function exports the hash state of the ahash_request handle into the
	402	+ * caller-allocated output buffer out which must have sufficient size (e.g. by
	403	+ * calling crypto_ahash_reqsize).
	404	+ *
	405	+ * Return: 0 if the export was successful; < 0 if an error occurred
	406	+ */
288	407	static inline int crypto_ahash_export(struct ahash_request req, void out)
289	408	{
290	409	return crypto_ahash_reqtfm(req)->export(req, out);
291	410	}
292	411
	412	+/**
	413	+ * crypto_ahash_import() - import message digest state
	414	+ * @req: reference to ahash_request handle the state is imported into
	415	+ * @in: buffer holding the state
	416	+ *
	417	+ * This function imports the hash state into the ahash_request handle from the
	418	+ * input buffer. That buffer should have been generated with the
	419	+ * crypto_ahash_export function.
	420	+ *
	421	+ * Return: 0 if the import was successful; < 0 if an error occurred
	422	+ */
293	423	static inline int crypto_ahash_import(struct ahash_request req, const void in)
294	424	{
295	425	return crypto_ahash_reqtfm(req)->import(req, in);
296	426	}
297	427
	428	+/**
	429	+ * crypto_ahash_init() - (re)initialize message digest handle
	430	+ * @req: ahash_request handle that already is initialized with all necessary
	431	+ * data using the ahash_request_* API functions
	432	+ *
	433	+ * The call (re-)initializes the message digest referenced by the ahash_request
	434	+ * handle. Any potentially existing state created by previous operations is
	435	+ * discarded.
	436	+ *
	437	+ * Return: 0 if the message digest initialization was successful; < 0 if an
	438	+ * error occurred
	439	+ */
298	440	static inline int crypto_ahash_init(struct ahash_request *req)
299	441	{
300	442	return crypto_ahash_reqtfm(req)->init(req);
301	443	}
302	444
	445	+/**
	446	+ * crypto_ahash_update() - add data to message digest for processing
	447	+ * @req: ahash_request handle that was previously initialized with the
	448	+ * crypto_ahash_init call.
	449	+ *
	450	+ * Updates the message digest state of the &ahash_request handle. The input data
	451	+ * is pointed to by the scatter/gather list registered in the &ahash_request
	452	+ * handle
	453	+ *
	454	+ * Return: 0 if the message digest update was successful; < 0 if an error
	455	+ * occurred
	456	+ */
303	457	static inline int crypto_ahash_update(struct ahash_request *req)
304	458	{
305	459	return crypto_ahash_reqtfm(req)->update(req);
306	460	}
307	461
	462	+/**
	463	+ * DOC: Asynchronous Hash Request Handle
	464	+ *
	465	+ * The &ahash_request data structure contains all pointers to data
	466	+ * required for the asynchronous cipher operation. This includes the cipher
	467	+ * handle (which can be used by multiple &ahash_request instances), pointer
	468	+ * to plaintext and the message digest output buffer, asynchronous callback
	469	+ * function, etc. It acts as a handle to the ahash_request_* API calls in a
	470	+ * similar way as ahash handle to the crypto_ahash_* API calls.
	471	+ */
	472	+
	473	+/**
	474	+ * ahash_request_set_tfm() - update cipher handle reference in request
	475	+ * @req: request handle to be modified
	476	+ * @tfm: cipher handle that shall be added to the request handle
	477	+ *
	478	+ * Allow the caller to replace the existing ahash handle in the request
	479	+ * data structure with a different one.
	480	+ */
308	481	static inline void ahash_request_set_tfm(struct ahash_request *req,
309	482	struct crypto_ahash *tfm)
310	483	{
311	484	req->base.tfm = crypto_ahash_tfm(tfm);
312	485	}
313	486
	487	+/**
	488	+ * ahash_request_alloc() - allocate request data structure
	489	+ * @tfm: cipher handle to be registered with the request
	490	+ * @gfp: memory allocation flag that is handed to kmalloc by the API call.
	491	+ *
	492	+ * Allocate the request data structure that must be used with the ahash
	493	+ * message digest API calls. During
	494	+ * the allocation, the provided ahash handle
	495	+ * is registered in the request data structure.
	496	+ *
	497	+ * Return: allocated request handle in case of success; IS_ERR() is true in case
	498	+ * of an error, PTR_ERR() returns the error code.
	499	+ */
314	500	static inline struct ahash_request *ahash_request_alloc(
315	501	struct crypto_ahash *tfm, gfp_t gfp)
316	502	{
...	...	@@ -325,6 +511,10 @@
325	511	return req;
326	512	}
327	513
	514	+/**
	515	+ * ahash_request_free() - zeroize and free the request data structure
	516	+ * @req: request data structure cipher handle to be freed
	517	+ */
328	518	static inline void ahash_request_free(struct ahash_request *req)
329	519	{
330	520	kzfree(req);
...	...	@@ -336,6 +526,31 @@
336	526	return container_of(req, struct ahash_request, base);
337	527	}
338	528
	529	+/**
	530	+ * ahash_request_set_callback() - set asynchronous callback function
	531	+ * @req: request handle
	532	+ * @flags: specify zero or an ORing of the flags
	533	+ * CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
	534	+ * increase the wait queue beyond the initial maximum size;
	535	+ * CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep
	536	+ * @compl: callback function pointer to be registered with the request handle
	537	+ * @data: The data pointer refers to memory that is not used by the kernel
	538	+ * crypto API, but provided to the callback function for it to use. Here,
	539	+ * the caller can provide a reference to memory the callback function can
	540	+ * operate on. As the callback function is invoked asynchronously to the
	541	+ * related functionality, it may need to access data structures of the
	542	+ * related functionality which can be referenced using this pointer. The
	543	+ * callback function can access the memory via the "data" field in the
	544	+ * &crypto_async_request data structure provided to the callback function.
	545	+ *
	546	+ * This function allows setting the callback function that is triggered once
	547	+ * the cipher operation completes.
	548	+ *
	549	+ * The callback function is registered with the &ahash_request handle and
	550	+ * must comply with the following template
	551	+ *
	552	+ * void callback_function(struct crypto_async_request *req, int error)
	553	+ */
339	554	static inline void ahash_request_set_callback(struct ahash_request *req,
340	555	u32 flags,
341	556	crypto_completion_t compl,
...	...	@@ -346,6 +561,19 @@
346	561	req->base.flags = flags;
347	562	}
348	563
	564	+/**
	565	+ * ahash_request_set_crypt() - set data buffers
	566	+ * @req: ahash_request handle to be updated
	567	+ * @src: source scatter/gather list
	568	+ * @result: buffer that is filled with the message digest -- the caller must
	569	+ * ensure that the buffer has sufficient space by, for example, calling
	570	+ * crypto_ahash_digestsize()
	571	+ * @nbytes: number of bytes to process from the source scatter/gather list
	572	+ *
	573	+ * By using this call, the caller references the source scatter/gather list.
	574	+ * The source scatter/gather list points to the data the message digest is to
	575	+ * be calculated for.
	576	+ */
349	577	static inline void ahash_request_set_crypt(struct ahash_request *req,
350	578	struct scatterlist src, u8 result,
351	579	unsigned int nbytes)