]>
Commit | Line | Data |
---|---|---|
7d12993e SM |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | |
4 | ||
5 | <book id="KernelCryptoAPI"> | |
6 | <bookinfo> | |
7 | <title>Linux Kernel Crypto API</title> | |
8 | ||
9 | <authorgroup> | |
10 | <author> | |
11 | <firstname>Stephan</firstname> | |
12 | <surname>Mueller</surname> | |
13 | <affiliation> | |
14 | <address> | |
15 | <email>smueller@chronox.de</email> | |
16 | </address> | |
17 | </affiliation> | |
18 | </author> | |
19 | <author> | |
20 | <firstname>Marek</firstname> | |
21 | <surname>Vasut</surname> | |
22 | <affiliation> | |
23 | <address> | |
24 | <email>marek@denx.de</email> | |
25 | </address> | |
26 | </affiliation> | |
27 | </author> | |
28 | </authorgroup> | |
29 | ||
30 | <copyright> | |
31 | <year>2014</year> | |
32 | <holder>Stephan Mueller</holder> | |
33 | </copyright> | |
34 | ||
35 | ||
36 | <legalnotice> | |
37 | <para> | |
38 | This documentation is free software; you can redistribute | |
39 | it and/or modify it under the terms of the GNU General Public | |
40 | License as published by the Free Software Foundation; either | |
41 | version 2 of the License, or (at your option) any later | |
42 | version. | |
43 | </para> | |
44 | ||
45 | <para> | |
46 | This program is distributed in the hope that it will be | |
47 | useful, but WITHOUT ANY WARRANTY; without even the implied | |
48 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
49 | See the GNU General Public License for more details. | |
50 | </para> | |
51 | ||
52 | <para> | |
53 | You should have received a copy of the GNU General Public | |
54 | License along with this program; if not, write to the Free | |
55 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, | |
56 | MA 02111-1307 USA | |
57 | </para> | |
58 | ||
59 | <para> | |
60 | For more details see the file COPYING in the source | |
61 | distribution of Linux. | |
62 | </para> | |
63 | </legalnotice> | |
64 | </bookinfo> | |
65 | ||
66 | <toc></toc> | |
67 | ||
68 | <chapter id="Intro"> | |
69 | <title>Kernel Crypto API Interface Specification</title> | |
70 | ||
71 | <sect1><title>Introduction</title> | |
72 | ||
73 | <para> | |
74 | The kernel crypto API offers a rich set of cryptographic ciphers as | |
75 | well as other data transformation mechanisms and methods to invoke | |
76 | these. This document contains a description of the API and provides | |
77 | example code. | |
78 | </para> | |
79 | ||
80 | <para> | |
81 | To understand and properly use the kernel crypto API a brief | |
82 | explanation of its structure is given. Based on the architecture, | |
83 | the API can be separated into different components. Following the | |
84 | architecture specification, hints to developers of ciphers are | |
85 | provided. Pointers to the API function call documentation are | |
86 | given at the end. | |
87 | </para> | |
88 | ||
89 | <para> | |
90 | The kernel crypto API refers to all algorithms as "transformations". | |
91 | Therefore, a cipher handle variable usually has the name "tfm". | |
92 | Besides cryptographic operations, the kernel crypto API also knows | |
93 | compression transformations and handles them the same way as ciphers. | |
94 | </para> | |
95 | ||
96 | <para> | |
97 | The kernel crypto API serves the following entity types: | |
98 | ||
99 | <itemizedlist> | |
100 | <listitem> | |
101 | <para>consumers requesting cryptographic services</para> | |
102 | </listitem> | |
103 | <listitem> | |
104 | <para>data transformation implementations (typically ciphers) | |
105 | that can be called by consumers using the kernel crypto | |
106 | API</para> | |
107 | </listitem> | |
108 | </itemizedlist> | |
109 | </para> | |
110 | ||
111 | <para> | |
112 | This specification is intended for consumers of the kernel crypto | |
113 | API as well as for developers implementing ciphers. This API | |
f309f165 | 114 | specification, however, does not discuss all API calls available |
7d12993e SM |
115 | to data transformation implementations (i.e. implementations of |
116 | ciphers and other transformations (such as CRC or even compression | |
117 | algorithms) that can register with the kernel crypto API). | |
118 | </para> | |
119 | ||
120 | <para> | |
121 | Note: The terms "transformation" and cipher algorithm are used | |
6b212f0f | 122 | interchangeably. |
7d12993e SM |
123 | </para> |
124 | </sect1> | |
125 | ||
126 | <sect1><title>Terminology</title> | |
127 | <para> | |
128 | The transformation implementation is an actual code or interface | |
129 | to hardware which implements a certain transformation with precisely | |
130 | defined behavior. | |
131 | </para> | |
132 | ||
133 | <para> | |
134 | The transformation object (TFM) is an instance of a transformation | |
135 | implementation. There can be multiple transformation objects | |
136 | associated with a single transformation implementation. Each of | |
137 | those transformation objects is held by a crypto API consumer or | |
138 | another transformation. Transformation object is allocated when a | |
139 | crypto API consumer requests a transformation implementation. | |
140 | The consumer is then provided with a structure, which contains | |
141 | a transformation object (TFM). | |
142 | </para> | |
143 | ||
144 | <para> | |
145 | The structure that contains transformation objects may also be | |
146 | referred to as a "cipher handle". Such a cipher handle is always | |
147 | subject to the following phases that are reflected in the API calls | |
148 | applicable to such a cipher handle: | |
149 | </para> | |
150 | ||
151 | <orderedlist> | |
152 | <listitem> | |
153 | <para>Initialization of a cipher handle.</para> | |
154 | </listitem> | |
155 | <listitem> | |
156 | <para>Execution of all intended cipher operations applicable | |
157 | for the handle where the cipher handle must be furnished to | |
158 | every API call.</para> | |
159 | </listitem> | |
160 | <listitem> | |
161 | <para>Destruction of a cipher handle.</para> | |
162 | </listitem> | |
163 | </orderedlist> | |
164 | ||
165 | <para> | |
166 | When using the initialization API calls, a cipher handle is | |
167 | created and returned to the consumer. Therefore, please refer | |
168 | to all initialization API calls that refer to the data | |
169 | structure type a consumer is expected to receive and subsequently | |
170 | to use. The initialization API calls have all the same naming | |
171 | conventions of crypto_alloc_*. | |
172 | </para> | |
173 | ||
174 | <para> | |
175 | The transformation context is private data associated with | |
176 | the transformation object. | |
177 | </para> | |
178 | </sect1> | |
179 | </chapter> | |
180 | ||
181 | <chapter id="Architecture"><title>Kernel Crypto API Architecture</title> | |
182 | <sect1><title>Cipher algorithm types</title> | |
183 | <para> | |
184 | The kernel crypto API provides different API calls for the | |
185 | following cipher types: | |
186 | ||
187 | <itemizedlist> | |
188 | <listitem><para>Symmetric ciphers</para></listitem> | |
189 | <listitem><para>AEAD ciphers</para></listitem> | |
190 | <listitem><para>Message digest, including keyed message digest</para></listitem> | |
191 | <listitem><para>Random number generation</para></listitem> | |
192 | <listitem><para>User space interface</para></listitem> | |
193 | </itemizedlist> | |
194 | </para> | |
195 | </sect1> | |
196 | ||
197 | <sect1><title>Ciphers And Templates</title> | |
198 | <para> | |
199 | The kernel crypto API provides implementations of single block | |
200 | ciphers and message digests. In addition, the kernel crypto API | |
201 | provides numerous "templates" that can be used in conjunction | |
202 | with the single block ciphers and message digests. Templates | |
203 | include all types of block chaining mode, the HMAC mechanism, etc. | |
204 | </para> | |
205 | ||
206 | <para> | |
207 | Single block ciphers and message digests can either be directly | |
208 | used by a caller or invoked together with a template to form | |
209 | multi-block ciphers or keyed message digests. | |
210 | </para> | |
211 | ||
212 | <para> | |
213 | A single block cipher may even be called with multiple templates. | |
214 | However, templates cannot be used without a single cipher. | |
215 | </para> | |
216 | ||
217 | <para> | |
218 | See /proc/crypto and search for "name". For example: | |
219 | ||
220 | <itemizedlist> | |
221 | <listitem><para>aes</para></listitem> | |
222 | <listitem><para>ecb(aes)</para></listitem> | |
223 | <listitem><para>cmac(aes)</para></listitem> | |
224 | <listitem><para>ccm(aes)</para></listitem> | |
225 | <listitem><para>rfc4106(gcm(aes))</para></listitem> | |
226 | <listitem><para>sha1</para></listitem> | |
227 | <listitem><para>hmac(sha1)</para></listitem> | |
228 | <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem> | |
229 | </itemizedlist> | |
230 | </para> | |
231 | ||
232 | <para> | |
233 | In these examples, "aes" and "sha1" are the ciphers and all | |
234 | others are the templates. | |
235 | </para> | |
236 | </sect1> | |
237 | ||
238 | <sect1><title>Synchronous And Asynchronous Operation</title> | |
239 | <para> | |
240 | The kernel crypto API provides synchronous and asynchronous | |
241 | API operations. | |
242 | </para> | |
243 | ||
244 | <para> | |
245 | When using the synchronous API operation, the caller invokes | |
246 | a cipher operation which is performed synchronously by the | |
247 | kernel crypto API. That means, the caller waits until the | |
248 | cipher operation completes. Therefore, the kernel crypto API | |
249 | calls work like regular function calls. For synchronous | |
250 | operation, the set of API calls is small and conceptually | |
251 | similar to any other crypto library. | |
252 | </para> | |
253 | ||
254 | <para> | |
255 | Asynchronous operation is provided by the kernel crypto API | |
256 | which implies that the invocation of a cipher operation will | |
257 | complete almost instantly. That invocation triggers the | |
258 | cipher operation but it does not signal its completion. Before | |
259 | invoking a cipher operation, the caller must provide a callback | |
260 | function the kernel crypto API can invoke to signal the | |
261 | completion of the cipher operation. Furthermore, the caller | |
262 | must ensure it can handle such asynchronous events by applying | |
263 | appropriate locking around its data. The kernel crypto API | |
264 | does not perform any special serialization operation to protect | |
265 | the caller's data integrity. | |
266 | </para> | |
267 | </sect1> | |
268 | ||
269 | <sect1><title>Crypto API Cipher References And Priority</title> | |
270 | <para> | |
271 | A cipher is referenced by the caller with a string. That string | |
272 | has the following semantics: | |
273 | ||
274 | <programlisting> | |
275 | template(single block cipher) | |
276 | </programlisting> | |
277 | ||
278 | where "template" and "single block cipher" is the aforementioned | |
279 | template and single block cipher, respectively. If applicable, | |
280 | additional templates may enclose other templates, such as | |
281 | ||
282 | <programlisting> | |
283 | template1(template2(single block cipher))) | |
284 | </programlisting> | |
285 | </para> | |
286 | ||
287 | <para> | |
288 | The kernel crypto API may provide multiple implementations of a | |
289 | template or a single block cipher. For example, AES on newer | |
290 | Intel hardware has the following implementations: AES-NI, | |
291 | assembler implementation, or straight C. Now, when using the | |
292 | string "aes" with the kernel crypto API, which cipher | |
293 | implementation is used? The answer to that question is the | |
294 | priority number assigned to each cipher implementation by the | |
295 | kernel crypto API. When a caller uses the string to refer to a | |
296 | cipher during initialization of a cipher handle, the kernel | |
297 | crypto API looks up all implementations providing an | |
298 | implementation with that name and selects the implementation | |
299 | with the highest priority. | |
300 | </para> | |
301 | ||
302 | <para> | |
303 | Now, a caller may have the need to refer to a specific cipher | |
304 | implementation and thus does not want to rely on the | |
305 | priority-based selection. To accommodate this scenario, the | |
306 | kernel crypto API allows the cipher implementation to register | |
307 | a unique name in addition to common names. When using that | |
308 | unique name, a caller is therefore always sure to refer to | |
309 | the intended cipher implementation. | |
310 | </para> | |
311 | ||
312 | <para> | |
313 | The list of available ciphers is given in /proc/crypto. However, | |
314 | that list does not specify all possible permutations of | |
315 | templates and ciphers. Each block listed in /proc/crypto may | |
316 | contain the following information -- if one of the components | |
317 | listed as follows are not applicable to a cipher, it is not | |
318 | displayed: | |
319 | </para> | |
320 | ||
321 | <itemizedlist> | |
322 | <listitem> | |
323 | <para>name: the generic name of the cipher that is subject | |
324 | to the priority-based selection -- this name can be used by | |
325 | the cipher allocation API calls (all names listed above are | |
326 | examples for such generic names)</para> | |
327 | </listitem> | |
328 | <listitem> | |
329 | <para>driver: the unique name of the cipher -- this name can | |
330 | be used by the cipher allocation API calls</para> | |
331 | </listitem> | |
332 | <listitem> | |
333 | <para>module: the kernel module providing the cipher | |
334 | implementation (or "kernel" for statically linked ciphers)</para> | |
335 | </listitem> | |
336 | <listitem> | |
337 | <para>priority: the priority value of the cipher implementation</para> | |
338 | </listitem> | |
339 | <listitem> | |
340 | <para>refcnt: the reference count of the respective cipher | |
341 | (i.e. the number of current consumers of this cipher)</para> | |
342 | </listitem> | |
343 | <listitem> | |
344 | <para>selftest: specification whether the self test for the | |
345 | cipher passed</para> | |
346 | </listitem> | |
347 | <listitem> | |
348 | <para>type: | |
349 | <itemizedlist> | |
350 | <listitem> | |
ba871e1d | 351 | <para>skcipher for symmetric key ciphers</para> |
7d12993e SM |
352 | </listitem> |
353 | <listitem> | |
354 | <para>cipher for single block ciphers that may be used with | |
355 | an additional template</para> | |
356 | </listitem> | |
357 | <listitem> | |
358 | <para>shash for synchronous message digest</para> | |
359 | </listitem> | |
360 | <listitem> | |
361 | <para>ahash for asynchronous message digest</para> | |
362 | </listitem> | |
363 | <listitem> | |
364 | <para>aead for AEAD cipher type</para> | |
365 | </listitem> | |
366 | <listitem> | |
367 | <para>compression for compression type transformations</para> | |
368 | </listitem> | |
369 | <listitem> | |
370 | <para>rng for random number generator</para> | |
371 | </listitem> | |
372 | <listitem> | |
373 | <para>givcipher for cipher with associated IV generator | |
374 | (see the geniv entry below for the specification of the | |
375 | IV generator type used by the cipher implementation)</para> | |
376 | </listitem> | |
377 | </itemizedlist> | |
378 | </para> | |
379 | </listitem> | |
380 | <listitem> | |
381 | <para>blocksize: blocksize of cipher in bytes</para> | |
382 | </listitem> | |
383 | <listitem> | |
384 | <para>keysize: key size in bytes</para> | |
385 | </listitem> | |
386 | <listitem> | |
387 | <para>ivsize: IV size in bytes</para> | |
388 | </listitem> | |
389 | <listitem> | |
390 | <para>seedsize: required size of seed data for random number | |
391 | generator</para> | |
392 | </listitem> | |
393 | <listitem> | |
394 | <para>digestsize: output size of the message digest</para> | |
395 | </listitem> | |
396 | <listitem> | |
397 | <para>geniv: IV generation type: | |
398 | <itemizedlist> | |
399 | <listitem> | |
400 | <para>eseqiv for encrypted sequence number based IV | |
401 | generation</para> | |
402 | </listitem> | |
403 | <listitem> | |
404 | <para>seqiv for sequence number based IV generation</para> | |
405 | </listitem> | |
406 | <listitem> | |
407 | <para>chainiv for chain iv generation</para> | |
408 | </listitem> | |
409 | <listitem> | |
410 | <para><builtin> is a marker that the cipher implements | |
411 | IV generation and handling as it is specific to the given | |
412 | cipher</para> | |
413 | </listitem> | |
414 | </itemizedlist> | |
415 | </para> | |
416 | </listitem> | |
417 | </itemizedlist> | |
418 | </sect1> | |
419 | ||
420 | <sect1><title>Key Sizes</title> | |
421 | <para> | |
422 | When allocating a cipher handle, the caller only specifies the | |
423 | cipher type. Symmetric ciphers, however, typically support | |
424 | multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256). | |
425 | These key sizes are determined with the length of the provided | |
426 | key. Thus, the kernel crypto API does not provide a separate | |
427 | way to select the particular symmetric cipher key size. | |
428 | </para> | |
429 | </sect1> | |
430 | ||
431 | <sect1><title>Cipher Allocation Type And Masks</title> | |
432 | <para> | |
433 | The different cipher handle allocation functions allow the | |
434 | specification of a type and mask flag. Both parameters have | |
435 | the following meaning (and are therefore not covered in the | |
436 | subsequent sections). | |
437 | </para> | |
438 | ||
439 | <para> | |
440 | The type flag specifies the type of the cipher algorithm. | |
441 | The caller usually provides a 0 when the caller wants the | |
442 | default handling. Otherwise, the caller may provide the | |
443 | following selections which match the the aforementioned | |
444 | cipher types: | |
445 | </para> | |
446 | ||
447 | <itemizedlist> | |
448 | <listitem> | |
449 | <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para> | |
450 | </listitem> | |
451 | <listitem> | |
452 | <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para> | |
453 | </listitem> | |
454 | <listitem> | |
455 | <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with | |
456 | Associated Data (MAC)</para> | |
457 | </listitem> | |
458 | <listitem> | |
459 | <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para> | |
460 | </listitem> | |
461 | <listitem> | |
462 | <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para> | |
463 | </listitem> | |
464 | <listitem> | |
465 | <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block | |
466 | cipher packed together with an IV generator (see geniv field | |
467 | in the /proc/crypto listing for the known IV generators)</para> | |
468 | </listitem> | |
469 | <listitem> | |
470 | <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para> | |
471 | </listitem> | |
472 | <listitem> | |
473 | <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para> | |
474 | </listitem> | |
475 | <listitem> | |
476 | <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para> | |
477 | </listitem> | |
478 | <listitem> | |
479 | <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para> | |
480 | </listitem> | |
481 | <listitem> | |
482 | <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> | |
483 | </listitem> | |
e1eabc05 SM |
484 | <listitem> |
485 | <para>CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher</para> | |
486 | </listitem> | |
7d12993e SM |
487 | <listitem> |
488 | <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of | |
489 | CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / | |
490 | decompression instead of performing the operation on one | |
491 | segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace | |
492 | CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para> | |
493 | </listitem> | |
494 | </itemizedlist> | |
495 | ||
496 | <para> | |
497 | The mask flag restricts the type of cipher. The only allowed | |
498 | flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function | |
499 | to asynchronous ciphers. Usually, a caller provides a 0 for the | |
500 | mask flag. | |
501 | </para> | |
502 | ||
503 | <para> | |
504 | When the caller provides a mask and type specification, the | |
505 | caller limits the search the kernel crypto API can perform for | |
506 | a suitable cipher implementation for the given cipher name. | |
507 | That means, even when a caller uses a cipher name that exists | |
508 | during its initialization call, the kernel crypto API may not | |
509 | select it due to the used type and mask field. | |
510 | </para> | |
511 | </sect1> | |
7b24d97f SM |
512 | |
513 | <sect1><title>Internal Structure of Kernel Crypto API</title> | |
514 | ||
515 | <para> | |
516 | The kernel crypto API has an internal structure where a cipher | |
517 | implementation may use many layers and indirections. This section | |
518 | shall help to clarify how the kernel crypto API uses | |
519 | various components to implement the complete cipher. | |
520 | </para> | |
521 | ||
522 | <para> | |
523 | The following subsections explain the internal structure based | |
524 | on existing cipher implementations. The first section addresses | |
525 | the most complex scenario where all other scenarios form a logical | |
526 | subset. | |
527 | </para> | |
528 | ||
529 | <sect2><title>Generic AEAD Cipher Structure</title> | |
530 | ||
531 | <para> | |
532 | The following ASCII art decomposes the kernel crypto API layers | |
533 | when using the AEAD cipher with the automated IV generation. The | |
534 | shown example is used by the IPSEC layer. | |
535 | </para> | |
536 | ||
537 | <para> | |
538 | For other use cases of AEAD ciphers, the ASCII art applies as | |
addfda2f SM |
539 | well, but the caller may not use the AEAD cipher with a separate |
540 | IV generator. In this case, the caller must generate the IV. | |
7b24d97f SM |
541 | </para> |
542 | ||
543 | <para> | |
544 | The depicted example decomposes the AEAD cipher of GCM(AES) based | |
545 | on the generic C implementations (gcm.c, aes-generic.c, ctr.c, | |
546 | ghash-generic.c, seqiv.c). The generic implementation serves as an | |
547 | example showing the complete logic of the kernel crypto API. | |
548 | </para> | |
549 | ||
550 | <para> | |
551 | It is possible that some streamlined cipher implementations (like | |
552 | AES-NI) provide implementations merging aspects which in the view | |
553 | of the kernel crypto API cannot be decomposed into layers any more. | |
554 | In case of the AES-NI implementation, the CTR mode, the GHASH | |
555 | implementation and the AES cipher are all merged into one cipher | |
556 | implementation registered with the kernel crypto API. In this case, | |
557 | the concept described by the following ASCII art applies too. However, | |
558 | the decomposition of GCM into the individual sub-components | |
559 | by the kernel crypto API is not done any more. | |
560 | </para> | |
561 | ||
562 | <para> | |
563 | Each block in the following ASCII art is an independent cipher | |
564 | instance obtained from the kernel crypto API. Each block | |
565 | is accessed by the caller or by other blocks using the API functions | |
566 | defined by the kernel crypto API for the cipher implementation type. | |
567 | </para> | |
568 | ||
569 | <para> | |
570 | The blocks below indicate the cipher type as well as the specific | |
571 | logic implemented in the cipher. | |
572 | </para> | |
573 | ||
574 | <para> | |
575 | The ASCII art picture also indicates the call structure, i.e. who | |
576 | calls which component. The arrows point to the invoked block | |
577 | where the caller uses the API applicable to the cipher type | |
578 | specified for the block. | |
579 | </para> | |
580 | ||
581 | <programlisting> | |
582 | <![CDATA[ | |
583 | kernel crypto API | IPSEC Layer | |
584 | | | |
585 | +-----------+ | | |
586 | | | (1) | |
addfda2f | 587 | | aead | <----------------------------------- esp_output |
f6e45c24 | 588 | | (seqiv) | ---+ |
7b24d97f SM |
589 | +-----------+ | |
590 | | (2) | |
591 | +-----------+ | | |
592 | | | <--+ (2) | |
593 | | aead | <----------------------------------- esp_input | |
594 | | (gcm) | ------------+ | |
595 | +-----------+ | | |
596 | | (3) | (5) | |
597 | v v | |
598 | +-----------+ +-----------+ | |
599 | | | | | | |
ba871e1d | 600 | | skcipher | | ahash | |
7b24d97f SM |
601 | | (ctr) | ---+ | (ghash) | |
602 | +-----------+ | +-----------+ | |
603 | | | |
604 | +-----------+ | (4) | |
605 | | | <--+ | |
606 | | cipher | | |
607 | | (aes) | | |
608 | +-----------+ | |
609 | ]]> | |
610 | </programlisting> | |
611 | ||
612 | <para> | |
613 | The following call sequence is applicable when the IPSEC layer | |
614 | triggers an encryption operation with the esp_output function. During | |
615 | configuration, the administrator set up the use of rfc4106(gcm(aes)) as | |
616 | the cipher for ESP. The following call sequence is now depicted in the | |
617 | ASCII art above: | |
618 | </para> | |
619 | ||
620 | <orderedlist> | |
621 | <listitem> | |
622 | <para> | |
addfda2f SM |
623 | esp_output() invokes crypto_aead_encrypt() to trigger an encryption |
624 | operation of the AEAD cipher with IV generator. | |
7b24d97f SM |
625 | </para> |
626 | ||
627 | <para> | |
628 | In case of GCM, the SEQIV implementation is registered as GIVCIPHER | |
629 | in crypto_rfc4106_alloc(). | |
630 | </para> | |
631 | ||
632 | <para> | |
633 | The SEQIV performs its operation to generate an IV where the core | |
634 | function is seqiv_geniv(). | |
635 | </para> | |
636 | </listitem> | |
637 | ||
638 | <listitem> | |
639 | <para> | |
640 | Now, SEQIV uses the AEAD API function calls to invoke the associated | |
641 | AEAD cipher. In our case, during the instantiation of SEQIV, the | |
642 | cipher handle for GCM is provided to SEQIV. This means that SEQIV | |
643 | invokes AEAD cipher operations with the GCM cipher handle. | |
644 | </para> | |
645 | ||
646 | <para> | |
647 | During instantiation of the GCM handle, the CTR(AES) and GHASH | |
648 | ciphers are instantiated. The cipher handles for CTR(AES) and GHASH | |
649 | are retained for later use. | |
650 | </para> | |
651 | ||
652 | <para> | |
653 | The GCM implementation is responsible to invoke the CTR mode AES and | |
654 | the GHASH cipher in the right manner to implement the GCM | |
655 | specification. | |
656 | </para> | |
657 | </listitem> | |
658 | ||
659 | <listitem> | |
660 | <para> | |
ba871e1d | 661 | The GCM AEAD cipher type implementation now invokes the SKCIPHER API |
7b24d97f SM |
662 | with the instantiated CTR(AES) cipher handle. |
663 | </para> | |
664 | ||
665 | <para> | |
666 | During instantiation of the CTR(AES) cipher, the CIPHER type | |
667 | implementation of AES is instantiated. The cipher handle for AES is | |
668 | retained. | |
669 | </para> | |
670 | ||
671 | <para> | |
ba871e1d | 672 | That means that the SKCIPHER implementation of CTR(AES) only |
7b24d97f SM |
673 | implements the CTR block chaining mode. After performing the block |
674 | chaining operation, the CIPHER implementation of AES is invoked. | |
675 | </para> | |
676 | </listitem> | |
677 | ||
678 | <listitem> | |
679 | <para> | |
ba871e1d | 680 | The SKCIPHER of CTR(AES) now invokes the CIPHER API with the AES |
7b24d97f SM |
681 | cipher handle to encrypt one block. |
682 | </para> | |
683 | </listitem> | |
684 | ||
685 | <listitem> | |
686 | <para> | |
687 | The GCM AEAD implementation also invokes the GHASH cipher | |
688 | implementation via the AHASH API. | |
689 | </para> | |
690 | </listitem> | |
691 | </orderedlist> | |
692 | ||
693 | <para> | |
694 | When the IPSEC layer triggers the esp_input() function, the same call | |
695 | sequence is followed with the only difference that the operation starts | |
696 | with step (2). | |
697 | </para> | |
698 | </sect2> | |
699 | ||
700 | <sect2><title>Generic Block Cipher Structure</title> | |
701 | <para> | |
702 | Generic block ciphers follow the same concept as depicted with the ASCII | |
703 | art picture above. | |
704 | </para> | |
705 | ||
706 | <para> | |
707 | For example, CBC(AES) is implemented with cbc.c, and aes-generic.c. The | |
708 | ASCII art picture above applies as well with the difference that only | |
ba871e1d | 709 | step (4) is used and the SKCIPHER block chaining mode is CBC. |
7b24d97f SM |
710 | </para> |
711 | </sect2> | |
712 | ||
713 | <sect2><title>Generic Keyed Message Digest Structure</title> | |
714 | <para> | |
715 | Keyed message digest implementations again follow the same concept as | |
716 | depicted in the ASCII art picture above. | |
717 | </para> | |
718 | ||
719 | <para> | |
720 | For example, HMAC(SHA256) is implemented with hmac.c and | |
721 | sha256_generic.c. The following ASCII art illustrates the | |
722 | implementation: | |
723 | </para> | |
724 | ||
725 | <programlisting> | |
726 | <![CDATA[ | |
727 | kernel crypto API | Caller | |
728 | | | |
729 | +-----------+ (1) | | |
730 | | | <------------------ some_function | |
731 | | ahash | | |
732 | | (hmac) | ---+ | |
733 | +-----------+ | | |
734 | | (2) | |
735 | +-----------+ | | |
736 | | | <--+ | |
737 | | shash | | |
738 | | (sha256) | | |
739 | +-----------+ | |
740 | ]]> | |
741 | </programlisting> | |
742 | ||
743 | <para> | |
744 | The following call sequence is applicable when a caller triggers | |
745 | an HMAC operation: | |
746 | </para> | |
747 | ||
748 | <orderedlist> | |
749 | <listitem> | |
750 | <para> | |
751 | The AHASH API functions are invoked by the caller. The HMAC | |
752 | implementation performs its operation as needed. | |
753 | </para> | |
754 | ||
755 | <para> | |
756 | During initialization of the HMAC cipher, the SHASH cipher type of | |
757 | SHA256 is instantiated. The cipher handle for the SHA256 instance is | |
758 | retained. | |
759 | </para> | |
760 | ||
761 | <para> | |
762 | At one time, the HMAC implementation requires a SHA256 operation | |
763 | where the SHA256 cipher handle is used. | |
764 | </para> | |
765 | </listitem> | |
766 | ||
767 | <listitem> | |
768 | <para> | |
769 | The HMAC instance now invokes the SHASH API with the SHA256 | |
770 | cipher handle to calculate the message digest. | |
771 | </para> | |
772 | </listitem> | |
773 | </orderedlist> | |
774 | </sect2> | |
775 | </sect1> | |
7d12993e SM |
776 | </chapter> |
777 | ||
778 | <chapter id="Development"><title>Developing Cipher Algorithms</title> | |
779 | <sect1><title>Registering And Unregistering Transformation</title> | |
780 | <para> | |
781 | There are three distinct types of registration functions in | |
782 | the Crypto API. One is used to register a generic cryptographic | |
783 | transformation, while the other two are specific to HASH | |
784 | transformations and COMPRESSion. We will discuss the latter | |
785 | two in a separate chapter, here we will only look at the | |
786 | generic ones. | |
787 | </para> | |
788 | ||
789 | <para> | |
790 | Before discussing the register functions, the data structure | |
791 | to be filled with each, struct crypto_alg, must be considered | |
792 | -- see below for a description of this data structure. | |
793 | </para> | |
794 | ||
795 | <para> | |
796 | The generic registration functions can be found in | |
797 | include/linux/crypto.h and their definition can be seen below. | |
798 | The former function registers a single transformation, while | |
799 | the latter works on an array of transformation descriptions. | |
800 | The latter is useful when registering transformations in bulk. | |
801 | </para> | |
802 | ||
803 | <programlisting> | |
804 | int crypto_register_alg(struct crypto_alg *alg); | |
805 | int crypto_register_algs(struct crypto_alg *algs, int count); | |
806 | </programlisting> | |
807 | ||
808 | <para> | |
809 | The counterparts to those functions are listed below. | |
810 | </para> | |
811 | ||
812 | <programlisting> | |
813 | int crypto_unregister_alg(struct crypto_alg *alg); | |
814 | int crypto_unregister_algs(struct crypto_alg *algs, int count); | |
815 | </programlisting> | |
816 | ||
817 | <para> | |
818 | Notice that both registration and unregistration functions | |
819 | do return a value, so make sure to handle errors. A return | |
820 | code of zero implies success. Any return code < 0 implies | |
821 | an error. | |
822 | </para> | |
823 | ||
824 | <para> | |
825 | The bulk registration / unregistration functions require | |
826 | that struct crypto_alg is an array of count size. These | |
827 | functions simply loop over that array and register / | |
828 | unregister each individual algorithm. If an error occurs, | |
829 | the loop is terminated at the offending algorithm definition. | |
830 | That means, the algorithms prior to the offending algorithm | |
831 | are successfully registered. Note, the caller has no way of | |
832 | knowing which cipher implementations have successfully | |
833 | registered. If this is important to know, the caller should | |
834 | loop through the different implementations using the single | |
835 | instance *_alg functions for each individual implementation. | |
836 | </para> | |
837 | </sect1> | |
838 | ||
839 | <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title> | |
840 | <para> | |
841 | Example of transformations: aes, arc4, ... | |
842 | </para> | |
843 | ||
844 | <para> | |
845 | This section describes the simplest of all transformation | |
846 | implementations, that being the CIPHER type used for symmetric | |
847 | ciphers. The CIPHER type is used for transformations which | |
848 | operate on exactly one block at a time and there are no | |
849 | dependencies between blocks at all. | |
850 | </para> | |
851 | ||
852 | <sect2><title>Registration specifics</title> | |
853 | <para> | |
854 | The registration of [CIPHER] algorithm is specific in that | |
855 | struct crypto_alg field .cra_type is empty. The .cra_u.cipher | |
856 | has to be filled in with proper callbacks to implement this | |
857 | transformation. | |
858 | </para> | |
859 | ||
860 | <para> | |
861 | See struct cipher_alg below. | |
862 | </para> | |
863 | </sect2> | |
864 | ||
865 | <sect2><title>Cipher Definition With struct cipher_alg</title> | |
866 | <para> | |
867 | Struct cipher_alg defines a single block cipher. | |
868 | </para> | |
869 | ||
870 | <para> | |
871 | Here are schematics of how these functions are called when | |
872 | operated from other part of the kernel. Note that the | |
873 | .cia_setkey() call might happen before or after any of these | |
874 | schematics happen, but must not happen during any of these | |
875 | are in-flight. | |
876 | </para> | |
877 | ||
878 | <para> | |
879 | <programlisting> | |
880 | KEY ---. PLAINTEXT ---. | |
881 | v v | |
882 | .cia_setkey() -> .cia_encrypt() | |
883 | | | |
884 | '-----> CIPHERTEXT | |
885 | </programlisting> | |
886 | </para> | |
887 | ||
888 | <para> | |
889 | Please note that a pattern where .cia_setkey() is called | |
890 | multiple times is also valid: | |
891 | </para> | |
892 | ||
893 | <para> | |
894 | <programlisting> | |
895 | ||
896 | KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --. | |
897 | v v v v | |
898 | .cia_setkey() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() | |
899 | | | | |
900 | '---> CIPHERTEXT1 '---> CIPHERTEXT2 | |
901 | </programlisting> | |
902 | </para> | |
903 | ||
904 | </sect2> | |
905 | </sect1> | |
906 | ||
ba871e1d | 907 | <sect1><title>Multi-Block Ciphers</title> |
7d12993e SM |
908 | <para> |
909 | Example of transformations: cbc(aes), ecb(arc4), ... | |
910 | </para> | |
911 | ||
912 | <para> | |
913 | This section describes the multi-block cipher transformation | |
ba871e1d | 914 | implementations. The multi-block ciphers are |
7d12993e SM |
915 | used for transformations which operate on scatterlists of |
916 | data supplied to the transformation functions. They output | |
917 | the result into a scatterlist of data as well. | |
918 | </para> | |
919 | ||
920 | <sect2><title>Registration Specifics</title> | |
921 | ||
922 | <para> | |
ba871e1d | 923 | The registration of multi-block cipher algorithms |
7d12993e SM |
924 | is one of the most standard procedures throughout the crypto API. |
925 | </para> | |
926 | ||
927 | <para> | |
928 | Note, if a cipher implementation requires a proper alignment | |
929 | of data, the caller should use the functions of | |
ba871e1d SM |
930 | crypto_skcipher_alignmask() to identify a memory alignment mask. |
931 | The kernel crypto API is able to process requests that are unaligned. | |
7d12993e SM |
932 | This implies, however, additional overhead as the kernel |
933 | crypto API needs to perform the realignment of the data which | |
934 | may imply moving of data. | |
935 | </para> | |
936 | </sect2> | |
937 | ||
938 | <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title> | |
939 | <para> | |
940 | Struct blkcipher_alg defines a synchronous block cipher whereas | |
941 | struct ablkcipher_alg defines an asynchronous block cipher. | |
942 | </para> | |
943 | ||
944 | <para> | |
945 | Please refer to the single block cipher description for schematics | |
ba871e1d | 946 | of the block cipher usage. |
7d12993e SM |
947 | </para> |
948 | </sect2> | |
949 | ||
950 | <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title> | |
951 | <para> | |
ba871e1d | 952 | There are a couple of specifics to the asynchronous interface. |
7d12993e SM |
953 | </para> |
954 | ||
955 | <para> | |
956 | First of all, some of the drivers will want to use the | |
957 | Generic ScatterWalk in case the hardware needs to be fed | |
958 | separate chunks of the scatterlist which contains the | |
959 | plaintext and will contain the ciphertext. Please refer | |
960 | to the ScatterWalk interface offered by the Linux kernel | |
961 | scatter / gather list implementation. | |
962 | </para> | |
963 | </sect2> | |
964 | </sect1> | |
965 | ||
966 | <sect1><title>Hashing [HASH]</title> | |
967 | ||
968 | <para> | |
969 | Example of transformations: crc32, md5, sha1, sha256,... | |
970 | </para> | |
971 | ||
972 | <sect2><title>Registering And Unregistering The Transformation</title> | |
973 | ||
974 | <para> | |
975 | There are multiple ways to register a HASH transformation, | |
976 | depending on whether the transformation is synchronous [SHASH] | |
977 | or asynchronous [AHASH] and the amount of HASH transformations | |
978 | we are registering. You can find the prototypes defined in | |
979 | include/crypto/internal/hash.h: | |
980 | </para> | |
981 | ||
982 | <programlisting> | |
983 | int crypto_register_ahash(struct ahash_alg *alg); | |
984 | ||
985 | int crypto_register_shash(struct shash_alg *alg); | |
986 | int crypto_register_shashes(struct shash_alg *algs, int count); | |
987 | </programlisting> | |
988 | ||
989 | <para> | |
990 | The respective counterparts for unregistering the HASH | |
991 | transformation are as follows: | |
992 | </para> | |
993 | ||
994 | <programlisting> | |
995 | int crypto_unregister_ahash(struct ahash_alg *alg); | |
996 | ||
997 | int crypto_unregister_shash(struct shash_alg *alg); | |
998 | int crypto_unregister_shashes(struct shash_alg *algs, int count); | |
999 | </programlisting> | |
1000 | </sect2> | |
1001 | ||
1002 | <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title> | |
1003 | <para> | |
1004 | Here are schematics of how these functions are called when | |
1005 | operated from other part of the kernel. Note that the .setkey() | |
1006 | call might happen before or after any of these schematics happen, | |
1007 | but must not happen during any of these are in-flight. Please note | |
1008 | that calling .init() followed immediately by .finish() is also a | |
1009 | perfectly valid transformation. | |
1010 | </para> | |
1011 | ||
1012 | <programlisting> | |
1013 | I) DATA -----------. | |
1014 | v | |
1015 | .init() -> .update() -> .final() ! .update() might not be called | |
1016 | ^ | | at all in this scenario. | |
1017 | '----' '---> HASH | |
1018 | ||
1019 | II) DATA -----------.-----------. | |
1020 | v v | |
1021 | .init() -> .update() -> .finup() ! .update() may not be called | |
1022 | ^ | | at all in this scenario. | |
1023 | '----' '---> HASH | |
1024 | ||
1025 | III) DATA -----------. | |
1026 | v | |
1027 | .digest() ! The entire process is handled | |
1028 | | by the .digest() call. | |
1029 | '---------------> HASH | |
1030 | </programlisting> | |
1031 | ||
1032 | <para> | |
1033 | Here is a schematic of how the .export()/.import() functions are | |
1034 | called when used from another part of the kernel. | |
1035 | </para> | |
1036 | ||
1037 | <programlisting> | |
1038 | KEY--. DATA--. | |
1039 | v v ! .update() may not be called | |
1040 | .setkey() -> .init() -> .update() -> .export() at all in this scenario. | |
1041 | ^ | | | |
1042 | '-----' '--> PARTIAL_HASH | |
1043 | ||
1044 | ----------- other transformations happen here ----------- | |
1045 | ||
1046 | PARTIAL_HASH--. DATA1--. | |
1047 | v v | |
1048 | .import -> .update() -> .final() ! .update() may not be called | |
1049 | ^ | | at all in this scenario. | |
1050 | '----' '--> HASH1 | |
1051 | ||
1052 | PARTIAL_HASH--. DATA2-. | |
1053 | v v | |
1054 | .import -> .finup() | |
1055 | | | |
1056 | '---------------> HASH2 | |
1057 | </programlisting> | |
1058 | </sect2> | |
1059 | ||
1060 | <sect2><title>Specifics Of Asynchronous HASH Transformation</title> | |
1061 | <para> | |
1062 | Some of the drivers will want to use the Generic ScatterWalk | |
1063 | in case the implementation needs to be fed separate chunks of the | |
1064 | scatterlist which contains the input data. The buffer containing | |
1065 | the resulting hash will always be properly aligned to | |
1066 | .cra_alignmask so there is no need to worry about this. | |
1067 | </para> | |
1068 | </sect2> | |
1069 | </sect1> | |
1070 | </chapter> | |
1071 | ||
dbe5fe7e SM |
1072 | <chapter id="User"><title>User Space Interface</title> |
1073 | <sect1><title>Introduction</title> | |
1074 | <para> | |
1075 | The concepts of the kernel crypto API visible to kernel space is fully | |
1076 | applicable to the user space interface as well. Therefore, the kernel | |
1077 | crypto API high level discussion for the in-kernel use cases applies | |
1078 | here as well. | |
1079 | </para> | |
1080 | ||
1081 | <para> | |
1082 | The major difference, however, is that user space can only act as a | |
1083 | consumer and never as a provider of a transformation or cipher algorithm. | |
1084 | </para> | |
1085 | ||
1086 | <para> | |
1087 | The following covers the user space interface exported by the kernel | |
1088 | crypto API. A working example of this description is libkcapi that | |
1089 | can be obtained from [1]. That library can be used by user space | |
1090 | applications that require cryptographic services from the kernel. | |
1091 | </para> | |
1092 | ||
1093 | <para> | |
1094 | Some details of the in-kernel kernel crypto API aspects do not | |
1095 | apply to user space, however. This includes the difference between | |
1096 | synchronous and asynchronous invocations. The user space API call | |
1097 | is fully synchronous. | |
1098 | </para> | |
1099 | ||
1100 | <para> | |
0e91657e | 1101 | [1] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink> |
dbe5fe7e SM |
1102 | </para> |
1103 | ||
1104 | </sect1> | |
1105 | ||
1106 | <sect1><title>User Space API General Remarks</title> | |
1107 | <para> | |
1108 | The kernel crypto API is accessible from user space. Currently, | |
1109 | the following ciphers are accessible: | |
1110 | </para> | |
1111 | ||
1112 | <itemizedlist> | |
1113 | <listitem> | |
1114 | <para>Message digest including keyed message digest (HMAC, CMAC)</para> | |
1115 | </listitem> | |
1116 | ||
1117 | <listitem> | |
1118 | <para>Symmetric ciphers</para> | |
1119 | </listitem> | |
1120 | ||
1121 | <listitem> | |
1122 | <para>AEAD ciphers</para> | |
1123 | </listitem> | |
1124 | ||
1125 | <listitem> | |
1126 | <para>Random Number Generators</para> | |
1127 | </listitem> | |
1128 | </itemizedlist> | |
1129 | ||
1130 | <para> | |
1131 | The interface is provided via socket type using the type AF_ALG. | |
1132 | In addition, the setsockopt option type is SOL_ALG. In case the | |
1133 | user space header files do not export these flags yet, use the | |
1134 | following macros: | |
1135 | </para> | |
1136 | ||
1137 | <programlisting> | |
1138 | #ifndef AF_ALG | |
1139 | #define AF_ALG 38 | |
1140 | #endif | |
1141 | #ifndef SOL_ALG | |
1142 | #define SOL_ALG 279 | |
1143 | #endif | |
1144 | </programlisting> | |
1145 | ||
1146 | <para> | |
1147 | A cipher is accessed with the same name as done for the in-kernel | |
1148 | API calls. This includes the generic vs. unique naming schema for | |
1149 | ciphers as well as the enforcement of priorities for generic names. | |
1150 | </para> | |
1151 | ||
1152 | <para> | |
1153 | To interact with the kernel crypto API, a socket must be | |
1154 | created by the user space application. User space invokes the cipher | |
1155 | operation with the send()/write() system call family. The result of the | |
1156 | cipher operation is obtained with the read()/recv() system call family. | |
1157 | </para> | |
1158 | ||
1159 | <para> | |
1160 | The following API calls assume that the socket descriptor | |
1161 | is already opened by the user space application and discusses only | |
1162 | the kernel crypto API specific invocations. | |
1163 | </para> | |
1164 | ||
1165 | <para> | |
1166 | To initialize the socket interface, the following sequence has to | |
1167 | be performed by the consumer: | |
1168 | </para> | |
1169 | ||
1170 | <orderedlist> | |
1171 | <listitem> | |
1172 | <para> | |
1173 | Create a socket of type AF_ALG with the struct sockaddr_alg | |
1174 | parameter specified below for the different cipher types. | |
1175 | </para> | |
1176 | </listitem> | |
1177 | ||
1178 | <listitem> | |
1179 | <para> | |
1180 | Invoke bind with the socket descriptor | |
1181 | </para> | |
1182 | </listitem> | |
1183 | ||
1184 | <listitem> | |
1185 | <para> | |
1186 | Invoke accept with the socket descriptor. The accept system call | |
1187 | returns a new file descriptor that is to be used to interact with | |
1188 | the particular cipher instance. When invoking send/write or recv/read | |
1189 | system calls to send data to the kernel or obtain data from the | |
1190 | kernel, the file descriptor returned by accept must be used. | |
1191 | </para> | |
1192 | </listitem> | |
1193 | </orderedlist> | |
1194 | </sect1> | |
1195 | ||
1196 | <sect1><title>In-place Cipher operation</title> | |
1197 | <para> | |
1198 | Just like the in-kernel operation of the kernel crypto API, the user | |
1199 | space interface allows the cipher operation in-place. That means that | |
1200 | the input buffer used for the send/write system call and the output | |
1201 | buffer used by the read/recv system call may be one and the same. | |
1202 | This is of particular interest for symmetric cipher operations where a | |
1203 | copying of the output data to its final destination can be avoided. | |
1204 | </para> | |
1205 | ||
1206 | <para> | |
1207 | If a consumer on the other hand wants to maintain the plaintext and | |
1208 | the ciphertext in different memory locations, all a consumer needs | |
1209 | to do is to provide different memory pointers for the encryption and | |
1210 | decryption operation. | |
1211 | </para> | |
1212 | </sect1> | |
1213 | ||
1214 | <sect1><title>Message Digest API</title> | |
1215 | <para> | |
1216 | The message digest type to be used for the cipher operation is | |
1217 | selected when invoking the bind syscall. bind requires the caller | |
1218 | to provide a filled struct sockaddr data structure. This data | |
1219 | structure must be filled as follows: | |
1220 | </para> | |
1221 | ||
1222 | <programlisting> | |
1223 | struct sockaddr_alg sa = { | |
1224 | .salg_family = AF_ALG, | |
1225 | .salg_type = "hash", /* this selects the hash logic in the kernel */ | |
1226 | .salg_name = "sha1" /* this is the cipher name */ | |
1227 | }; | |
1228 | </programlisting> | |
1229 | ||
1230 | <para> | |
1231 | The salg_type value "hash" applies to message digests and keyed | |
1232 | message digests. Though, a keyed message digest is referenced by | |
1233 | the appropriate salg_name. Please see below for the setsockopt | |
1234 | interface that explains how the key can be set for a keyed message | |
1235 | digest. | |
1236 | </para> | |
1237 | ||
1238 | <para> | |
1239 | Using the send() system call, the application provides the data that | |
1240 | should be processed with the message digest. The send system call | |
1241 | allows the following flags to be specified: | |
1242 | </para> | |
1243 | ||
1244 | <itemizedlist> | |
1245 | <listitem> | |
1246 | <para> | |
1247 | MSG_MORE: If this flag is set, the send system call acts like a | |
1248 | message digest update function where the final hash is not | |
1249 | yet calculated. If the flag is not set, the send system call | |
1250 | calculates the final message digest immediately. | |
1251 | </para> | |
1252 | </listitem> | |
1253 | </itemizedlist> | |
1254 | ||
1255 | <para> | |
1256 | With the recv() system call, the application can read the message | |
1257 | digest from the kernel crypto API. If the buffer is too small for the | |
1258 | message digest, the flag MSG_TRUNC is set by the kernel. | |
1259 | </para> | |
1260 | ||
1261 | <para> | |
1262 | In order to set a message digest key, the calling application must use | |
1263 | the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC | |
1264 | operation is performed without the initial HMAC state change caused by | |
1265 | the key. | |
1266 | </para> | |
1267 | </sect1> | |
1268 | ||
1269 | <sect1><title>Symmetric Cipher API</title> | |
1270 | <para> | |
1271 | The operation is very similar to the message digest discussion. | |
1272 | During initialization, the struct sockaddr data structure must be | |
1273 | filled as follows: | |
1274 | </para> | |
1275 | ||
1276 | <programlisting> | |
1277 | struct sockaddr_alg sa = { | |
1278 | .salg_family = AF_ALG, | |
1279 | .salg_type = "skcipher", /* this selects the symmetric cipher */ | |
1280 | .salg_name = "cbc(aes)" /* this is the cipher name */ | |
1281 | }; | |
1282 | </programlisting> | |
1283 | ||
1284 | <para> | |
1285 | Before data can be sent to the kernel using the write/send system | |
1286 | call family, the consumer must set the key. The key setting is | |
1287 | described with the setsockopt invocation below. | |
1288 | </para> | |
1289 | ||
1290 | <para> | |
1291 | Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is | |
1292 | specified with the data structure provided by the sendmsg() system call. | |
1293 | </para> | |
1294 | ||
1295 | <para> | |
1296 | The sendmsg system call parameter of struct msghdr is embedded into the | |
1297 | struct cmsghdr data structure. See recv(2) and cmsg(3) for more | |
1298 | information on how the cmsghdr data structure is used together with the | |
1299 | send/recv system call family. That cmsghdr data structure holds the | |
1300 | following information specified with a separate header instances: | |
1301 | </para> | |
1302 | ||
1303 | <itemizedlist> | |
1304 | <listitem> | |
1305 | <para> | |
1306 | specification of the cipher operation type with one of these flags: | |
1307 | </para> | |
1308 | <itemizedlist> | |
1309 | <listitem> | |
1310 | <para>ALG_OP_ENCRYPT - encryption of data</para> | |
1311 | </listitem> | |
1312 | <listitem> | |
1313 | <para>ALG_OP_DECRYPT - decryption of data</para> | |
1314 | </listitem> | |
1315 | </itemizedlist> | |
1316 | </listitem> | |
1317 | ||
1318 | <listitem> | |
1319 | <para> | |
1320 | specification of the IV information marked with the flag ALG_SET_IV | |
1321 | </para> | |
1322 | </listitem> | |
1323 | </itemizedlist> | |
1324 | ||
1325 | <para> | |
1326 | The send system call family allows the following flag to be specified: | |
1327 | </para> | |
1328 | ||
1329 | <itemizedlist> | |
1330 | <listitem> | |
1331 | <para> | |
1332 | MSG_MORE: If this flag is set, the send system call acts like a | |
1333 | cipher update function where more input data is expected | |
1334 | with a subsequent invocation of the send system call. | |
1335 | </para> | |
1336 | </listitem> | |
1337 | </itemizedlist> | |
1338 | ||
1339 | <para> | |
1340 | Note: The kernel reports -EINVAL for any unexpected data. The caller | |
1341 | must make sure that all data matches the constraints given in | |
1342 | /proc/crypto for the selected cipher. | |
1343 | </para> | |
1344 | ||
1345 | <para> | |
1346 | With the recv() system call, the application can read the result of | |
1347 | the cipher operation from the kernel crypto API. The output buffer | |
1348 | must be at least as large as to hold all blocks of the encrypted or | |
1349 | decrypted data. If the output data size is smaller, only as many | |
1350 | blocks are returned that fit into that output buffer size. | |
1351 | </para> | |
1352 | </sect1> | |
1353 | ||
1354 | <sect1><title>AEAD Cipher API</title> | |
1355 | <para> | |
1356 | The operation is very similar to the symmetric cipher discussion. | |
1357 | During initialization, the struct sockaddr data structure must be | |
1358 | filled as follows: | |
1359 | </para> | |
1360 | ||
1361 | <programlisting> | |
1362 | struct sockaddr_alg sa = { | |
1363 | .salg_family = AF_ALG, | |
1364 | .salg_type = "aead", /* this selects the symmetric cipher */ | |
1365 | .salg_name = "gcm(aes)" /* this is the cipher name */ | |
1366 | }; | |
1367 | </programlisting> | |
1368 | ||
1369 | <para> | |
1370 | Before data can be sent to the kernel using the write/send system | |
1371 | call family, the consumer must set the key. The key setting is | |
1372 | described with the setsockopt invocation below. | |
1373 | </para> | |
1374 | ||
1375 | <para> | |
1376 | In addition, before data can be sent to the kernel using the | |
1377 | write/send system call family, the consumer must set the authentication | |
1378 | tag size. To set the authentication tag size, the caller must use the | |
1379 | setsockopt invocation described below. | |
1380 | </para> | |
1381 | ||
1382 | <para> | |
1383 | Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is | |
1384 | specified with the data structure provided by the sendmsg() system call. | |
1385 | </para> | |
1386 | ||
1387 | <para> | |
1388 | The sendmsg system call parameter of struct msghdr is embedded into the | |
1389 | struct cmsghdr data structure. See recv(2) and cmsg(3) for more | |
1390 | information on how the cmsghdr data structure is used together with the | |
1391 | send/recv system call family. That cmsghdr data structure holds the | |
1392 | following information specified with a separate header instances: | |
1393 | </para> | |
1394 | ||
1395 | <itemizedlist> | |
1396 | <listitem> | |
1397 | <para> | |
1398 | specification of the cipher operation type with one of these flags: | |
1399 | </para> | |
1400 | <itemizedlist> | |
1401 | <listitem> | |
1402 | <para>ALG_OP_ENCRYPT - encryption of data</para> | |
1403 | </listitem> | |
1404 | <listitem> | |
1405 | <para>ALG_OP_DECRYPT - decryption of data</para> | |
1406 | </listitem> | |
1407 | </itemizedlist> | |
1408 | </listitem> | |
1409 | ||
1410 | <listitem> | |
1411 | <para> | |
1412 | specification of the IV information marked with the flag ALG_SET_IV | |
1413 | </para> | |
1414 | </listitem> | |
1415 | ||
1416 | <listitem> | |
1417 | <para> | |
1418 | specification of the associated authentication data (AAD) with the | |
1419 | flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together | |
1420 | with the plaintext / ciphertext. See below for the memory structure. | |
1421 | </para> | |
1422 | </listitem> | |
1423 | </itemizedlist> | |
1424 | ||
1425 | <para> | |
1426 | The send system call family allows the following flag to be specified: | |
1427 | </para> | |
1428 | ||
1429 | <itemizedlist> | |
1430 | <listitem> | |
1431 | <para> | |
1432 | MSG_MORE: If this flag is set, the send system call acts like a | |
1433 | cipher update function where more input data is expected | |
1434 | with a subsequent invocation of the send system call. | |
1435 | </para> | |
1436 | </listitem> | |
1437 | </itemizedlist> | |
1438 | ||
1439 | <para> | |
1440 | Note: The kernel reports -EINVAL for any unexpected data. The caller | |
1441 | must make sure that all data matches the constraints given in | |
1442 | /proc/crypto for the selected cipher. | |
1443 | </para> | |
1444 | ||
1445 | <para> | |
1446 | With the recv() system call, the application can read the result of | |
1447 | the cipher operation from the kernel crypto API. The output buffer | |
1448 | must be at least as large as defined with the memory structure below. | |
1449 | If the output data size is smaller, the cipher operation is not performed. | |
1450 | </para> | |
1451 | ||
1452 | <para> | |
1453 | The authenticated decryption operation may indicate an integrity error. | |
1454 | Such breach in integrity is marked with the -EBADMSG error code. | |
1455 | </para> | |
1456 | ||
1457 | <sect2><title>AEAD Memory Structure</title> | |
1458 | <para> | |
1459 | The AEAD cipher operates with the following information that | |
1460 | is communicated between user and kernel space as one data stream: | |
1461 | </para> | |
1462 | ||
1463 | <itemizedlist> | |
1464 | <listitem> | |
1465 | <para>plaintext or ciphertext</para> | |
1466 | </listitem> | |
1467 | ||
1468 | <listitem> | |
1469 | <para>associated authentication data (AAD)</para> | |
1470 | </listitem> | |
1471 | ||
1472 | <listitem> | |
1473 | <para>authentication tag</para> | |
1474 | </listitem> | |
1475 | </itemizedlist> | |
1476 | ||
1477 | <para> | |
1478 | The sizes of the AAD and the authentication tag are provided with | |
1479 | the sendmsg and setsockopt calls (see there). As the kernel knows | |
1480 | the size of the entire data stream, the kernel is now able to | |
1481 | calculate the right offsets of the data components in the data | |
1482 | stream. | |
1483 | </para> | |
1484 | ||
1485 | <para> | |
1486 | The user space caller must arrange the aforementioned information | |
1487 | in the following order: | |
1488 | </para> | |
1489 | ||
1490 | <itemizedlist> | |
1491 | <listitem> | |
1492 | <para> | |
1493 | AEAD encryption input: AAD || plaintext | |
1494 | </para> | |
1495 | </listitem> | |
1496 | ||
1497 | <listitem> | |
1498 | <para> | |
1499 | AEAD decryption input: AAD || ciphertext || authentication tag | |
1500 | </para> | |
1501 | </listitem> | |
1502 | </itemizedlist> | |
1503 | ||
1504 | <para> | |
1505 | The output buffer the user space caller provides must be at least as | |
1506 | large to hold the following data: | |
1507 | </para> | |
1508 | ||
1509 | <itemizedlist> | |
1510 | <listitem> | |
1511 | <para> | |
1512 | AEAD encryption output: ciphertext || authentication tag | |
1513 | </para> | |
1514 | </listitem> | |
1515 | ||
1516 | <listitem> | |
1517 | <para> | |
1518 | AEAD decryption output: plaintext | |
1519 | </para> | |
1520 | </listitem> | |
1521 | </itemizedlist> | |
1522 | </sect2> | |
1523 | </sect1> | |
1524 | ||
1525 | <sect1><title>Random Number Generator API</title> | |
1526 | <para> | |
1527 | Again, the operation is very similar to the other APIs. | |
1528 | During initialization, the struct sockaddr data structure must be | |
1529 | filled as follows: | |
1530 | </para> | |
1531 | ||
1532 | <programlisting> | |
1533 | struct sockaddr_alg sa = { | |
1534 | .salg_family = AF_ALG, | |
1535 | .salg_type = "rng", /* this selects the symmetric cipher */ | |
1536 | .salg_name = "drbg_nopr_sha256" /* this is the cipher name */ | |
1537 | }; | |
1538 | </programlisting> | |
1539 | ||
1540 | <para> | |
1541 | Depending on the RNG type, the RNG must be seeded. The seed is provided | |
1542 | using the setsockopt interface to set the key. For example, the | |
1543 | ansi_cprng requires a seed. The DRBGs do not require a seed, but | |
1544 | may be seeded. | |
1545 | </para> | |
1546 | ||
1547 | <para> | |
1548 | Using the read()/recvmsg() system calls, random numbers can be obtained. | |
1549 | The kernel generates at most 128 bytes in one call. If user space | |
1550 | requires more data, multiple calls to read()/recvmsg() must be made. | |
1551 | </para> | |
1552 | ||
1553 | <para> | |
1554 | WARNING: The user space caller may invoke the initially mentioned | |
1555 | accept system call multiple times. In this case, the returned file | |
1556 | descriptors have the same state. | |
1557 | </para> | |
1558 | ||
1559 | </sect1> | |
1560 | ||
1561 | <sect1><title>Zero-Copy Interface</title> | |
1562 | <para> | |
6b212f0f | 1563 | In addition to the send/write/read/recv system call family, the AF_ALG |
dbe5fe7e SM |
1564 | interface can be accessed with the zero-copy interface of splice/vmsplice. |
1565 | As the name indicates, the kernel tries to avoid a copy operation into | |
1566 | kernel space. | |
1567 | </para> | |
1568 | ||
1569 | <para> | |
1570 | The zero-copy operation requires data to be aligned at the page boundary. | |
1571 | Non-aligned data can be used as well, but may require more operations of | |
1572 | the kernel which would defeat the speed gains obtained from the zero-copy | |
1573 | interface. | |
1574 | </para> | |
1575 | ||
1576 | <para> | |
1577 | The system-interent limit for the size of one zero-copy operation is | |
1578 | 16 pages. If more data is to be sent to AF_ALG, user space must slice | |
1579 | the input into segments with a maximum size of 16 pages. | |
1580 | </para> | |
1581 | ||
1582 | <para> | |
1583 | Zero-copy can be used with the following code example (a complete working | |
1584 | example is provided with libkcapi): | |
1585 | </para> | |
1586 | ||
1587 | <programlisting> | |
1588 | int pipes[2]; | |
1589 | ||
1590 | pipe(pipes); | |
1591 | /* input data in iov */ | |
1592 | vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT); | |
1593 | /* opfd is the file descriptor returned from accept() system call */ | |
1594 | splice(pipes[0], NULL, opfd, NULL, ret, 0); | |
1595 | read(opfd, out, outlen); | |
1596 | </programlisting> | |
1597 | ||
1598 | </sect1> | |
1599 | ||
1600 | <sect1><title>Setsockopt Interface</title> | |
1601 | <para> | |
1602 | In addition to the read/recv and send/write system call handling | |
1603 | to send and retrieve data subject to the cipher operation, a consumer | |
1604 | also needs to set the additional information for the cipher operation. | |
1605 | This additional information is set using the setsockopt system call | |
1606 | that must be invoked with the file descriptor of the open cipher | |
1607 | (i.e. the file descriptor returned by the accept system call). | |
1608 | </para> | |
1609 | ||
1610 | <para> | |
1611 | Each setsockopt invocation must use the level SOL_ALG. | |
1612 | </para> | |
1613 | ||
1614 | <para> | |
1615 | The setsockopt interface allows setting the following data using | |
1616 | the mentioned optname: | |
1617 | </para> | |
1618 | ||
1619 | <itemizedlist> | |
1620 | <listitem> | |
1621 | <para> | |
1622 | ALG_SET_KEY -- Setting the key. Key setting is applicable to: | |
1623 | </para> | |
1624 | <itemizedlist> | |
1625 | <listitem> | |
1626 | <para>the skcipher cipher type (symmetric ciphers)</para> | |
1627 | </listitem> | |
1628 | <listitem> | |
1629 | <para>the hash cipher type (keyed message digests)</para> | |
1630 | </listitem> | |
1631 | <listitem> | |
1632 | <para>the AEAD cipher type</para> | |
1633 | </listitem> | |
1634 | <listitem> | |
1635 | <para>the RNG cipher type to provide the seed</para> | |
1636 | </listitem> | |
1637 | </itemizedlist> | |
1638 | </listitem> | |
1639 | ||
1640 | <listitem> | |
1641 | <para> | |
1642 | ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size | |
1643 | for AEAD ciphers. For a encryption operation, the authentication | |
1644 | tag of the given size will be generated. For a decryption operation, | |
1645 | the provided ciphertext is assumed to contain an authentication tag | |
1646 | of the given size (see section about AEAD memory layout below). | |
1647 | </para> | |
1648 | </listitem> | |
1649 | </itemizedlist> | |
1650 | ||
1651 | </sect1> | |
1652 | ||
1653 | <sect1><title>User space API example</title> | |
1654 | <para> | |
1655 | Please see [1] for libkcapi which provides an easy-to-use wrapper | |
1656 | around the aforementioned Netlink kernel interface. [1] also contains | |
1657 | a test application that invokes all libkcapi API calls. | |
1658 | </para> | |
1659 | ||
1660 | <para> | |
0e91657e | 1661 | [1] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink> |
dbe5fe7e SM |
1662 | </para> |
1663 | ||
1664 | </sect1> | |
1665 | ||
1666 | </chapter> | |
1667 | ||
7d12993e | 1668 | <chapter id="API"><title>Programming Interface</title> |
addfda2f SM |
1669 | <para> |
1670 | Please note that the kernel crypto API contains the AEAD givcrypt | |
1671 | API (crypto_aead_giv* and aead_givcrypt_* function calls in | |
1672 | include/crypto/aead.h). This API is obsolete and will be removed | |
1673 | in the future. To obtain the functionality of an AEAD cipher with | |
1674 | internal IV generation, use the IV generator as a regular cipher. | |
1675 | For example, rfc4106(gcm(aes)) is the AEAD cipher with external | |
1676 | IV generation and seqniv(rfc4106(gcm(aes))) implies that the kernel | |
1677 | crypto API generates the IV. Different IV generators are available. | |
1678 | </para> | |
7d12993e SM |
1679 | <sect1><title>Block Cipher Context Data Structures</title> |
1680 | !Pinclude/linux/crypto.h Block Cipher Context Data Structures | |
05767229 | 1681 | !Finclude/crypto/aead.h aead_request |
7d12993e SM |
1682 | </sect1> |
1683 | <sect1><title>Block Cipher Algorithm Definitions</title> | |
1684 | !Pinclude/linux/crypto.h Block Cipher Algorithm Definitions | |
1685 | !Finclude/linux/crypto.h crypto_alg | |
1686 | !Finclude/linux/crypto.h ablkcipher_alg | |
f6e45c24 | 1687 | !Finclude/crypto/aead.h aead_alg |
7d12993e SM |
1688 | !Finclude/linux/crypto.h blkcipher_alg |
1689 | !Finclude/linux/crypto.h cipher_alg | |
05767229 | 1690 | !Finclude/crypto/rng.h rng_alg |
7d12993e | 1691 | </sect1> |
ba871e1d SM |
1692 | <sect1><title>Symmetric Key Cipher API</title> |
1693 | !Pinclude/crypto/skcipher.h Symmetric Key Cipher API | |
1694 | !Finclude/crypto/skcipher.h crypto_alloc_skcipher | |
1695 | !Finclude/crypto/skcipher.h crypto_free_skcipher | |
1696 | !Finclude/crypto/skcipher.h crypto_has_skcipher | |
1697 | !Finclude/crypto/skcipher.h crypto_skcipher_ivsize | |
1698 | !Finclude/crypto/skcipher.h crypto_skcipher_blocksize | |
1699 | !Finclude/crypto/skcipher.h crypto_skcipher_setkey | |
1700 | !Finclude/crypto/skcipher.h crypto_skcipher_reqtfm | |
1701 | !Finclude/crypto/skcipher.h crypto_skcipher_encrypt | |
1702 | !Finclude/crypto/skcipher.h crypto_skcipher_decrypt | |
1703 | </sect1> | |
1704 | <sect1><title>Symmetric Key Cipher Request Handle</title> | |
1705 | !Pinclude/crypto/skcipher.h Symmetric Key Cipher Request Handle | |
1706 | !Finclude/crypto/skcipher.h crypto_skcipher_reqsize | |
1707 | !Finclude/crypto/skcipher.h skcipher_request_set_tfm | |
1708 | !Finclude/crypto/skcipher.h skcipher_request_alloc | |
1709 | !Finclude/crypto/skcipher.h skcipher_request_free | |
1710 | !Finclude/crypto/skcipher.h skcipher_request_set_callback | |
1711 | !Finclude/crypto/skcipher.h skcipher_request_set_crypt | |
1712 | </sect1> | |
1713 | <sect1><title>Asynchronous Block Cipher API - Deprecated</title> | |
7d12993e SM |
1714 | !Pinclude/linux/crypto.h Asynchronous Block Cipher API |
1715 | !Finclude/linux/crypto.h crypto_alloc_ablkcipher | |
1716 | !Finclude/linux/crypto.h crypto_free_ablkcipher | |
1717 | !Finclude/linux/crypto.h crypto_has_ablkcipher | |
1718 | !Finclude/linux/crypto.h crypto_ablkcipher_ivsize | |
1719 | !Finclude/linux/crypto.h crypto_ablkcipher_blocksize | |
1720 | !Finclude/linux/crypto.h crypto_ablkcipher_setkey | |
1721 | !Finclude/linux/crypto.h crypto_ablkcipher_reqtfm | |
1722 | !Finclude/linux/crypto.h crypto_ablkcipher_encrypt | |
1723 | !Finclude/linux/crypto.h crypto_ablkcipher_decrypt | |
1724 | </sect1> | |
ba871e1d | 1725 | <sect1><title>Asynchronous Cipher Request Handle - Deprecated</title> |
7d12993e SM |
1726 | !Pinclude/linux/crypto.h Asynchronous Cipher Request Handle |
1727 | !Finclude/linux/crypto.h crypto_ablkcipher_reqsize | |
1728 | !Finclude/linux/crypto.h ablkcipher_request_set_tfm | |
1729 | !Finclude/linux/crypto.h ablkcipher_request_alloc | |
1730 | !Finclude/linux/crypto.h ablkcipher_request_free | |
1731 | !Finclude/linux/crypto.h ablkcipher_request_set_callback | |
1732 | !Finclude/linux/crypto.h ablkcipher_request_set_crypt | |
1733 | </sect1> | |
1734 | <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title> | |
05767229 SM |
1735 | !Pinclude/crypto/aead.h Authenticated Encryption With Associated Data (AEAD) Cipher API |
1736 | !Finclude/crypto/aead.h crypto_alloc_aead | |
1737 | !Finclude/crypto/aead.h crypto_free_aead | |
1738 | !Finclude/crypto/aead.h crypto_aead_ivsize | |
1739 | !Finclude/crypto/aead.h crypto_aead_authsize | |
1740 | !Finclude/crypto/aead.h crypto_aead_blocksize | |
1741 | !Finclude/crypto/aead.h crypto_aead_setkey | |
1742 | !Finclude/crypto/aead.h crypto_aead_setauthsize | |
1743 | !Finclude/crypto/aead.h crypto_aead_encrypt | |
1744 | !Finclude/crypto/aead.h crypto_aead_decrypt | |
7d12993e SM |
1745 | </sect1> |
1746 | <sect1><title>Asynchronous AEAD Request Handle</title> | |
05767229 SM |
1747 | !Pinclude/crypto/aead.h Asynchronous AEAD Request Handle |
1748 | !Finclude/crypto/aead.h crypto_aead_reqsize | |
1749 | !Finclude/crypto/aead.h aead_request_set_tfm | |
1750 | !Finclude/crypto/aead.h aead_request_alloc | |
1751 | !Finclude/crypto/aead.h aead_request_free | |
1752 | !Finclude/crypto/aead.h aead_request_set_callback | |
1753 | !Finclude/crypto/aead.h aead_request_set_crypt | |
addfda2f | 1754 | !Finclude/crypto/aead.h aead_request_set_ad |
7d12993e | 1755 | </sect1> |
ba871e1d | 1756 | <sect1><title>Synchronous Block Cipher API - Deprecated</title> |
7d12993e SM |
1757 | !Pinclude/linux/crypto.h Synchronous Block Cipher API |
1758 | !Finclude/linux/crypto.h crypto_alloc_blkcipher | |
1759 | !Finclude/linux/crypto.h crypto_free_blkcipher | |
1760 | !Finclude/linux/crypto.h crypto_has_blkcipher | |
1761 | !Finclude/linux/crypto.h crypto_blkcipher_name | |
1762 | !Finclude/linux/crypto.h crypto_blkcipher_ivsize | |
1763 | !Finclude/linux/crypto.h crypto_blkcipher_blocksize | |
1764 | !Finclude/linux/crypto.h crypto_blkcipher_setkey | |
1765 | !Finclude/linux/crypto.h crypto_blkcipher_encrypt | |
1766 | !Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv | |
1767 | !Finclude/linux/crypto.h crypto_blkcipher_decrypt | |
1768 | !Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv | |
1769 | !Finclude/linux/crypto.h crypto_blkcipher_set_iv | |
1770 | !Finclude/linux/crypto.h crypto_blkcipher_get_iv | |
1771 | </sect1> | |
1772 | <sect1><title>Single Block Cipher API</title> | |
1773 | !Pinclude/linux/crypto.h Single Block Cipher API | |
1774 | !Finclude/linux/crypto.h crypto_alloc_cipher | |
1775 | !Finclude/linux/crypto.h crypto_free_cipher | |
1776 | !Finclude/linux/crypto.h crypto_has_cipher | |
1777 | !Finclude/linux/crypto.h crypto_cipher_blocksize | |
1778 | !Finclude/linux/crypto.h crypto_cipher_setkey | |
1779 | !Finclude/linux/crypto.h crypto_cipher_encrypt_one | |
1780 | !Finclude/linux/crypto.h crypto_cipher_decrypt_one | |
7d12993e SM |
1781 | </sect1> |
1782 | <sect1><title>Message Digest Algorithm Definitions</title> | |
1783 | !Pinclude/crypto/hash.h Message Digest Algorithm Definitions | |
1784 | !Finclude/crypto/hash.h hash_alg_common | |
1785 | !Finclude/crypto/hash.h ahash_alg | |
1786 | !Finclude/crypto/hash.h shash_alg | |
1787 | </sect1> | |
1788 | <sect1><title>Asynchronous Message Digest API</title> | |
1789 | !Pinclude/crypto/hash.h Asynchronous Message Digest API | |
1790 | !Finclude/crypto/hash.h crypto_alloc_ahash | |
1791 | !Finclude/crypto/hash.h crypto_free_ahash | |
1792 | !Finclude/crypto/hash.h crypto_ahash_init | |
1793 | !Finclude/crypto/hash.h crypto_ahash_digestsize | |
1794 | !Finclude/crypto/hash.h crypto_ahash_reqtfm | |
1795 | !Finclude/crypto/hash.h crypto_ahash_reqsize | |
1796 | !Finclude/crypto/hash.h crypto_ahash_setkey | |
1797 | !Finclude/crypto/hash.h crypto_ahash_finup | |
1798 | !Finclude/crypto/hash.h crypto_ahash_final | |
1799 | !Finclude/crypto/hash.h crypto_ahash_digest | |
1800 | !Finclude/crypto/hash.h crypto_ahash_export | |
1801 | !Finclude/crypto/hash.h crypto_ahash_import | |
1802 | </sect1> | |
1803 | <sect1><title>Asynchronous Hash Request Handle</title> | |
1804 | !Pinclude/crypto/hash.h Asynchronous Hash Request Handle | |
1805 | !Finclude/crypto/hash.h ahash_request_set_tfm | |
1806 | !Finclude/crypto/hash.h ahash_request_alloc | |
1807 | !Finclude/crypto/hash.h ahash_request_free | |
1808 | !Finclude/crypto/hash.h ahash_request_set_callback | |
1809 | !Finclude/crypto/hash.h ahash_request_set_crypt | |
1810 | </sect1> | |
1811 | <sect1><title>Synchronous Message Digest API</title> | |
1812 | !Pinclude/crypto/hash.h Synchronous Message Digest API | |
1813 | !Finclude/crypto/hash.h crypto_alloc_shash | |
1814 | !Finclude/crypto/hash.h crypto_free_shash | |
1815 | !Finclude/crypto/hash.h crypto_shash_blocksize | |
1816 | !Finclude/crypto/hash.h crypto_shash_digestsize | |
1817 | !Finclude/crypto/hash.h crypto_shash_descsize | |
1818 | !Finclude/crypto/hash.h crypto_shash_setkey | |
1819 | !Finclude/crypto/hash.h crypto_shash_digest | |
1820 | !Finclude/crypto/hash.h crypto_shash_export | |
1821 | !Finclude/crypto/hash.h crypto_shash_import | |
1822 | !Finclude/crypto/hash.h crypto_shash_init | |
1823 | !Finclude/crypto/hash.h crypto_shash_update | |
1824 | !Finclude/crypto/hash.h crypto_shash_final | |
1825 | !Finclude/crypto/hash.h crypto_shash_finup | |
1826 | </sect1> | |
1827 | <sect1><title>Crypto API Random Number API</title> | |
1828 | !Pinclude/crypto/rng.h Random number generator API | |
1829 | !Finclude/crypto/rng.h crypto_alloc_rng | |
1830 | !Finclude/crypto/rng.h crypto_rng_alg | |
1831 | !Finclude/crypto/rng.h crypto_free_rng | |
649e2007 | 1832 | !Finclude/crypto/rng.h crypto_rng_generate |
7d12993e SM |
1833 | !Finclude/crypto/rng.h crypto_rng_get_bytes |
1834 | !Finclude/crypto/rng.h crypto_rng_reset | |
1835 | !Finclude/crypto/rng.h crypto_rng_seedsize | |
1836 | !Cinclude/crypto/rng.h | |
1837 | </sect1> | |
e1eabc05 SM |
1838 | <sect1><title>Asymmetric Cipher API</title> |
1839 | !Pinclude/crypto/akcipher.h Generic Public Key API | |
1840 | !Finclude/crypto/akcipher.h akcipher_alg | |
1841 | !Finclude/crypto/akcipher.h akcipher_request | |
1842 | !Finclude/crypto/akcipher.h crypto_alloc_akcipher | |
1843 | !Finclude/crypto/akcipher.h crypto_free_akcipher | |
1844 | !Finclude/crypto/akcipher.h crypto_akcipher_set_pub_key | |
1845 | !Finclude/crypto/akcipher.h crypto_akcipher_set_priv_key | |
1846 | </sect1> | |
1847 | <sect1><title>Asymmetric Cipher Request Handle</title> | |
1848 | !Finclude/crypto/akcipher.h akcipher_request_alloc | |
1849 | !Finclude/crypto/akcipher.h akcipher_request_free | |
1850 | !Finclude/crypto/akcipher.h akcipher_request_set_callback | |
1851 | !Finclude/crypto/akcipher.h akcipher_request_set_crypt | |
1852 | !Finclude/crypto/akcipher.h crypto_akcipher_maxsize | |
1853 | !Finclude/crypto/akcipher.h crypto_akcipher_encrypt | |
1854 | !Finclude/crypto/akcipher.h crypto_akcipher_decrypt | |
1855 | !Finclude/crypto/akcipher.h crypto_akcipher_sign | |
1856 | !Finclude/crypto/akcipher.h crypto_akcipher_verify | |
1857 | </sect1> | |
7d12993e SM |
1858 | </chapter> |
1859 | ||
1860 | <chapter id="Code"><title>Code Examples</title> | |
ba871e1d | 1861 | <sect1><title>Code Example For Symmetric Key Cipher Operation</title> |
7d12993e SM |
1862 | <programlisting> |
1863 | ||
1864 | struct tcrypt_result { | |
1865 | struct completion completion; | |
1866 | int err; | |
1867 | }; | |
1868 | ||
1869 | /* tie all data structures together */ | |
ba871e1d | 1870 | struct skcipher_def { |
7d12993e | 1871 | struct scatterlist sg; |
ba871e1d SM |
1872 | struct crypto_skcipher *tfm; |
1873 | struct skcipher_request *req; | |
7d12993e SM |
1874 | struct tcrypt_result result; |
1875 | }; | |
1876 | ||
1877 | /* Callback function */ | |
ba871e1d | 1878 | static void test_skcipher_cb(struct crypto_async_request *req, int error) |
7d12993e SM |
1879 | { |
1880 | struct tcrypt_result *result = req->data; | |
1881 | ||
1882 | if (error == -EINPROGRESS) | |
1883 | return; | |
1884 | result->err = error; | |
1885 | complete(&result->completion); | |
1886 | pr_info("Encryption finished successfully\n"); | |
1887 | } | |
1888 | ||
1889 | /* Perform cipher operation */ | |
ba871e1d SM |
1890 | static unsigned int test_skcipher_encdec(struct skcipher_def *sk, |
1891 | int enc) | |
7d12993e SM |
1892 | { |
1893 | int rc = 0; | |
1894 | ||
1895 | if (enc) | |
ba871e1d | 1896 | rc = crypto_skcipher_encrypt(sk->req); |
7d12993e | 1897 | else |
ba871e1d | 1898 | rc = crypto_skcipher_decrypt(sk->req); |
7d12993e SM |
1899 | |
1900 | switch (rc) { | |
1901 | case 0: | |
1902 | break; | |
1903 | case -EINPROGRESS: | |
1904 | case -EBUSY: | |
1905 | rc = wait_for_completion_interruptible( | |
ba871e1d SM |
1906 | &sk->result.completion); |
1907 | if (!rc && !sk->result.err) { | |
1908 | reinit_completion(&sk->result.completion); | |
7d12993e SM |
1909 | break; |
1910 | } | |
1911 | default: | |
ba871e1d SM |
1912 | pr_info("skcipher encrypt returned with %d result %d\n", |
1913 | rc, sk->result.err); | |
7d12993e SM |
1914 | break; |
1915 | } | |
ba871e1d | 1916 | init_completion(&sk->result.completion); |
7d12993e SM |
1917 | |
1918 | return rc; | |
1919 | } | |
1920 | ||
1921 | /* Initialize and trigger cipher operation */ | |
ba871e1d | 1922 | static int test_skcipher(void) |
7d12993e | 1923 | { |
ba871e1d SM |
1924 | struct skcipher_def sk; |
1925 | struct crypto_skcipher *skcipher = NULL; | |
1926 | struct skcipher_request *req = NULL; | |
7d12993e SM |
1927 | char *scratchpad = NULL; |
1928 | char *ivdata = NULL; | |
1929 | unsigned char key[32]; | |
1930 | int ret = -EFAULT; | |
1931 | ||
ba871e1d SM |
1932 | skcipher = crypto_alloc_skcipher("cbc-aes-aesni", 0, 0); |
1933 | if (IS_ERR(skcipher)) { | |
1934 | pr_info("could not allocate skcipher handle\n"); | |
1935 | return PTR_ERR(skcipher); | |
7d12993e SM |
1936 | } |
1937 | ||
ba871e1d | 1938 | req = skcipher_request_alloc(skcipher, GFP_KERNEL); |
6eae29e7 EB |
1939 | if (!req) { |
1940 | pr_info("could not allocate skcipher request\n"); | |
1941 | ret = -ENOMEM; | |
7d12993e SM |
1942 | goto out; |
1943 | } | |
1944 | ||
ba871e1d SM |
1945 | skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, |
1946 | test_skcipher_cb, | |
1947 | &sk.result); | |
7d12993e SM |
1948 | |
1949 | /* AES 256 with random key */ | |
1950 | get_random_bytes(&key, 32); | |
ba871e1d | 1951 | if (crypto_skcipher_setkey(skcipher, key, 32)) { |
7d12993e SM |
1952 | pr_info("key could not be set\n"); |
1953 | ret = -EAGAIN; | |
1954 | goto out; | |
1955 | } | |
1956 | ||
1957 | /* IV will be random */ | |
1958 | ivdata = kmalloc(16, GFP_KERNEL); | |
1959 | if (!ivdata) { | |
1960 | pr_info("could not allocate ivdata\n"); | |
1961 | goto out; | |
1962 | } | |
1963 | get_random_bytes(ivdata, 16); | |
1964 | ||
1965 | /* Input data will be random */ | |
1966 | scratchpad = kmalloc(16, GFP_KERNEL); | |
1967 | if (!scratchpad) { | |
1968 | pr_info("could not allocate scratchpad\n"); | |
1969 | goto out; | |
1970 | } | |
1971 | get_random_bytes(scratchpad, 16); | |
1972 | ||
ba871e1d SM |
1973 | sk.tfm = skcipher; |
1974 | sk.req = req; | |
7d12993e SM |
1975 | |
1976 | /* We encrypt one block */ | |
ba871e1d SM |
1977 | sg_init_one(&sk.sg, scratchpad, 16); |
1978 | skcipher_request_set_crypt(req, &sk.sg, &sk.sg, 16, ivdata); | |
1979 | init_completion(&sk.result.completion); | |
7d12993e SM |
1980 | |
1981 | /* encrypt data */ | |
ba871e1d | 1982 | ret = test_skcipher_encdec(&sk, 1); |
7d12993e SM |
1983 | if (ret) |
1984 | goto out; | |
1985 | ||
1986 | pr_info("Encryption triggered successfully\n"); | |
1987 | ||
1988 | out: | |
ba871e1d SM |
1989 | if (skcipher) |
1990 | crypto_free_skcipher(skcipher); | |
7d12993e | 1991 | if (req) |
ba871e1d | 1992 | skcipher_request_free(req); |
7d12993e SM |
1993 | if (ivdata) |
1994 | kfree(ivdata); | |
1995 | if (scratchpad) | |
1996 | kfree(scratchpad); | |
1997 | return ret; | |
1998 | } | |
1999 | </programlisting> | |
2000 | </sect1> | |
2001 | ||
7d12993e SM |
2002 | <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> |
2003 | <programlisting> | |
2004 | ||
2005 | struct sdesc { | |
2006 | struct shash_desc shash; | |
2007 | char ctx[]; | |
2008 | }; | |
2009 | ||
2010 | static struct sdescinit_sdesc(struct crypto_shash *alg) | |
2011 | { | |
2012 | struct sdescsdesc; | |
2013 | int size; | |
2014 | ||
2015 | size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); | |
2016 | sdesc = kmalloc(size, GFP_KERNEL); | |
2017 | if (!sdesc) | |
2018 | return ERR_PTR(-ENOMEM); | |
2019 | sdesc->shash.tfm = alg; | |
2020 | sdesc->shash.flags = 0x0; | |
2021 | return sdesc; | |
2022 | } | |
2023 | ||
2024 | static int calc_hash(struct crypto_shashalg, | |
2025 | const unsigned chardata, unsigned int datalen, | |
2026 | unsigned chardigest) { | |
2027 | struct sdescsdesc; | |
2028 | int ret; | |
2029 | ||
2030 | sdesc = init_sdesc(alg); | |
2031 | if (IS_ERR(sdesc)) { | |
2032 | pr_info("trusted_key: can't alloc %s\n", hash_alg); | |
2033 | return PTR_ERR(sdesc); | |
2034 | } | |
2035 | ||
2036 | ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); | |
2037 | kfree(sdesc); | |
2038 | return ret; | |
2039 | } | |
2040 | </programlisting> | |
2041 | </sect1> | |
2042 | ||
2043 | <sect1><title>Code Example For Random Number Generator Usage</title> | |
2044 | <programlisting> | |
2045 | ||
2046 | static int get_random_numbers(u8 *buf, unsigned int len) | |
2047 | { | |
2048 | struct crypto_rngrng = NULL; | |
2049 | chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ | |
2050 | int ret; | |
2051 | ||
2052 | if (!buf || !len) { | |
2053 | pr_debug("No output buffer provided\n"); | |
2054 | return -EINVAL; | |
2055 | } | |
2056 | ||
2057 | rng = crypto_alloc_rng(drbg, 0, 0); | |
2058 | if (IS_ERR(rng)) { | |
2059 | pr_debug("could not allocate RNG handle for %s\n", drbg); | |
2060 | return -PTR_ERR(rng); | |
2061 | } | |
2062 | ||
2063 | ret = crypto_rng_get_bytes(rng, buf, len); | |
2064 | if (ret < 0) | |
2065 | pr_debug("generation of random numbers failed\n"); | |
2066 | else if (ret == 0) | |
2067 | pr_debug("RNG returned no data"); | |
2068 | else | |
2069 | pr_debug("RNG returned %d bytes of data\n", ret); | |
2070 | ||
2071 | out: | |
2072 | crypto_free_rng(rng); | |
2073 | return ret; | |
2074 | } | |
2075 | </programlisting> | |
2076 | </sect1> | |
2077 | </chapter> | |
2078 | </book> |