1 .. SPDX-License-Identifier: GPL-2.0 !! 1 =============
2 !! 2 CRYPTO ENGINE
3 Crypto Engine <<
4 ============= 3 =============
5 4
6 Overview 5 Overview
7 -------- 6 --------
8 The crypto engine (CE) API is a crypto queue m !! 7 The crypto engine API (CE), is a crypto queue manager.
9 8
10 Requirement 9 Requirement
11 ----------- 10 -----------
12 You must put, at the start of your transform c !! 11 You have to put at start of your tfm_ctx the struct crypto_engine_ctx::
13 crypto_engine: <<
14 <<
15 :: <<
16 12
17 struct your_tfm_ctx { !! 13 struct your_tfm_ctx {
18 struct crypto_engine engine; !! 14 struct crypto_engine_ctx enginectx;
19 ... !! 15 ...
20 }; !! 16 };
21 !! 17
22 The crypto engine only manages asynchronous re !! 18 Why: Since CE manage only crypto_async_request, it cannot know the underlying
23 crypto_async_request. It cannot know the under !! 19 request_type and so have access only on the TFM.
24 has access to the transform structure. It is n !! 20 So using container_of for accessing __ctx is impossible.
25 using container_of. In addition, the engine kn !! 21 Furthermore, the crypto engine cannot know the "struct your_tfm_ctx",
26 structure "``struct your_tfm_ctx``". The engin !! 22 so it must assume that crypto_engine_ctx is at start of it.
27 of the known member ``struct crypto_engine`` a <<
28 23
29 Order of operations 24 Order of operations
30 ------------------- 25 -------------------
31 You are required to obtain a struct crypto_eng !! 26 You have to obtain a struct crypto_engine via crypto_engine_alloc_init().
32 Start it via ``crypto_engine_start()``. When f !! 27 And start it via crypto_engine_start().
33 engine using ``crypto_engine_stop()`` and dest <<
34 ``crypto_engine_exit()``. <<
35 <<
36 Before transferring any request, you have to f <<
37 providing functions for the following: <<
38 <<
39 * ``prepare_crypt_hardware``: Called once befo <<
40 called. <<
41 <<
42 * ``unprepare_crypt_hardware``: Called once af <<
43 been called. <<
44 <<
45 * ``prepare_cipher_request``/``prepare_hash_re <<
46 corresponding request is performed. If some <<
47 work is required, do it here. <<
48 <<
49 * ``unprepare_cipher_request``/``unprepare_has <<
50 request is handled. Clean up / undo what was <<
51 <<
52 * ``cipher_one_request``/``hash_one_request``: <<
53 performing the operation. <<
54 <<
55 Note that these functions access the crypto_as <<
56 associated with the received request. You are <<
57 request by using: <<
58 <<
59 :: <<
60 <<
61 container_of(areq, struct yourrequestt <<
62 <<
63 When your driver receives a crypto_request, yo <<
64 the crypto engine via one of: <<
65 <<
66 * crypto_transfer_aead_request_to_engine() <<
67 <<
68 * crypto_transfer_akcipher_request_to_engine() <<
69 <<
70 * crypto_transfer_hash_request_to_engine() <<
71 <<
72 * crypto_transfer_kpp_request_to_engine() <<
73 <<
74 * crypto_transfer_skcipher_request_to_engine() <<
75 <<
76 At the end of the request process, a call to o <<
77 <<
78 * crypto_finalize_aead_request() <<
79 <<
80 * crypto_finalize_akcipher_request() <<
81 <<
82 * crypto_finalize_hash_request() <<
83 <<
84 * crypto_finalize_kpp_request() <<
85 28
86 * crypto_finalize_skcipher_request() !! 29 Before transferring any request, you have to fill the enginectx.
>> 30 - prepare_request: (taking a function pointer) If you need to do some processing before doing the request
>> 31 - unprepare_request: (taking a function pointer) Undoing what's done in prepare_request
>> 32 - do_one_request: (taking a function pointer) Do encryption for current request
>> 33
>> 34 Note: that those three functions get the crypto_async_request associated with the received request.
>> 35 So your need to get the original request via container_of(areq, struct yourrequesttype_request, base);
>> 36
>> 37 When your driver receive a crypto_request, you have to transfer it to
>> 38 the cryptoengine via one of:
>> 39 - crypto_transfer_ablkcipher_request_to_engine()
>> 40 - crypto_transfer_aead_request_to_engine()
>> 41 - crypto_transfer_akcipher_request_to_engine()
>> 42 - crypto_transfer_hash_request_to_engine()
>> 43 - crypto_transfer_skcipher_request_to_engine()
>> 44
>> 45 At the end of the request process, a call to one of the following function is needed:
>> 46 - crypto_finalize_ablkcipher_request
>> 47 - crypto_finalize_aead_request
>> 48 - crypto_finalize_akcipher_request
>> 49 - crypto_finalize_hash_request
>> 50 - crypto_finalize_skcipher_request
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.