| 1 | |
| 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()
|