← Documents Documentation/crypto/api-intro.rst GitHub 원문 ↗

Linux 6.18.37 · Crypto

Scatterlist Cryptographic API

Scatterlist Crypto API의 page 기반 in-place 처리, transform과 algorithm layer, hash 사용 예제, context·alignment 규칙, 새 algorithm 제출 기준, bug 연락처와 개발 기여자를 설명합니다.

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

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

1. 요약·해설

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

요약과 해설

api-intro.rst:1-262

Scatterlist Crypto API는 page vector를 직접 처리하여 불필요한 linearization과 copy를 줄입니다. Transform layer가 state와 per-type logic을 감추고 algorithm layer가 구현 등록을 담당합니다.

Transform 할당과 `setkey`는 user context에서 수행하고 cryptographic method는 user 또는 softirq context에서 호출해야 합니다. Scatterlist segment를 block size 배수로 맞추면 fragment boundary copy를 피할 수 있습니다.

새 algorithm은 신뢰할 수 있는 test vector, recognized standard 또는 peer review, patent 검토가 필요합니다. 기존의 검증된 code를 활용하고 macro보다 inline function을 선호합니다.

문서 후반부는 API가 Cryptoapi와 Nettle에서 이어받은 부분, algorithm 원 개발자와 subsystem 기여자를 원문 순서대로 기록합니다.

2. 영어 원문 전체

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

