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