1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 Crypto Engine 3 Crypto Engine
4 ============= 4 =============
5 5
6 Overview 6 Overview
7 -------- 7 --------
8 The crypto engine (CE) API is a crypto queue m 8 The crypto engine (CE) API is a crypto queue manager.
9 9
10 Requirement 10 Requirement
11 ----------- 11 -----------
12 You must put, at the start of your transform c 12 You must put, at the start of your transform context your_tfm_ctx, the structure
13 crypto_engine: 13 crypto_engine:
14 14
15 :: 15 ::
16 16
17 struct your_tfm_ctx { 17 struct your_tfm_ctx {
18 struct crypto_engine engine; 18 struct crypto_engine engine;
19 ... 19 ...
20 }; 20 };
21 21
22 The crypto engine only manages asynchronous re 22 The crypto engine only manages asynchronous requests in the form of
23 crypto_async_request. It cannot know the under 23 crypto_async_request. It cannot know the underlying request type and thus only
24 has access to the transform structure. It is n 24 has access to the transform structure. It is not possible to access the context
25 using container_of. In addition, the engine kn 25 using container_of. In addition, the engine knows nothing about your
26 structure "``struct your_tfm_ctx``". The engin 26 structure "``struct your_tfm_ctx``". The engine assumes (requires) the placement
27 of the known member ``struct crypto_engine`` a 27 of the known member ``struct crypto_engine`` at the beginning.
28 28
29 Order of operations 29 Order of operations
30 ------------------- 30 -------------------
31 You are required to obtain a struct crypto_eng 31 You are required to obtain a struct crypto_engine via ``crypto_engine_alloc_init()``.
32 Start it via ``crypto_engine_start()``. When f 32 Start it via ``crypto_engine_start()``. When finished with your work, shut down the
33 engine using ``crypto_engine_stop()`` and dest 33 engine using ``crypto_engine_stop()`` and destroy the engine with
34 ``crypto_engine_exit()``. 34 ``crypto_engine_exit()``.
35 35
36 Before transferring any request, you have to f 36 Before transferring any request, you have to fill the context enginectx by
37 providing functions for the following: 37 providing functions for the following:
38 38
39 * ``prepare_crypt_hardware``: Called once befo 39 * ``prepare_crypt_hardware``: Called once before any prepare functions are
40 called. 40 called.
41 41
42 * ``unprepare_crypt_hardware``: Called once af 42 * ``unprepare_crypt_hardware``: Called once after all unprepare functions have
43 been called. 43 been called.
44 44
45 * ``prepare_cipher_request``/``prepare_hash_re 45 * ``prepare_cipher_request``/``prepare_hash_request``: Called before each
46 corresponding request is performed. If some 46 corresponding request is performed. If some processing or other preparatory
47 work is required, do it here. 47 work is required, do it here.
48 48
49 * ``unprepare_cipher_request``/``unprepare_has 49 * ``unprepare_cipher_request``/``unprepare_hash_request``: Called after each
50 request is handled. Clean up / undo what was 50 request is handled. Clean up / undo what was done in the prepare function.
51 51
52 * ``cipher_one_request``/``hash_one_request``: 52 * ``cipher_one_request``/``hash_one_request``: Handle the current request by
53 performing the operation. 53 performing the operation.
54 54
55 Note that these functions access the crypto_as 55 Note that these functions access the crypto_async_request structure
56 associated with the received request. You are 56 associated with the received request. You are able to retrieve the original
57 request by using: 57 request by using:
58 58
59 :: 59 ::
60 60
61 container_of(areq, struct yourrequestt 61 container_of(areq, struct yourrequesttype_request, base);
62 62
63 When your driver receives a crypto_request, yo 63 When your driver receives a crypto_request, you must to transfer it to
64 the crypto engine via one of: 64 the crypto engine via one of:
65 65
66 * crypto_transfer_aead_request_to_engine() 66 * crypto_transfer_aead_request_to_engine()
67 67
68 * crypto_transfer_akcipher_request_to_engine() 68 * crypto_transfer_akcipher_request_to_engine()
69 69
70 * crypto_transfer_hash_request_to_engine() 70 * crypto_transfer_hash_request_to_engine()
71 71
72 * crypto_transfer_kpp_request_to_engine() <<
73 <<
74 * crypto_transfer_skcipher_request_to_engine() 72 * crypto_transfer_skcipher_request_to_engine()
75 73
76 At the end of the request process, a call to o 74 At the end of the request process, a call to one of the following functions is needed:
77 75
78 * crypto_finalize_aead_request() 76 * crypto_finalize_aead_request()
79 77
80 * crypto_finalize_akcipher_request() 78 * crypto_finalize_akcipher_request()
81 79
82 * crypto_finalize_hash_request() 80 * crypto_finalize_hash_request()
83 <<
84 * crypto_finalize_kpp_request() <<
85 81
86 * crypto_finalize_skcipher_request() 82 * 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.