원문 전체 펼치기
1 .. SPDX-License-Identifier: GPL-2.0
2
3 =============================
4 Scatterlist Cryptographic API
5 =============================
6
7 Introduction
8 ============
9
10 The Scatterlist Crypto API takes page vectors (scatterlists) as
11 arguments, and works directly on pages. In some cases (e.g. ECB
12 mode ciphers), this will allow for pages to be encrypted in-place
13 with no copying.
14
15 One of the initial goals of this design was to readily support IPsec,
16 so that processing can be applied to paged skb's without the need
17 for linearization.
18
19
20 Details
21 =======
22
23 At the lowest level are algorithms, which register dynamically with the
24 API.
25
26 'Transforms' are user-instantiated objects, which maintain state, handle all
27 of the implementation logic (e.g. manipulating page vectors) and provide an
28 abstraction to the underlying algorithms. However, at the user
29 level they are very simple.
30
31 Conceptually, the API layering looks like this::
32
33 [transform api] (user interface)
34 [transform ops] (per-type logic glue e.g. cipher.c, compress.c)
35 [algorithm api] (for registering algorithms)
36
37 The idea is to make the user interface and algorithm registration API
38 very simple, while hiding the core logic from both. Many good ideas
39 from existing APIs such as Cryptoapi and Nettle have been adapted for this.
40
41 The API currently supports five main types of transforms: AEAD (Authenticated
42 Encryption with Associated Data), Block Ciphers, Ciphers, Compressors and
43 Hashes.
44
45 Please note that Block Ciphers is somewhat of a misnomer. It is in fact
46 meant to support all ciphers including stream ciphers. The difference
47 between Block Ciphers and Ciphers is that the latter operates on exactly
48 one block while the former can operate on an arbitrary amount of data,
49 subject to block size requirements (i.e., non-stream ciphers can only
50 process multiples of blocks).
51
52 Here's an example of how to use the API::
53
54 #include <crypto/hash.h>
55 #include <linux/err.h>
56 #include <linux/scatterlist.h>
57
58 struct scatterlist sg[2];
59 char result[128];
60 struct crypto_ahash *tfm;
61 struct ahash_request *req;
62
63 tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
64 if (IS_ERR(tfm))
65 fail();
66
67 /* ... set up the scatterlists ... */
68
69 req = ahash_request_alloc(tfm, GFP_ATOMIC);
70 if (!req)
71 fail();
72
73 ahash_request_set_callback(req, 0, NULL, NULL);
74 ahash_request_set_crypt(req, sg, result, 2);
75
76 if (crypto_ahash_digest(req))
77 fail();
78
79 ahash_request_free(req);
80 crypto_free_ahash(tfm);
81
82
83 Many real examples are available in the regression test module (tcrypt.c).
84
85
86 Developer Notes
87 ===============
88
89 Transforms may only be allocated in user context, and cryptographic
90 methods may only be called from softirq and user contexts. For
91 transforms with a setkey method it too should only be called from
92 user context.
93
94 When using the API for ciphers, performance will be optimal if each
95 scatterlist contains data which is a multiple of the cipher's block
96 size (typically 8 bytes). This prevents having to do any copying
97 across non-aligned page fragment boundaries.
98
99
100 Adding New Algorithms
101 =====================
102
103 When submitting a new algorithm for inclusion, a mandatory requirement
104 is that at least a few test vectors from known sources (preferably
105 standards) be included.
106
107 Converting existing well known code is preferred, as it is more likely
108 to have been reviewed and widely tested. If submitting code from LGPL
109 sources, please consider changing the license to GPL (see section 3 of
110 the LGPL).
111
112 Algorithms submitted must also be generally patent-free (e.g. IDEA
113 will not be included in the mainline until around 2011), and be based
114 on a recognized standard and/or have been subjected to appropriate
115 peer review.
116
117 Also check for any RFCs which may relate to the use of specific algorithms,
118 as well as general application notes such as RFC2451 ("The ESP CBC-Mode
119 Cipher Algorithms").
120
121 It's a good idea to avoid using lots of macros and use inlined functions
122 instead, as gcc does a good job with inlining, while excessive use of
123 macros can cause compilation problems on some platforms.
124
125 Also check the TODO list at the web site listed below to see what people
126 might already be working on.
127
128
129 Bugs
130 ====
131
132 Send bug reports to:
134
135 Cc:
136 Herbert Xu <[email protected]>,
137 David S. Miller <[email protected]>
138
139
140 Further Information
141 ===================
142
143 For further patches and various updates, including the current TODO
144 list, see:
145 http://gondor.apana.org.au/~herbert/crypto/
146
147
148 Authors
149 =======
150
151 - James Morris
152 - David S. Miller
153 - Herbert Xu
154
155
156 Credits
157 =======
158
159 The following people provided invaluable feedback during the development
160 of the API:
161
162 - Alexey Kuznetzov
163 - Rusty Russell
164 - Herbert Valerio Riedel
165 - Jeff Garzik
166 - Michael Richardson
167 - Andrew Morton
168 - Ingo Oeser
169 - Christoph Hellwig
170
171 Portions of this API were derived from the following projects:
172
173 Kerneli Cryptoapi (http://www.kerneli.org/)
174 - Alexander Kjeldaas
175 - Herbert Valerio Riedel
176 - Kyle McMartin
177 - Jean-Luc Cooke
178 - David Bryson
179 - Clemens Fruhwirth
180 - Tobias Ringstrom
181 - Harald Welte
182
183 and;
184
185 Nettle (https://www.lysator.liu.se/~nisse/nettle/)
186 - Niels Möller
187
188 Original developers of the crypto algorithms:
189
190 - Dana L. How (DES)
191 - Andrew Tridgell and Steve French (MD4)
192 - Colin Plumb (MD5)
193 - Steve Reid (SHA1)
194 - Jean-Luc Cooke (SHA256, SHA384, SHA512)
195 - Kazunori Miyazawa / USAGI (HMAC)
196 - Matthew Skala (Twofish)
197 - Dag Arne Osvik (Serpent)
198 - Brian Gladman (AES)
199 - Kartikey Mahendra Bhatt (CAST6)
200 - Jon Oberheide (ARC4)
201 - Jouni Malinen (Michael MIC)
202 - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
203
204 SHA1 algorithm contributors:
205 - Jean-Francois Dive
206
207 DES algorithm contributors:
208 - Raimar Falke
209 - Gisle Sælensminde
210 - Niels Möller
211
212 Blowfish algorithm contributors:
213 - Herbert Valerio Riedel
214 - Kyle McMartin
215
216 Twofish algorithm contributors:
217 - Werner Koch
218 - Marc Mutz
219
220 SHA256/384/512 algorithm contributors:
221 - Andrew McDonald
222 - Kyle McMartin
223 - Herbert Valerio Riedel
224
225 AES algorithm contributors:
226 - Alexander Kjeldaas
227 - Herbert Valerio Riedel
228 - Kyle McMartin
229 - Adam J. Richter
230 - Fruhwirth Clemens (i586)
231 - Linus Torvalds (i586)
232
233 CAST5 algorithm contributors:
234 - Kartikey Mahendra Bhatt (original developers unknown, FSF copyright).
235
236 TEA/XTEA algorithm contributors:
237 - Aaron Grothe
238 - Michael Ringe
239
240 Khazad algorithm contributors:
241 - Aaron Grothe
242
243 Whirlpool algorithm contributors:
244 - Aaron Grothe
245 - Jean-Luc Cooke
246
247 Anubis algorithm contributors:
248 - Aaron Grothe
249
250 Tiger algorithm contributors:
251 - Aaron Grothe
252
253 VIA PadLock contributors:
254 - Michal Ludvig
255
256 Camellia algorithm contributors:
257 - NTT(Nippon Telegraph and Telephone Corporation) (Camellia)
258
259 Generic scatterwalk code by Adam J. Richter <[email protected]>
260
261 Please send any credits updates or corrections to:
262 Herbert Xu <[email protected]>
263

3. 한국어 전문 번역

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

Scatterlist Cryptographic API

1-19 
.. SPDX-License-Identifier: GPL-2.0

Scatterlist Cryptographic API

소개

Scatterlist Crypto API는 page vector인 scatterlist를 argument로 받아 page에서 직접 동작합니다. ECB mode cipher 같은 일부 경우에는 복사 없이 page를 in-place로 encrypt할 수 있습니다.

이 설계의 초기 목표 중 하나는 IPsec을 쉽게 지원하여 paged skb를 linearization하지 않고도 처리할 수 있게 하는 것이었습니다.

상세 구조와 사용 예제

20-85

상세

가장 낮은 level에는 API에 동적으로 등록되는 algorithm이 있습니다.

`Transform`은 사용자가 instance화한 object로서 state를 유지하고 page vector 조작 같은 구현 logic을 모두 처리하며 underlying algorithm을 추상화합니다. 하지만 사용자 level에서는 매우 단순합니다.

개념적인 API layering은 다음과 같습니다.

[transform api]  (user interface)
[transform ops]  (per-type logic glue e.g. cipher.c, compress.c)
[algorithm api]  (for registering algorithms)
Scatterlist Crypto API layering
transform API (user interface)transform ops (per-type logic)algorithm API (registration)

사용자 interface에서 type별 logic glue를 거쳐 algorithm registration layer로 내려가는 구조입니다.

사용자 interface와 algorithm registration API를 매우 단순하게 유지하면서 core logic을 양쪽에서 숨기는 것이 목표입니다. Cryptoapi와 Nettle 같은 기존 API의 좋은 아이디어를 많이 적용했습니다.

현재 API는 AEAD(Authenticated Encryption with Associated Data), Block Cipher, Cipher, Compressor, Hash의 다섯 가지 주요 transform type을 지원합니다.

Block Cipher라는 이름은 다소 부정확합니다. 실제로는 stream cipher를 포함한 모든 cipher를 지원하도록 설계되었습니다. Block Cipher와 Cipher의 차이는 후자가 정확히 block 하나에 동작하는 반면, 전자는 block size 요구사항 안에서 임의 양의 data를 처리할 수 있다는 점입니다. 즉 non-stream cipher는 block의 배수만 처리할 수 있습니다.

API 사용 예제:

#include <crypto/hash.h>
#include <linux/err.h>
#include <linux/scatterlist.h>

struct scatterlist sg[2];
char result[128];
struct crypto_ahash *tfm;
struct ahash_request *req;

tfm = crypto_alloc_ahash("md5", 0, CRYPTO_ALG_ASYNC);
if (IS_ERR(tfm))
        fail();

/* ... set up the scatterlists ... */

req = ahash_request_alloc(tfm, GFP_ATOMIC);
if (!req)
        fail();

ahash_request_set_callback(req, 0, NULL, NULL);
ahash_request_set_crypt(req, sg, result, 2);

if (crypto_ahash_digest(req))
        fail();

ahash_request_free(req);
crypto_free_ahash(tfm);

실제 예제는 regression test module인 `tcrypt.c`에서 많이 찾을 수 있습니다.

개발자 참고 사항

86-99

개발자 참고 사항

Transform은 user context에서만 할당할 수 있고 cryptographic method는 softirq와 user context에서만 호출할 수 있습니다. `setkey` method가 있는 transform의 해당 method도 user context에서만 호출해야 합니다.

Cipher API를 사용할 때 각 scatterlist가 cipher block size, 보통 8 byte의 배수인 data를 포함하면 성능이 최적입니다. 그러면 alignment가 맞지 않는 page fragment boundary를 가로질러 복사할 필요가 없습니다.

새 algorithm 추가

100-128

새 algorithm 추가

새 algorithm을 inclusion 대상으로 제출할 때는 알려진 출처, 가능하면 standard에서 가져온 test vector를 최소 몇 개 포함해야 합니다. 이는 필수 요구사항입니다.

기존의 잘 알려진 code를 변환하는 방식을 선호합니다. 이미 review되고 널리 test되었을 가능성이 높기 때문입니다. LGPL source의 code를 제출한다면 LGPL section 3을 참고하여 license를 GPL로 변경하는 것을 고려하십시오.

제출하는 algorithm은 일반적으로 patent-free여야 하며, 인정된 standard를 기반으로 하거나 적절한 peer review를 거쳐야 합니다. 원문은 IDEA가 약 2011년까지 mainline에 포함되지 않을 사례를 듭니다.

특정 algorithm 사용과 관련된 RFC뿐 아니라 RFC2451 `The ESP CBC-Mode Cipher Algorithms` 같은 일반 application note도 확인하십시오.

많은 macro를 사용하기보다 inline function을 사용하는 편이 좋습니다. GCC는 inlining을 잘 수행하지만 macro를 지나치게 사용하면 일부 platform에서 compilation 문제가 생길 수 있습니다.

아래 web site의 TODO list도 확인하여 다른 사람이 이미 작업 중인 항목이 있는지 살펴보십시오.

Bug 보고

129-139

Bug 보고

Bug report는 `[email protected]`로 보내십시오.

Cc: Herbert Xu <[email protected]>, David S. Miller <[email protected]>

추가 정보

140-147

추가 정보

현재 TODO list를 포함한 patch와 여러 update는 다음 위치를 참조하십시오.

저자

148-155

저자

  • James Morris
  • David S. Miller
  • Herbert Xu

API 개발 feedback

156-170

크레딧

다음 사람들은 API 개발 과정에서 매우 중요한 feedback을 제공했습니다.

  • Alexey Kuznetzov
  • Rusty Russell
  • Herbert Valerio Riedel
  • Jeff Garzik
  • Michael Richardson
  • Andrew Morton
  • Ingo Oeser
  • Christoph Hellwig

기반 project

171-187

이 API의 일부는 다음 project에서 유래했습니다.

Kerneli Cryptoapi 기여자:

  • Alexander Kjeldaas
  • Herbert Valerio Riedel
  • Kyle McMartin
  • Jean-Luc Cooke
  • David Bryson
  • Clemens Fruhwirth
  • Tobias Ringstrom
  • Harald Welte

Nettle 기여자:

  • Niels Möller

Crypto algorithm 원 개발자

188-203

Crypto algorithm의 원 개발자:

  • Dana L. How (DES)
  • Andrew Tridgell and Steve French (MD4)
  • Colin Plumb (MD5)
  • Steve Reid (SHA1)
  • Jean-Luc Cooke (SHA256, SHA384, SHA512)
  • Kazunori Miyazawa / USAGI (HMAC)
  • Matthew Skala (Twofish)
  • Dag Arne Osvik (Serpent)
  • Brian Gladman (AES)
  • Kartikey Mahendra Bhatt (CAST6)
  • Jon Oberheide (ARC4)
  • Jouni Malinen (Michael MIC)
  • NTT(Nippon Telegraph and Telephone Corporation) (Camellia)

Algorithm별 기여자

204-258

SHA1 algorithm 기여자:

  • Jean-Francois Dive

DES algorithm 기여자:

  • Raimar Falke
  • Gisle Sælensminde
  • Niels Möller

Blowfish algorithm 기여자:

  • Herbert Valerio Riedel
  • Kyle McMartin

Twofish algorithm 기여자:

  • Werner Koch
  • Marc Mutz

SHA256/384/512 algorithm 기여자:

  • Andrew McDonald
  • Kyle McMartin
  • Herbert Valerio Riedel

AES algorithm 기여자:

  • Alexander Kjeldaas
  • Herbert Valerio Riedel
  • Kyle McMartin
  • Adam J. Richter
  • Fruhwirth Clemens (i586)
  • Linus Torvalds (i586)

CAST5 algorithm 기여자:

  • Kartikey Mahendra Bhatt (original developers unknown, FSF copyright)

TEA/XTEA algorithm 기여자:

  • Aaron Grothe
  • Michael Ringe

Khazad algorithm 기여자:

  • Aaron Grothe

Whirlpool algorithm 기여자:

  • Aaron Grothe
  • Jean-Luc Cooke

Anubis algorithm 기여자:

  • Aaron Grothe

Tiger algorithm 기여자:

  • Aaron Grothe

VIA PadLock 기여자:

  • Michal Ludvig

Camellia algorithm 기여자:

  • NTT(Nippon Telegraph and Telephone Corporation) (Camellia)

추가 credit 연락처

259-262

Generic scatterwalk code는 Adam J. Richter <[email protected]>가 작성했습니다.

Credit update나 correction은 Herbert Xu <[email protected]>에게 보내십시오.