1ae400be9SHook, Gary.. SPDX-License-Identifier: GPL-2.0 25d2ded28SJonathan Neuschäfer 3ae400be9SHook, GaryCrypto Engine 4ce09a6c0SCorentin LABBE============= 5ce09a6c0SCorentin LABBE 6ce09a6c0SCorentin LABBEOverview 7ce09a6c0SCorentin LABBE-------- 8ae400be9SHook, GaryThe crypto engine (CE) API is a crypto queue manager. 9ce09a6c0SCorentin LABBE 10ce09a6c0SCorentin LABBERequirement 11ce09a6c0SCorentin LABBE----------- 12ae400be9SHook, GaryYou must put, at the start of your transform context your_tfm_ctx, the structure 13ae400be9SHook, Garycrypto_engine: 14ae400be9SHook, Gary 15ae400be9SHook, Gary:: 162fab3019SMauro Carvalho Chehab 17ce09a6c0SCorentin LABBE struct your_tfm_ctx { 18ae400be9SHook, Gary struct crypto_engine engine; 19ce09a6c0SCorentin LABBE ... 20ce09a6c0SCorentin LABBE }; 212fab3019SMauro Carvalho Chehab 22ae400be9SHook, GaryThe crypto engine only manages asynchronous requests in the form of 23ae400be9SHook, Garycrypto_async_request. It cannot know the underlying request type and thus only 24ae400be9SHook, Garyhas access to the transform structure. It is not possible to access the context 25ae400be9SHook, Garyusing container_of. In addition, the engine knows nothing about your 26ae400be9SHook, Garystructure "``struct your_tfm_ctx``". The engine assumes (requires) the placement 27ae400be9SHook, Garyof the known member ``struct crypto_engine`` at the beginning. 28ce09a6c0SCorentin LABBE 29ce09a6c0SCorentin LABBEOrder of operations 30ce09a6c0SCorentin LABBE------------------- 31ae400be9SHook, GaryYou are required to obtain a struct crypto_engine via ``crypto_engine_alloc_init()``. 32ae400be9SHook, GaryStart it via ``crypto_engine_start()``. When finished with your work, shut down the 33ae400be9SHook, Garyengine using ``crypto_engine_stop()`` and destroy the engine with 34ae400be9SHook, Gary``crypto_engine_exit()``. 35ce09a6c0SCorentin LABBE 36ae400be9SHook, GaryBefore transferring any request, you have to fill the context enginectx by 37ae400be9SHook, Garyproviding functions for the following: 38ce09a6c0SCorentin LABBE 39ae400be9SHook, Gary* ``prepare_crypt_hardware``: Called once before any prepare functions are 40ae400be9SHook, Gary called. 41ce09a6c0SCorentin LABBE 42ae400be9SHook, Gary* ``unprepare_crypt_hardware``: Called once after all unprepare functions have 43ae400be9SHook, Gary been called. 44ae400be9SHook, Gary 45ae400be9SHook, Gary* ``prepare_cipher_request``/``prepare_hash_request``: Called before each 46ae400be9SHook, Gary corresponding request is performed. If some processing or other preparatory 47ae400be9SHook, Gary work is required, do it here. 48ae400be9SHook, Gary 49ae400be9SHook, Gary* ``unprepare_cipher_request``/``unprepare_hash_request``: Called after each 50ae400be9SHook, Gary request is handled. Clean up / undo what was done in the prepare function. 51ae400be9SHook, Gary 52ae400be9SHook, Gary* ``cipher_one_request``/``hash_one_request``: Handle the current request by 53ae400be9SHook, Gary performing the operation. 54ae400be9SHook, Gary 55ae400be9SHook, GaryNote that these functions access the crypto_async_request structure 56ae400be9SHook, Garyassociated with the received request. You are able to retrieve the original 57ae400be9SHook, Garyrequest by using: 58ae400be9SHook, Gary 59ae400be9SHook, Gary:: 60ae400be9SHook, Gary 61ae400be9SHook, Gary container_of(areq, struct yourrequesttype_request, base); 62ae400be9SHook, Gary 63ae400be9SHook, GaryWhen your driver receives a crypto_request, you must to transfer it to 64ce09a6c0SCorentin LABBEthe crypto engine via one of: 65ce09a6c0SCorentin LABBE 66ae400be9SHook, Gary* crypto_transfer_aead_request_to_engine() 67ae400be9SHook, Gary 68ae400be9SHook, Gary* crypto_transfer_akcipher_request_to_engine() 69ae400be9SHook, Gary 70ae400be9SHook, Gary* crypto_transfer_hash_request_to_engine() 71ae400be9SHook, Gary 72*1730c5aaSPrabhjot Khurana* crypto_transfer_kpp_request_to_engine() 73*1730c5aaSPrabhjot Khurana 74ae400be9SHook, Gary* crypto_transfer_skcipher_request_to_engine() 75ae400be9SHook, Gary 76ae400be9SHook, GaryAt the end of the request process, a call to one of the following functions is needed: 77ae400be9SHook, Gary 78ae400be9SHook, Gary* crypto_finalize_aead_request() 79ae400be9SHook, Gary 80ae400be9SHook, Gary* crypto_finalize_akcipher_request() 81ae400be9SHook, Gary 82ae400be9SHook, Gary* crypto_finalize_hash_request() 83ae400be9SHook, Gary 84*1730c5aaSPrabhjot Khurana* crypto_finalize_kpp_request() 85*1730c5aaSPrabhjot Khurana 86ae400be9SHook, Gary* crypto_finalize_skcipher_request() 87