← Documents Documentation/crypto/crypto_engine.rst GitHub 원문 ↗

Linux 6.18.37 · Crypto

Crypto Engine

Crypto Engine queue 관리자의 transform context 배치 규칙, 수명 주기, prepare·unprepare·실행 callback, request 전달 및 완료 API를 설명합니다.

Source pathDocumentation/crypto/crypto_engine.rst
Source versionLinux v6.18.37
TranslationDUJINLABS 전문 번역 + 해설

요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.

1. 요약·해설

원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.

요약과 해설

crypto_engine.rst:1-80

Crypto Engine은 여러 비동기 암호 request type을 공통 queue에서 관리합니다. Engine이 구체적인 context type을 모르므로 `struct crypto_engine`을 transform context의 첫 member로 두는 layout 계약이 핵심입니다.

Driver는 engine 할당·시작·정지·폐기 수명 주기를 지키고, request 종류별 prepare·실행·unprepare callback을 제공해야 합니다. 받은 request는 종류별 `crypto_transfer_*_request_to_engine()`으로 넘기고 처리 후 대응하는 `crypto_finalize_*_request()`로 완료합니다.

2. 영어 원문 전체

번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.

원문 전체 펼치기
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()
81

3. 한국어 전문 번역

영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.

Crypto Engine

1-5

SPDX 라이선스 식별자: `GPL-2.0`

Crypto Engine

개요

6-9

개요

Crypto Engine(CE) API는 암호 request queue 관리자입니다.

요구 사항

10-28

요구 사항

Transform context인 `your_tfm_ctx`의 시작 위치에 `crypto_engine` 구조체를 배치해야 합니다.

::

        struct your_tfm_ctx {
                struct crypto_engine engine;
                ...
        };

Crypto Engine은 `crypto_async_request` 형식의 비동기 request만 관리합니다. 기반 request type을 알 수 없으므로 transform 구조체에만 접근할 수 있으며 `container_of`로 context에 접근할 수 없습니다.

또한 engine은 `struct your_tfm_ctx`의 구조를 알지 못합니다. 따라서 알려진 member인 `struct crypto_engine`이 context의 맨 앞에 있다고 가정하며 이를 필수로 요구합니다.

연산 순서

29-80

연산 순서

`crypto_engine_alloc_init()`으로 `struct crypto_engine`을 얻고 `crypto_engine_start()`로 시작해야 합니다. 작업이 끝나면 `crypto_engine_stop()`으로 engine을 정지하고 `crypto_engine_exit()`으로 폐기합니다.

Request를 전달하기 전에 다음 함수를 제공하여 context `enginectx`를 채워야 합니다.

  • `prepare_cipher_request` / `prepare_hash_request`: 해당 request를 수행하기 전에 호출됩니다. 처리나 다른 준비 작업이 필요하면 여기서 수행합니다.
  • `unprepare_cipher_request` / `unprepare_hash_request`: 각 request를 처리한 뒤 호출됩니다. Prepare 함수에서 수행한 작업을 정리하거나 되돌립니다.
  • `cipher_one_request` / `hash_one_request`: 실제 연산을 수행하여 현재 request를 처리합니다.

이 함수들은 받은 request에 연결된 `crypto_async_request` 구조체에 접근합니다. 다음과 같이 원래 request를 가져올 수 있습니다.

::

        container_of(areq, struct yourrequesttype_request, base);

Driver가 `crypto_request`를 받으면 다음 함수 중 하나로 Crypto Engine에 전달해야 합니다.

  • `crypto_transfer_aead_request_to_engine()`
  • `crypto_transfer_akcipher_request_to_engine()`
  • `crypto_transfer_hash_request_to_engine()`
  • `crypto_transfer_kpp_request_to_engine()`
  • `crypto_transfer_skcipher_request_to_engine()`

Request 처리 마지막에는 다음 함수 중 하나를 호출하여 완료를 알릴 필요가 있습니다.

  • `crypto_finalize_aead_request()`
  • `crypto_finalize_akcipher_request()`
  • `crypto_finalize_hash_request()`
  • `crypto_finalize_kpp_request()`
  • `crypto_finalize_skcipher_request()`