]>
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 | |
122 | interchangably. | |
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> | |
351 | <para>blkcipher for synchronous block ciphers</para> | |
352 | </listitem> | |
353 | <listitem> | |
354 | <para>ablkcipher for asynchronous block ciphers</para> | |
355 | </listitem> | |
356 | <listitem> | |
357 | <para>cipher for single block ciphers that may be used with | |
358 | an additional template</para> | |
359 | </listitem> | |
360 | <listitem> | |
361 | <para>shash for synchronous message digest</para> | |
362 | </listitem> | |
363 | <listitem> | |
364 | <para>ahash for asynchronous message digest</para> | |
365 | </listitem> | |
366 | <listitem> | |
367 | <para>aead for AEAD cipher type</para> | |
368 | </listitem> | |
369 | <listitem> | |
370 | <para>compression for compression type transformations</para> | |
371 | </listitem> | |
372 | <listitem> | |
373 | <para>rng for random number generator</para> | |
374 | </listitem> | |
375 | <listitem> | |
376 | <para>givcipher for cipher with associated IV generator | |
377 | (see the geniv entry below for the specification of the | |
378 | IV generator type used by the cipher implementation)</para> | |
379 | </listitem> | |
380 | </itemizedlist> | |
381 | </para> | |
382 | </listitem> | |
383 | <listitem> | |
384 | <para>blocksize: blocksize of cipher in bytes</para> | |
385 | </listitem> | |
386 | <listitem> | |
387 | <para>keysize: key size in bytes</para> | |
388 | </listitem> | |
389 | <listitem> | |
390 | <para>ivsize: IV size in bytes</para> | |
391 | </listitem> | |
392 | <listitem> | |
393 | <para>seedsize: required size of seed data for random number | |
394 | generator</para> | |
395 | </listitem> | |
396 | <listitem> | |
397 | <para>digestsize: output size of the message digest</para> | |
398 | </listitem> | |
399 | <listitem> | |
400 | <para>geniv: IV generation type: | |
401 | <itemizedlist> | |
402 | <listitem> | |
403 | <para>eseqiv for encrypted sequence number based IV | |
404 | generation</para> | |
405 | </listitem> | |
406 | <listitem> | |
407 | <para>seqiv for sequence number based IV generation</para> | |
408 | </listitem> | |
409 | <listitem> | |
410 | <para>chainiv for chain iv generation</para> | |
411 | </listitem> | |
412 | <listitem> | |
413 | <para><builtin> is a marker that the cipher implements | |
414 | IV generation and handling as it is specific to the given | |
415 | cipher</para> | |
416 | </listitem> | |
417 | </itemizedlist> | |
418 | </para> | |
419 | </listitem> | |
420 | </itemizedlist> | |
421 | </sect1> | |
422 | ||
423 | <sect1><title>Key Sizes</title> | |
424 | <para> | |
425 | When allocating a cipher handle, the caller only specifies the | |
426 | cipher type. Symmetric ciphers, however, typically support | |
427 | multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256). | |
428 | These key sizes are determined with the length of the provided | |
429 | key. Thus, the kernel crypto API does not provide a separate | |
430 | way to select the particular symmetric cipher key size. | |
431 | </para> | |
432 | </sect1> | |
433 | ||
434 | <sect1><title>Cipher Allocation Type And Masks</title> | |
435 | <para> | |
436 | The different cipher handle allocation functions allow the | |
437 | specification of a type and mask flag. Both parameters have | |
438 | the following meaning (and are therefore not covered in the | |
439 | subsequent sections). | |
440 | </para> | |
441 | ||
442 | <para> | |
443 | The type flag specifies the type of the cipher algorithm. | |
444 | The caller usually provides a 0 when the caller wants the | |
445 | default handling. Otherwise, the caller may provide the | |
446 | following selections which match the the aforementioned | |
447 | cipher types: | |
448 | </para> | |
449 | ||
450 | <itemizedlist> | |
451 | <listitem> | |
452 | <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para> | |
453 | </listitem> | |
454 | <listitem> | |
455 | <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para> | |
456 | </listitem> | |
457 | <listitem> | |
458 | <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with | |
459 | Associated Data (MAC)</para> | |
460 | </listitem> | |
461 | <listitem> | |
462 | <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para> | |
463 | </listitem> | |
464 | <listitem> | |
465 | <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para> | |
466 | </listitem> | |
467 | <listitem> | |
468 | <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block | |
469 | cipher packed together with an IV generator (see geniv field | |
470 | in the /proc/crypto listing for the known IV generators)</para> | |
471 | </listitem> | |
472 | <listitem> | |
473 | <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para> | |
474 | </listitem> | |
475 | <listitem> | |
476 | <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para> | |
477 | </listitem> | |
478 | <listitem> | |
479 | <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para> | |
480 | </listitem> | |
481 | <listitem> | |
482 | <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para> | |
483 | </listitem> | |
484 | <listitem> | |
485 | <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> | |
486 | </listitem> | |
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 SM |
587 | | aead | <----------------------------------- esp_output |
588 | | (seqniv) | ---+ | |
7b24d97f SM |
589 | +-----------+ | |
590 | | (2) | |
591 | +-----------+ | | |
592 | | | <--+ (2) | |
593 | | aead | <----------------------------------- esp_input | |
594 | | (gcm) | ------------+ | |
595 | +-----------+ | | |
596 | | (3) | (5) | |
597 | v v | |
598 | +-----------+ +-----------+ | |
599 | | | | | | |
600 | | ablkcipher| | ahash | | |
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> | |
661 | The GCM AEAD cipher type implementation now invokes the ABLKCIPHER API | |
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> | |
672 | That means that the ABLKCIPHER implementation of CTR(AES) only | |
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> | |
680 | The ABLKCIPHER of CTR(AES) now invokes the CIPHER API with the AES | |
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 | |
709 | step (4) is used and the ABLKCIPHER block chaining mode is CBC. | |
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 | ||
907 | <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title> | |
908 | <para> | |
909 | Example of transformations: cbc(aes), ecb(arc4), ... | |
910 | </para> | |
911 | ||
912 | <para> | |
913 | This section describes the multi-block cipher transformation | |
914 | implementations for both synchronous [BLKCIPHER] and | |
915 | asynchronous [ABLKCIPHER] case. The multi-block ciphers are | |
916 | used for transformations which operate on scatterlists of | |
917 | data supplied to the transformation functions. They output | |
918 | the result into a scatterlist of data as well. | |
919 | </para> | |
920 | ||
921 | <sect2><title>Registration Specifics</title> | |
922 | ||
923 | <para> | |
924 | The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms | |
925 | is one of the most standard procedures throughout the crypto API. | |
926 | </para> | |
927 | ||
928 | <para> | |
929 | Note, if a cipher implementation requires a proper alignment | |
930 | of data, the caller should use the functions of | |
931 | crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask() | |
932 | respectively to identify a memory alignment mask. The kernel | |
933 | crypto API is able to process requests that are unaligned. | |
934 | This implies, however, additional overhead as the kernel | |
935 | crypto API needs to perform the realignment of the data which | |
936 | may imply moving of data. | |
937 | </para> | |
938 | </sect2> | |
939 | ||
940 | <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title> | |
941 | <para> | |
942 | Struct blkcipher_alg defines a synchronous block cipher whereas | |
943 | struct ablkcipher_alg defines an asynchronous block cipher. | |
944 | </para> | |
945 | ||
946 | <para> | |
947 | Please refer to the single block cipher description for schematics | |
948 | of the block cipher usage. The usage patterns are exactly the same | |
949 | for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER]. | |
950 | </para> | |
951 | </sect2> | |
952 | ||
953 | <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title> | |
954 | <para> | |
955 | There are a couple of specifics to the [ABLKCIPHER] interface. | |
956 | </para> | |
957 | ||
958 | <para> | |
959 | First of all, some of the drivers will want to use the | |
960 | Generic ScatterWalk in case the hardware needs to be fed | |
961 | separate chunks of the scatterlist which contains the | |
962 | plaintext and will contain the ciphertext. Please refer | |
963 | to the ScatterWalk interface offered by the Linux kernel | |
964 | scatter / gather list implementation. | |
965 | </para> | |
966 | </sect2> | |
967 | </sect1> | |
968 | ||
969 | <sect1><title>Hashing [HASH]</title> | |
970 | ||
971 | <para> | |
972 | Example of transformations: crc32, md5, sha1, sha256,... | |
973 | </para> | |
974 | ||
975 | <sect2><title>Registering And Unregistering The Transformation</title> | |
976 | ||
977 | <para> | |
978 | There are multiple ways to register a HASH transformation, | |
979 | depending on whether the transformation is synchronous [SHASH] | |
980 | or asynchronous [AHASH] and the amount of HASH transformations | |
981 | we are registering. You can find the prototypes defined in | |
982 | include/crypto/internal/hash.h: | |
983 | </para> | |
984 | ||
985 | <programlisting> | |
986 | int crypto_register_ahash(struct ahash_alg *alg); | |
987 | ||
988 | int crypto_register_shash(struct shash_alg *alg); | |
989 | int crypto_register_shashes(struct shash_alg *algs, int count); | |
990 | </programlisting> | |
991 | ||
992 | <para> | |
993 | The respective counterparts for unregistering the HASH | |
994 | transformation are as follows: | |
995 | </para> | |
996 | ||
997 | <programlisting> | |
998 | int crypto_unregister_ahash(struct ahash_alg *alg); | |
999 | ||
1000 | int crypto_unregister_shash(struct shash_alg *alg); | |
1001 | int crypto_unregister_shashes(struct shash_alg *algs, int count); | |
1002 | </programlisting> | |
1003 | </sect2> | |
1004 | ||
1005 | <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title> | |
1006 | <para> | |
1007 | Here are schematics of how these functions are called when | |
1008 | operated from other part of the kernel. Note that the .setkey() | |
1009 | call might happen before or after any of these schematics happen, | |
1010 | but must not happen during any of these are in-flight. Please note | |
1011 | that calling .init() followed immediately by .finish() is also a | |
1012 | perfectly valid transformation. | |
1013 | </para> | |
1014 | ||
1015 | <programlisting> | |
1016 | I) DATA -----------. | |
1017 | v | |
1018 | .init() -> .update() -> .final() ! .update() might not be called | |
1019 | ^ | | at all in this scenario. | |
1020 | '----' '---> HASH | |
1021 | ||
1022 | II) DATA -----------.-----------. | |
1023 | v v | |
1024 | .init() -> .update() -> .finup() ! .update() may not be called | |
1025 | ^ | | at all in this scenario. | |
1026 | '----' '---> HASH | |
1027 | ||
1028 | III) DATA -----------. | |
1029 | v | |
1030 | .digest() ! The entire process is handled | |
1031 | | by the .digest() call. | |
1032 | '---------------> HASH | |
1033 | </programlisting> | |
1034 | ||
1035 | <para> | |
1036 | Here is a schematic of how the .export()/.import() functions are | |
1037 | called when used from another part of the kernel. | |
1038 | </para> | |
1039 | ||
1040 | <programlisting> | |
1041 | KEY--. DATA--. | |
1042 | v v ! .update() may not be called | |
1043 | .setkey() -> .init() -> .update() -> .export() at all in this scenario. | |
1044 | ^ | | | |
1045 | '-----' '--> PARTIAL_HASH | |
1046 | ||
1047 | ----------- other transformations happen here ----------- | |
1048 | ||
1049 | PARTIAL_HASH--. DATA1--. | |
1050 | v v | |
1051 | .import -> .update() -> .final() ! .update() may not be called | |
1052 | ^ | | at all in this scenario. | |
1053 | '----' '--> HASH1 | |
1054 | ||
1055 | PARTIAL_HASH--. DATA2-. | |
1056 | v v | |
1057 | .import -> .finup() | |
1058 | | | |
1059 | '---------------> HASH2 | |
1060 | </programlisting> | |
1061 | </sect2> | |
1062 | ||
1063 | <sect2><title>Specifics Of Asynchronous HASH Transformation</title> | |
1064 | <para> | |
1065 | Some of the drivers will want to use the Generic ScatterWalk | |
1066 | in case the implementation needs to be fed separate chunks of the | |
1067 | scatterlist which contains the input data. The buffer containing | |
1068 | the resulting hash will always be properly aligned to | |
1069 | .cra_alignmask so there is no need to worry about this. | |
1070 | </para> | |
1071 | </sect2> | |
1072 | </sect1> | |
1073 | </chapter> | |
1074 | ||
dbe5fe7e SM |
1075 | <chapter id="User"><title>User Space Interface</title> |
1076 | <sect1><title>Introduction</title> | |
1077 | <para> | |
1078 | The concepts of the kernel crypto API visible to kernel space is fully | |
1079 | applicable to the user space interface as well. Therefore, the kernel | |
1080 | crypto API high level discussion for the in-kernel use cases applies | |
1081 | here as well. | |
1082 | </para> | |
1083 | ||
1084 | <para> | |
1085 | The major difference, however, is that user space can only act as a | |
1086 | consumer and never as a provider of a transformation or cipher algorithm. | |
1087 | </para> | |
1088 | ||
1089 | <para> | |
1090 | The following covers the user space interface exported by the kernel | |
1091 | crypto API. A working example of this description is libkcapi that | |
1092 | can be obtained from [1]. That library can be used by user space | |
1093 | applications that require cryptographic services from the kernel. | |
1094 | </para> | |
1095 | ||
1096 | <para> | |
1097 | Some details of the in-kernel kernel crypto API aspects do not | |
1098 | apply to user space, however. This includes the difference between | |
1099 | synchronous and asynchronous invocations. The user space API call | |
1100 | is fully synchronous. | |
1101 | </para> | |
1102 | ||
1103 | <para> | |
1104 | [1] http://www.chronox.de/libkcapi.html | |
1105 | </para> | |
1106 | ||
1107 | </sect1> | |
1108 | ||
1109 | <sect1><title>User Space API General Remarks</title> | |
1110 | <para> | |
1111 | The kernel crypto API is accessible from user space. Currently, | |
1112 | the following ciphers are accessible: | |
1113 | </para> | |
1114 | ||
1115 | <itemizedlist> | |
1116 | <listitem> | |
1117 | <para>Message digest including keyed message digest (HMAC, CMAC)</para> | |
1118 | </listitem> | |
1119 | ||
1120 | <listitem> | |
1121 | <para>Symmetric ciphers</para> | |
1122 | </listitem> | |
1123 | ||
1124 | <listitem> | |
1125 | <para>AEAD ciphers</para> | |
1126 | </listitem> | |
1127 | ||
1128 | <listitem> | |
1129 | <para>Random Number Generators</para> | |
1130 | </listitem> | |
1131 | </itemizedlist> | |
1132 | ||
1133 | <para> | |
1134 | The interface is provided via socket type using the type AF_ALG. | |
1135 | In addition, the setsockopt option type is SOL_ALG. In case the | |
1136 | user space header files do not export these flags yet, use the | |
1137 | following macros: | |
1138 | </para> | |
1139 | ||
1140 | <programlisting> | |
1141 | #ifndef AF_ALG | |
1142 | #define AF_ALG 38 | |
1143 | #endif | |
1144 | #ifndef SOL_ALG | |
1145 | #define SOL_ALG 279 | |
1146 | #endif | |
1147 | </programlisting> | |
1148 | ||
1149 | <para> | |
1150 | A cipher is accessed with the same name as done for the in-kernel | |
1151 | API calls. This includes the generic vs. unique naming schema for | |
1152 | ciphers as well as the enforcement of priorities for generic names. | |
1153 | </para> | |
1154 | ||
1155 | <para> | |
1156 | To interact with the kernel crypto API, a socket must be | |
1157 | created by the user space application. User space invokes the cipher | |
1158 | operation with the send()/write() system call family. The result of the | |
1159 | cipher operation is obtained with the read()/recv() system call family. | |
1160 | </para> | |
1161 | ||
1162 | <para> | |
1163 | The following API calls assume that the socket descriptor | |
1164 | is already opened by the user space application and discusses only | |
1165 | the kernel crypto API specific invocations. | |
1166 | </para> | |
1167 | ||
1168 | <para> | |
1169 | To initialize the socket interface, the following sequence has to | |
1170 | be performed by the consumer: | |
1171 | </para> | |
1172 | ||
1173 | <orderedlist> | |
1174 | <listitem> | |
1175 | <para> | |
1176 | Create a socket of type AF_ALG with the struct sockaddr_alg | |
1177 | parameter specified below for the different cipher types. | |
1178 | </para> | |
1179 | </listitem> | |
1180 | ||
1181 | <listitem> | |
1182 | <para> | |
1183 | Invoke bind with the socket descriptor | |
1184 | </para> | |
1185 | </listitem> | |
1186 | ||
1187 | <listitem> | |
1188 | <para> | |
1189 | Invoke accept with the socket descriptor. The accept system call | |
1190 | returns a new file descriptor that is to be used to interact with | |
1191 | the particular cipher instance. When invoking send/write or recv/read | |
1192 | system calls to send data to the kernel or obtain data from the | |
1193 | kernel, the file descriptor returned by accept must be used. | |
1194 | </para> | |
1195 | </listitem> | |
1196 | </orderedlist> | |
1197 | </sect1> | |
1198 | ||
1199 | <sect1><title>In-place Cipher operation</title> | |
1200 | <para> | |
1201 | Just like the in-kernel operation of the kernel crypto API, the user | |
1202 | space interface allows the cipher operation in-place. That means that | |
1203 | the input buffer used for the send/write system call and the output | |
1204 | buffer used by the read/recv system call may be one and the same. | |
1205 | This is of particular interest for symmetric cipher operations where a | |
1206 | copying of the output data to its final destination can be avoided. | |
1207 | </para> | |
1208 | ||
1209 | <para> | |
1210 | If a consumer on the other hand wants to maintain the plaintext and | |
1211 | the ciphertext in different memory locations, all a consumer needs | |
1212 | to do is to provide different memory pointers for the encryption and | |
1213 | decryption operation. | |
1214 | </para> | |
1215 | </sect1> | |
1216 | ||
1217 | <sect1><title>Message Digest API</title> | |
1218 | <para> | |
1219 | The message digest type to be used for the cipher operation is | |
1220 | selected when invoking the bind syscall. bind requires the caller | |
1221 | to provide a filled struct sockaddr data structure. This data | |
1222 | structure must be filled as follows: | |
1223 | </para> | |
1224 | ||
1225 | <programlisting> | |
1226 | struct sockaddr_alg sa = { | |
1227 | .salg_family = AF_ALG, | |
1228 | .salg_type = "hash", /* this selects the hash logic in the kernel */ | |
1229 | .salg_name = "sha1" /* this is the cipher name */ | |
1230 | }; | |
1231 | </programlisting> | |
1232 | ||
1233 | <para> | |
1234 | The salg_type value "hash" applies to message digests and keyed | |
1235 | message digests. Though, a keyed message digest is referenced by | |
1236 | the appropriate salg_name. Please see below for the setsockopt | |
1237 | interface that explains how the key can be set for a keyed message | |
1238 | digest. | |
1239 | </para> | |
1240 | ||
1241 | <para> | |
1242 | Using the send() system call, the application provides the data that | |
1243 | should be processed with the message digest. The send system call | |
1244 | allows the following flags to be specified: | |
1245 | </para> | |
1246 | ||
1247 | <itemizedlist> | |
1248 | <listitem> | |
1249 | <para> | |
1250 | MSG_MORE: If this flag is set, the send system call acts like a | |
1251 | message digest update function where the final hash is not | |
1252 | yet calculated. If the flag is not set, the send system call | |
1253 | calculates the final message digest immediately. | |
1254 | </para> | |
1255 | </listitem> | |
1256 | </itemizedlist> | |
1257 | ||
1258 | <para> | |
1259 | With the recv() system call, the application can read the message | |
1260 | digest from the kernel crypto API. If the buffer is too small for the | |
1261 | message digest, the flag MSG_TRUNC is set by the kernel. | |
1262 | </para> | |
1263 | ||
1264 | <para> | |
1265 | In order to set a message digest key, the calling application must use | |
1266 | the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC | |
1267 | operation is performed without the initial HMAC state change caused by | |
1268 | the key. | |
1269 | </para> | |
1270 | </sect1> | |
1271 | ||
1272 | <sect1><title>Symmetric Cipher API</title> | |
1273 | <para> | |
1274 | The operation is very similar to the message digest discussion. | |
1275 | During initialization, the struct sockaddr data structure must be | |
1276 | filled as follows: | |
1277 | </para> | |
1278 | ||
1279 | <programlisting> | |
1280 | struct sockaddr_alg sa = { | |
1281 | .salg_family = AF_ALG, | |
1282 | .salg_type = "skcipher", /* this selects the symmetric cipher */ | |
1283 | .salg_name = "cbc(aes)" /* this is the cipher name */ | |
1284 | }; | |
1285 | </programlisting> | |
1286 | ||
1287 | <para> | |
1288 | Before data can be sent to the kernel using the write/send system | |
1289 | call family, the consumer must set the key. The key setting is | |
1290 | described with the setsockopt invocation below. | |
1291 | </para> | |
1292 | ||
1293 | <para> | |
1294 | Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is | |
1295 | specified with the data structure provided by the sendmsg() system call. | |
1296 | </para> | |
1297 | ||
1298 | <para> | |
1299 | The sendmsg system call parameter of struct msghdr is embedded into the | |
1300 | struct cmsghdr data structure. See recv(2) and cmsg(3) for more | |
1301 | information on how the cmsghdr data structure is used together with the | |
1302 | send/recv system call family. That cmsghdr data structure holds the | |
1303 | following information specified with a separate header instances: | |
1304 | </para> | |
1305 | ||
1306 | <itemizedlist> | |
1307 | <listitem> | |
1308 | <para> | |
1309 | specification of the cipher operation type with one of these flags: | |
1310 | </para> | |
1311 | <itemizedlist> | |
1312 | <listitem> | |
1313 | <para>ALG_OP_ENCRYPT - encryption of data</para> | |
1314 | </listitem> | |
1315 | <listitem> | |
1316 | <para>ALG_OP_DECRYPT - decryption of data</para> | |
1317 | </listitem> | |
1318 | </itemizedlist> | |
1319 | </listitem> | |
1320 | ||
1321 | <listitem> | |
1322 | <para> | |
1323 | specification of the IV information marked with the flag ALG_SET_IV | |
1324 | </para> | |
1325 | </listitem> | |
1326 | </itemizedlist> | |
1327 | ||
1328 | <para> | |
1329 | The send system call family allows the following flag to be specified: | |
1330 | </para> | |
1331 | ||
1332 | <itemizedlist> | |
1333 | <listitem> | |
1334 | <para> | |
1335 | MSG_MORE: If this flag is set, the send system call acts like a | |
1336 | cipher update function where more input data is expected | |
1337 | with a subsequent invocation of the send system call. | |
1338 | </para> | |
1339 | </listitem> | |
1340 | </itemizedlist> | |
1341 | ||
1342 | <para> | |
1343 | Note: The kernel reports -EINVAL for any unexpected data. The caller | |
1344 | must make sure that all data matches the constraints given in | |
1345 | /proc/crypto for the selected cipher. | |
1346 | </para> | |
1347 | ||
1348 | <para> | |
1349 | With the recv() system call, the application can read the result of | |
1350 | the cipher operation from the kernel crypto API. The output buffer | |
1351 | must be at least as large as to hold all blocks of the encrypted or | |
1352 | decrypted data. If the output data size is smaller, only as many | |
1353 | blocks are returned that fit into that output buffer size. | |
1354 | </para> | |
1355 | </sect1> | |
1356 | ||
1357 | <sect1><title>AEAD Cipher API</title> | |
1358 | <para> | |
1359 | The operation is very similar to the symmetric cipher discussion. | |
1360 | During initialization, the struct sockaddr data structure must be | |
1361 | filled as follows: | |
1362 | </para> | |
1363 | ||
1364 | <programlisting> | |
1365 | struct sockaddr_alg sa = { | |
1366 | .salg_family = AF_ALG, | |
1367 | .salg_type = "aead", /* this selects the symmetric cipher */ | |
1368 | .salg_name = "gcm(aes)" /* this is the cipher name */ | |
1369 | }; | |
1370 | </programlisting> | |
1371 | ||
1372 | <para> | |
1373 | Before data can be sent to the kernel using the write/send system | |
1374 | call family, the consumer must set the key. The key setting is | |
1375 | described with the setsockopt invocation below. | |
1376 | </para> | |
1377 | ||
1378 | <para> | |
1379 | In addition, before data can be sent to the kernel using the | |
1380 | write/send system call family, the consumer must set the authentication | |
1381 | tag size. To set the authentication tag size, the caller must use the | |
1382 | setsockopt invocation described below. | |
1383 | </para> | |
1384 | ||
1385 | <para> | |
1386 | Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is | |
1387 | specified with the data structure provided by the sendmsg() system call. | |
1388 | </para> | |
1389 | ||
1390 | <para> | |
1391 | The sendmsg system call parameter of struct msghdr is embedded into the | |
1392 | struct cmsghdr data structure. See recv(2) and cmsg(3) for more | |
1393 | information on how the cmsghdr data structure is used together with the | |
1394 | send/recv system call family. That cmsghdr data structure holds the | |
1395 | following information specified with a separate header instances: | |
1396 | </para> | |
1397 | ||
1398 | <itemizedlist> | |
1399 | <listitem> | |
1400 | <para> | |
1401 | specification of the cipher operation type with one of these flags: | |
1402 | </para> | |
1403 | <itemizedlist> | |
1404 | <listitem> | |
1405 | <para>ALG_OP_ENCRYPT - encryption of data</para> | |
1406 | </listitem> | |
1407 | <listitem> | |
1408 | <para>ALG_OP_DECRYPT - decryption of data</para> | |
1409 | </listitem> | |
1410 | </itemizedlist> | |
1411 | </listitem> | |
1412 | ||
1413 | <listitem> | |
1414 | <para> | |
1415 | specification of the IV information marked with the flag ALG_SET_IV | |
1416 | </para> | |
1417 | </listitem> | |
1418 | ||
1419 | <listitem> | |
1420 | <para> | |
1421 | specification of the associated authentication data (AAD) with the | |
1422 | flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together | |
1423 | with the plaintext / ciphertext. See below for the memory structure. | |
1424 | </para> | |
1425 | </listitem> | |
1426 | </itemizedlist> | |
1427 | ||
1428 | <para> | |
1429 | The send system call family allows the following flag to be specified: | |
1430 | </para> | |
1431 | ||
1432 | <itemizedlist> | |
1433 | <listitem> | |
1434 | <para> | |
1435 | MSG_MORE: If this flag is set, the send system call acts like a | |
1436 | cipher update function where more input data is expected | |
1437 | with a subsequent invocation of the send system call. | |
1438 | </para> | |
1439 | </listitem> | |
1440 | </itemizedlist> | |
1441 | ||
1442 | <para> | |
1443 | Note: The kernel reports -EINVAL for any unexpected data. The caller | |
1444 | must make sure that all data matches the constraints given in | |
1445 | /proc/crypto for the selected cipher. | |
1446 | </para> | |
1447 | ||
1448 | <para> | |
1449 | With the recv() system call, the application can read the result of | |
1450 | the cipher operation from the kernel crypto API. The output buffer | |
1451 | must be at least as large as defined with the memory structure below. | |
1452 | If the output data size is smaller, the cipher operation is not performed. | |
1453 | </para> | |
1454 | ||
1455 | <para> | |
1456 | The authenticated decryption operation may indicate an integrity error. | |
1457 | Such breach in integrity is marked with the -EBADMSG error code. | |
1458 | </para> | |
1459 | ||
1460 | <sect2><title>AEAD Memory Structure</title> | |
1461 | <para> | |
1462 | The AEAD cipher operates with the following information that | |
1463 | is communicated between user and kernel space as one data stream: | |
1464 | </para> | |
1465 | ||
1466 | <itemizedlist> | |
1467 | <listitem> | |
1468 | <para>plaintext or ciphertext</para> | |
1469 | </listitem> | |
1470 | ||
1471 | <listitem> | |
1472 | <para>associated authentication data (AAD)</para> | |
1473 | </listitem> | |
1474 | ||
1475 | <listitem> | |
1476 | <para>authentication tag</para> | |
1477 | </listitem> | |
1478 | </itemizedlist> | |
1479 | ||
1480 | <para> | |
1481 | The sizes of the AAD and the authentication tag are provided with | |
1482 | the sendmsg and setsockopt calls (see there). As the kernel knows | |
1483 | the size of the entire data stream, the kernel is now able to | |
1484 | calculate the right offsets of the data components in the data | |
1485 | stream. | |
1486 | </para> | |
1487 | ||
1488 | <para> | |
1489 | The user space caller must arrange the aforementioned information | |
1490 | in the following order: | |
1491 | </para> | |
1492 | ||
1493 | <itemizedlist> | |
1494 | <listitem> | |
1495 | <para> | |
1496 | AEAD encryption input: AAD || plaintext | |
1497 | </para> | |
1498 | </listitem> | |
1499 | ||
1500 | <listitem> | |
1501 | <para> | |
1502 | AEAD decryption input: AAD || ciphertext || authentication tag | |
1503 | </para> | |
1504 | </listitem> | |
1505 | </itemizedlist> | |
1506 | ||
1507 | <para> | |
1508 | The output buffer the user space caller provides must be at least as | |
1509 | large to hold the following data: | |
1510 | </para> | |
1511 | ||
1512 | <itemizedlist> | |
1513 | <listitem> | |
1514 | <para> | |
1515 | AEAD encryption output: ciphertext || authentication tag | |
1516 | </para> | |
1517 | </listitem> | |
1518 | ||
1519 | <listitem> | |
1520 | <para> | |
1521 | AEAD decryption output: plaintext | |
1522 | </para> | |
1523 | </listitem> | |
1524 | </itemizedlist> | |
1525 | </sect2> | |
1526 | </sect1> | |
1527 | ||
1528 | <sect1><title>Random Number Generator API</title> | |
1529 | <para> | |
1530 | Again, the operation is very similar to the other APIs. | |
1531 | During initialization, the struct sockaddr data structure must be | |
1532 | filled as follows: | |
1533 | </para> | |
1534 | ||
1535 | <programlisting> | |
1536 | struct sockaddr_alg sa = { | |
1537 | .salg_family = AF_ALG, | |
1538 | .salg_type = "rng", /* this selects the symmetric cipher */ | |
1539 | .salg_name = "drbg_nopr_sha256" /* this is the cipher name */ | |
1540 | }; | |
1541 | </programlisting> | |
1542 | ||
1543 | <para> | |
1544 | Depending on the RNG type, the RNG must be seeded. The seed is provided | |
1545 | using the setsockopt interface to set the key. For example, the | |
1546 | ansi_cprng requires a seed. The DRBGs do not require a seed, but | |
1547 | may be seeded. | |
1548 | </para> | |
1549 | ||
1550 | <para> | |
1551 | Using the read()/recvmsg() system calls, random numbers can be obtained. | |
1552 | The kernel generates at most 128 bytes in one call. If user space | |
1553 | requires more data, multiple calls to read()/recvmsg() must be made. | |
1554 | </para> | |
1555 | ||
1556 | <para> | |
1557 | WARNING: The user space caller may invoke the initially mentioned | |
1558 | accept system call multiple times. In this case, the returned file | |
1559 | descriptors have the same state. | |
1560 | </para> | |
1561 | ||
1562 | </sect1> | |
1563 | ||
1564 | <sect1><title>Zero-Copy Interface</title> | |
1565 | <para> | |
1566 | In addition to the send/write/read/recv system call familty, the AF_ALG | |
1567 | interface can be accessed with the zero-copy interface of splice/vmsplice. | |
1568 | As the name indicates, the kernel tries to avoid a copy operation into | |
1569 | kernel space. | |
1570 | </para> | |
1571 | ||
1572 | <para> | |
1573 | The zero-copy operation requires data to be aligned at the page boundary. | |
1574 | Non-aligned data can be used as well, but may require more operations of | |
1575 | the kernel which would defeat the speed gains obtained from the zero-copy | |
1576 | interface. | |
1577 | </para> | |
1578 | ||
1579 | <para> | |
1580 | The system-interent limit for the size of one zero-copy operation is | |
1581 | 16 pages. If more data is to be sent to AF_ALG, user space must slice | |
1582 | the input into segments with a maximum size of 16 pages. | |
1583 | </para> | |
1584 | ||
1585 | <para> | |
1586 | Zero-copy can be used with the following code example (a complete working | |
1587 | example is provided with libkcapi): | |
1588 | </para> | |
1589 | ||
1590 | <programlisting> | |
1591 | int pipes[2]; | |
1592 | ||
1593 | pipe(pipes); | |
1594 | /* input data in iov */ | |
1595 | vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT); | |
1596 | /* opfd is the file descriptor returned from accept() system call */ | |
1597 | splice(pipes[0], NULL, opfd, NULL, ret, 0); | |
1598 | read(opfd, out, outlen); | |
1599 | </programlisting> | |
1600 | ||
1601 | </sect1> | |
1602 | ||
1603 | <sect1><title>Setsockopt Interface</title> | |
1604 | <para> | |
1605 | In addition to the read/recv and send/write system call handling | |
1606 | to send and retrieve data subject to the cipher operation, a consumer | |
1607 | also needs to set the additional information for the cipher operation. | |
1608 | This additional information is set using the setsockopt system call | |
1609 | that must be invoked with the file descriptor of the open cipher | |
1610 | (i.e. the file descriptor returned by the accept system call). | |
1611 | </para> | |
1612 | ||
1613 | <para> | |
1614 | Each setsockopt invocation must use the level SOL_ALG. | |
1615 | </para> | |
1616 | ||
1617 | <para> | |
1618 | The setsockopt interface allows setting the following data using | |
1619 | the mentioned optname: | |
1620 | </para> | |
1621 | ||
1622 | <itemizedlist> | |
1623 | <listitem> | |
1624 | <para> | |
1625 | ALG_SET_KEY -- Setting the key. Key setting is applicable to: | |
1626 | </para> | |
1627 | <itemizedlist> | |
1628 | <listitem> | |
1629 | <para>the skcipher cipher type (symmetric ciphers)</para> | |
1630 | </listitem> | |
1631 | <listitem> | |
1632 | <para>the hash cipher type (keyed message digests)</para> | |
1633 | </listitem> | |
1634 | <listitem> | |
1635 | <para>the AEAD cipher type</para> | |
1636 | </listitem> | |
1637 | <listitem> | |
1638 | <para>the RNG cipher type to provide the seed</para> | |
1639 | </listitem> | |
1640 | </itemizedlist> | |
1641 | </listitem> | |
1642 | ||
1643 | <listitem> | |
1644 | <para> | |
1645 | ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size | |
1646 | for AEAD ciphers. For a encryption operation, the authentication | |
1647 | tag of the given size will be generated. For a decryption operation, | |
1648 | the provided ciphertext is assumed to contain an authentication tag | |
1649 | of the given size (see section about AEAD memory layout below). | |
1650 | </para> | |
1651 | </listitem> | |
1652 | </itemizedlist> | |
1653 | ||
1654 | </sect1> | |
1655 | ||
1656 | <sect1><title>User space API example</title> | |
1657 | <para> | |
1658 | Please see [1] for libkcapi which provides an easy-to-use wrapper | |
1659 | around the aforementioned Netlink kernel interface. [1] also contains | |
1660 | a test application that invokes all libkcapi API calls. | |
1661 | </para> | |
1662 | ||
1663 | <para> | |
1664 | [1] http://www.chronox.de/libkcapi.html | |
1665 | </para> | |
1666 | ||
1667 | </sect1> | |
1668 | ||
1669 | </chapter> | |
1670 | ||
7d12993e | 1671 | <chapter id="API"><title>Programming Interface</title> |
addfda2f SM |
1672 | <para> |
1673 | Please note that the kernel crypto API contains the AEAD givcrypt | |
1674 | API (crypto_aead_giv* and aead_givcrypt_* function calls in | |
1675 | include/crypto/aead.h). This API is obsolete and will be removed | |
1676 | in the future. To obtain the functionality of an AEAD cipher with | |
1677 | internal IV generation, use the IV generator as a regular cipher. | |
1678 | For example, rfc4106(gcm(aes)) is the AEAD cipher with external | |
1679 | IV generation and seqniv(rfc4106(gcm(aes))) implies that the kernel | |
1680 | crypto API generates the IV. Different IV generators are available. | |
1681 | </para> | |
7d12993e SM |
1682 | <sect1><title>Block Cipher Context Data Structures</title> |
1683 | !Pinclude/linux/crypto.h Block Cipher Context Data Structures | |
05767229 | 1684 | !Finclude/crypto/aead.h aead_request |
7d12993e SM |
1685 | </sect1> |
1686 | <sect1><title>Block Cipher Algorithm Definitions</title> | |
1687 | !Pinclude/linux/crypto.h Block Cipher Algorithm Definitions | |
1688 | !Finclude/linux/crypto.h crypto_alg | |
1689 | !Finclude/linux/crypto.h ablkcipher_alg | |
1690 | !Finclude/linux/crypto.h aead_alg | |
1691 | !Finclude/linux/crypto.h blkcipher_alg | |
1692 | !Finclude/linux/crypto.h cipher_alg | |
05767229 | 1693 | !Finclude/crypto/rng.h rng_alg |
7d12993e SM |
1694 | </sect1> |
1695 | <sect1><title>Asynchronous Block Cipher API</title> | |
1696 | !Pinclude/linux/crypto.h Asynchronous Block Cipher API | |
1697 | !Finclude/linux/crypto.h crypto_alloc_ablkcipher | |
1698 | !Finclude/linux/crypto.h crypto_free_ablkcipher | |
1699 | !Finclude/linux/crypto.h crypto_has_ablkcipher | |
1700 | !Finclude/linux/crypto.h crypto_ablkcipher_ivsize | |
1701 | !Finclude/linux/crypto.h crypto_ablkcipher_blocksize | |
1702 | !Finclude/linux/crypto.h crypto_ablkcipher_setkey | |
1703 | !Finclude/linux/crypto.h crypto_ablkcipher_reqtfm | |
1704 | !Finclude/linux/crypto.h crypto_ablkcipher_encrypt | |
1705 | !Finclude/linux/crypto.h crypto_ablkcipher_decrypt | |
1706 | </sect1> | |
1707 | <sect1><title>Asynchronous Cipher Request Handle</title> | |
1708 | !Pinclude/linux/crypto.h Asynchronous Cipher Request Handle | |
1709 | !Finclude/linux/crypto.h crypto_ablkcipher_reqsize | |
1710 | !Finclude/linux/crypto.h ablkcipher_request_set_tfm | |
1711 | !Finclude/linux/crypto.h ablkcipher_request_alloc | |
1712 | !Finclude/linux/crypto.h ablkcipher_request_free | |
1713 | !Finclude/linux/crypto.h ablkcipher_request_set_callback | |
1714 | !Finclude/linux/crypto.h ablkcipher_request_set_crypt | |
1715 | </sect1> | |
1716 | <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title> | |
05767229 SM |
1717 | !Pinclude/crypto/aead.h Authenticated Encryption With Associated Data (AEAD) Cipher API |
1718 | !Finclude/crypto/aead.h crypto_alloc_aead | |
1719 | !Finclude/crypto/aead.h crypto_free_aead | |
1720 | !Finclude/crypto/aead.h crypto_aead_ivsize | |
1721 | !Finclude/crypto/aead.h crypto_aead_authsize | |
1722 | !Finclude/crypto/aead.h crypto_aead_blocksize | |
1723 | !Finclude/crypto/aead.h crypto_aead_setkey | |
1724 | !Finclude/crypto/aead.h crypto_aead_setauthsize | |
1725 | !Finclude/crypto/aead.h crypto_aead_encrypt | |
1726 | !Finclude/crypto/aead.h crypto_aead_decrypt | |
7d12993e SM |
1727 | </sect1> |
1728 | <sect1><title>Asynchronous AEAD Request Handle</title> | |
05767229 SM |
1729 | !Pinclude/crypto/aead.h Asynchronous AEAD Request Handle |
1730 | !Finclude/crypto/aead.h crypto_aead_reqsize | |
1731 | !Finclude/crypto/aead.h aead_request_set_tfm | |
1732 | !Finclude/crypto/aead.h aead_request_alloc | |
1733 | !Finclude/crypto/aead.h aead_request_free | |
1734 | !Finclude/crypto/aead.h aead_request_set_callback | |
1735 | !Finclude/crypto/aead.h aead_request_set_crypt | |
1736 | !Finclude/crypto/aead.h aead_request_set_assoc | |
addfda2f | 1737 | !Finclude/crypto/aead.h aead_request_set_ad |
7d12993e SM |
1738 | </sect1> |
1739 | <sect1><title>Synchronous Block Cipher API</title> | |
1740 | !Pinclude/linux/crypto.h Synchronous Block Cipher API | |
1741 | !Finclude/linux/crypto.h crypto_alloc_blkcipher | |
1742 | !Finclude/linux/crypto.h crypto_free_blkcipher | |
1743 | !Finclude/linux/crypto.h crypto_has_blkcipher | |
1744 | !Finclude/linux/crypto.h crypto_blkcipher_name | |
1745 | !Finclude/linux/crypto.h crypto_blkcipher_ivsize | |
1746 | !Finclude/linux/crypto.h crypto_blkcipher_blocksize | |
1747 | !Finclude/linux/crypto.h crypto_blkcipher_setkey | |
1748 | !Finclude/linux/crypto.h crypto_blkcipher_encrypt | |
1749 | !Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv | |
1750 | !Finclude/linux/crypto.h crypto_blkcipher_decrypt | |
1751 | !Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv | |
1752 | !Finclude/linux/crypto.h crypto_blkcipher_set_iv | |
1753 | !Finclude/linux/crypto.h crypto_blkcipher_get_iv | |
1754 | </sect1> | |
1755 | <sect1><title>Single Block Cipher API</title> | |
1756 | !Pinclude/linux/crypto.h Single Block Cipher API | |
1757 | !Finclude/linux/crypto.h crypto_alloc_cipher | |
1758 | !Finclude/linux/crypto.h crypto_free_cipher | |
1759 | !Finclude/linux/crypto.h crypto_has_cipher | |
1760 | !Finclude/linux/crypto.h crypto_cipher_blocksize | |
1761 | !Finclude/linux/crypto.h crypto_cipher_setkey | |
1762 | !Finclude/linux/crypto.h crypto_cipher_encrypt_one | |
1763 | !Finclude/linux/crypto.h crypto_cipher_decrypt_one | |
1764 | </sect1> | |
1765 | <sect1><title>Synchronous Message Digest API</title> | |
1766 | !Pinclude/linux/crypto.h Synchronous Message Digest API | |
1767 | !Finclude/linux/crypto.h crypto_alloc_hash | |
1768 | !Finclude/linux/crypto.h crypto_free_hash | |
1769 | !Finclude/linux/crypto.h crypto_has_hash | |
1770 | !Finclude/linux/crypto.h crypto_hash_blocksize | |
1771 | !Finclude/linux/crypto.h crypto_hash_digestsize | |
1772 | !Finclude/linux/crypto.h crypto_hash_init | |
1773 | !Finclude/linux/crypto.h crypto_hash_update | |
1774 | !Finclude/linux/crypto.h crypto_hash_final | |
1775 | !Finclude/linux/crypto.h crypto_hash_digest | |
1776 | !Finclude/linux/crypto.h crypto_hash_setkey | |
1777 | </sect1> | |
1778 | <sect1><title>Message Digest Algorithm Definitions</title> | |
1779 | !Pinclude/crypto/hash.h Message Digest Algorithm Definitions | |
1780 | !Finclude/crypto/hash.h hash_alg_common | |
1781 | !Finclude/crypto/hash.h ahash_alg | |
1782 | !Finclude/crypto/hash.h shash_alg | |
1783 | </sect1> | |
1784 | <sect1><title>Asynchronous Message Digest API</title> | |
1785 | !Pinclude/crypto/hash.h Asynchronous Message Digest API | |
1786 | !Finclude/crypto/hash.h crypto_alloc_ahash | |
1787 | !Finclude/crypto/hash.h crypto_free_ahash | |
1788 | !Finclude/crypto/hash.h crypto_ahash_init | |
1789 | !Finclude/crypto/hash.h crypto_ahash_digestsize | |
1790 | !Finclude/crypto/hash.h crypto_ahash_reqtfm | |
1791 | !Finclude/crypto/hash.h crypto_ahash_reqsize | |
1792 | !Finclude/crypto/hash.h crypto_ahash_setkey | |
1793 | !Finclude/crypto/hash.h crypto_ahash_finup | |
1794 | !Finclude/crypto/hash.h crypto_ahash_final | |
1795 | !Finclude/crypto/hash.h crypto_ahash_digest | |
1796 | !Finclude/crypto/hash.h crypto_ahash_export | |
1797 | !Finclude/crypto/hash.h crypto_ahash_import | |
1798 | </sect1> | |
1799 | <sect1><title>Asynchronous Hash Request Handle</title> | |
1800 | !Pinclude/crypto/hash.h Asynchronous Hash Request Handle | |
1801 | !Finclude/crypto/hash.h ahash_request_set_tfm | |
1802 | !Finclude/crypto/hash.h ahash_request_alloc | |
1803 | !Finclude/crypto/hash.h ahash_request_free | |
1804 | !Finclude/crypto/hash.h ahash_request_set_callback | |
1805 | !Finclude/crypto/hash.h ahash_request_set_crypt | |
1806 | </sect1> | |
1807 | <sect1><title>Synchronous Message Digest API</title> | |
1808 | !Pinclude/crypto/hash.h Synchronous Message Digest API | |
1809 | !Finclude/crypto/hash.h crypto_alloc_shash | |
1810 | !Finclude/crypto/hash.h crypto_free_shash | |
1811 | !Finclude/crypto/hash.h crypto_shash_blocksize | |
1812 | !Finclude/crypto/hash.h crypto_shash_digestsize | |
1813 | !Finclude/crypto/hash.h crypto_shash_descsize | |
1814 | !Finclude/crypto/hash.h crypto_shash_setkey | |
1815 | !Finclude/crypto/hash.h crypto_shash_digest | |
1816 | !Finclude/crypto/hash.h crypto_shash_export | |
1817 | !Finclude/crypto/hash.h crypto_shash_import | |
1818 | !Finclude/crypto/hash.h crypto_shash_init | |
1819 | !Finclude/crypto/hash.h crypto_shash_update | |
1820 | !Finclude/crypto/hash.h crypto_shash_final | |
1821 | !Finclude/crypto/hash.h crypto_shash_finup | |
1822 | </sect1> | |
1823 | <sect1><title>Crypto API Random Number API</title> | |
1824 | !Pinclude/crypto/rng.h Random number generator API | |
1825 | !Finclude/crypto/rng.h crypto_alloc_rng | |
1826 | !Finclude/crypto/rng.h crypto_rng_alg | |
1827 | !Finclude/crypto/rng.h crypto_free_rng | |
1828 | !Finclude/crypto/rng.h crypto_rng_get_bytes | |
1829 | !Finclude/crypto/rng.h crypto_rng_reset | |
1830 | !Finclude/crypto/rng.h crypto_rng_seedsize | |
1831 | !Cinclude/crypto/rng.h | |
1832 | </sect1> | |
1833 | </chapter> | |
1834 | ||
1835 | <chapter id="Code"><title>Code Examples</title> | |
1836 | <sect1><title>Code Example For Asynchronous Block Cipher Operation</title> | |
1837 | <programlisting> | |
1838 | ||
1839 | struct tcrypt_result { | |
1840 | struct completion completion; | |
1841 | int err; | |
1842 | }; | |
1843 | ||
1844 | /* tie all data structures together */ | |
1845 | struct ablkcipher_def { | |
1846 | struct scatterlist sg; | |
1847 | struct crypto_ablkcipher *tfm; | |
1848 | struct ablkcipher_request *req; | |
1849 | struct tcrypt_result result; | |
1850 | }; | |
1851 | ||
1852 | /* Callback function */ | |
1853 | static void test_ablkcipher_cb(struct crypto_async_request *req, int error) | |
1854 | { | |
1855 | struct tcrypt_result *result = req->data; | |
1856 | ||
1857 | if (error == -EINPROGRESS) | |
1858 | return; | |
1859 | result->err = error; | |
1860 | complete(&result->completion); | |
1861 | pr_info("Encryption finished successfully\n"); | |
1862 | } | |
1863 | ||
1864 | /* Perform cipher operation */ | |
1865 | static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk, | |
1866 | int enc) | |
1867 | { | |
1868 | int rc = 0; | |
1869 | ||
1870 | if (enc) | |
1871 | rc = crypto_ablkcipher_encrypt(ablk->req); | |
1872 | else | |
1873 | rc = crypto_ablkcipher_decrypt(ablk->req); | |
1874 | ||
1875 | switch (rc) { | |
1876 | case 0: | |
1877 | break; | |
1878 | case -EINPROGRESS: | |
1879 | case -EBUSY: | |
1880 | rc = wait_for_completion_interruptible( | |
1881 | &ablk->result.completion); | |
1882 | if (!rc && !ablk->result.err) { | |
1883 | reinit_completion(&ablk->result.completion); | |
1884 | break; | |
1885 | } | |
1886 | default: | |
1887 | pr_info("ablkcipher encrypt returned with %d result %d\n", | |
1888 | rc, ablk->result.err); | |
1889 | break; | |
1890 | } | |
1891 | init_completion(&ablk->result.completion); | |
1892 | ||
1893 | return rc; | |
1894 | } | |
1895 | ||
1896 | /* Initialize and trigger cipher operation */ | |
1897 | static int test_ablkcipher(void) | |
1898 | { | |
1899 | struct ablkcipher_def ablk; | |
1900 | struct crypto_ablkcipher *ablkcipher = NULL; | |
1901 | struct ablkcipher_request *req = NULL; | |
1902 | char *scratchpad = NULL; | |
1903 | char *ivdata = NULL; | |
1904 | unsigned char key[32]; | |
1905 | int ret = -EFAULT; | |
1906 | ||
1907 | ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0); | |
1908 | if (IS_ERR(ablkcipher)) { | |
1909 | pr_info("could not allocate ablkcipher handle\n"); | |
1910 | return PTR_ERR(ablkcipher); | |
1911 | } | |
1912 | ||
1913 | req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL); | |
1914 | if (IS_ERR(req)) { | |
1915 | pr_info("could not allocate request queue\n"); | |
1916 | ret = PTR_ERR(req); | |
1917 | goto out; | |
1918 | } | |
1919 | ||
1920 | ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG, | |
1921 | test_ablkcipher_cb, | |
1922 | &ablk.result); | |
1923 | ||
1924 | /* AES 256 with random key */ | |
1925 | get_random_bytes(&key, 32); | |
1926 | if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) { | |
1927 | pr_info("key could not be set\n"); | |
1928 | ret = -EAGAIN; | |
1929 | goto out; | |
1930 | } | |
1931 | ||
1932 | /* IV will be random */ | |
1933 | ivdata = kmalloc(16, GFP_KERNEL); | |
1934 | if (!ivdata) { | |
1935 | pr_info("could not allocate ivdata\n"); | |
1936 | goto out; | |
1937 | } | |
1938 | get_random_bytes(ivdata, 16); | |
1939 | ||
1940 | /* Input data will be random */ | |
1941 | scratchpad = kmalloc(16, GFP_KERNEL); | |
1942 | if (!scratchpad) { | |
1943 | pr_info("could not allocate scratchpad\n"); | |
1944 | goto out; | |
1945 | } | |
1946 | get_random_bytes(scratchpad, 16); | |
1947 | ||
1948 | ablk.tfm = ablkcipher; | |
1949 | ablk.req = req; | |
1950 | ||
1951 | /* We encrypt one block */ | |
1952 | sg_init_one(&ablk.sg, scratchpad, 16); | |
1953 | ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata); | |
1954 | init_completion(&ablk.result.completion); | |
1955 | ||
1956 | /* encrypt data */ | |
1957 | ret = test_ablkcipher_encdec(&ablk, 1); | |
1958 | if (ret) | |
1959 | goto out; | |
1960 | ||
1961 | pr_info("Encryption triggered successfully\n"); | |
1962 | ||
1963 | out: | |
1964 | if (ablkcipher) | |
1965 | crypto_free_ablkcipher(ablkcipher); | |
1966 | if (req) | |
1967 | ablkcipher_request_free(req); | |
1968 | if (ivdata) | |
1969 | kfree(ivdata); | |
1970 | if (scratchpad) | |
1971 | kfree(scratchpad); | |
1972 | return ret; | |
1973 | } | |
1974 | </programlisting> | |
1975 | </sect1> | |
1976 | ||
1977 | <sect1><title>Code Example For Synchronous Block Cipher Operation</title> | |
1978 | <programlisting> | |
1979 | ||
1980 | static int test_blkcipher(void) | |
1981 | { | |
1982 | struct crypto_blkcipher *blkcipher = NULL; | |
1983 | char *cipher = "cbc(aes)"; | |
1984 | // AES 128 | |
1985 | charkey = | |
1986 | "\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; | |
1987 | chariv = | |
1988 | "\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef"; | |
1989 | unsigned int ivsize = 0; | |
1990 | char *scratchpad = NULL; // holds plaintext and ciphertext | |
1991 | struct scatterlist sg; | |
1992 | struct blkcipher_desc desc; | |
1993 | int ret = -EFAULT; | |
1994 | ||
1995 | blkcipher = crypto_alloc_blkcipher(cipher, 0, 0); | |
1996 | if (IS_ERR(blkcipher)) { | |
1997 | printk("could not allocate blkcipher handle for %s\n", cipher); | |
1998 | return -PTR_ERR(blkcipher); | |
1999 | } | |
2000 | ||
2001 | if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) { | |
2002 | printk("key could not be set\n"); | |
2003 | ret = -EAGAIN; | |
2004 | goto out; | |
2005 | } | |
2006 | ||
2007 | ivsize = crypto_blkcipher_ivsize(blkcipher); | |
2008 | if (ivsize) { | |
2009 | if (ivsize != strlen(iv)) | |
2010 | printk("IV length differs from expected length\n"); | |
2011 | crypto_blkcipher_set_iv(blkcipher, iv, ivsize); | |
2012 | } | |
2013 | ||
2014 | scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL); | |
2015 | if (!scratchpad) { | |
2016 | printk("could not allocate scratchpad for %s\n", cipher); | |
2017 | goto out; | |
2018 | } | |
2019 | /* get some random data that we want to encrypt */ | |
2020 | get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher)); | |
2021 | ||
2022 | desc.flags = 0; | |
2023 | desc.tfm = blkcipher; | |
2024 | sg_init_one(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher)); | |
2025 | ||
2026 | /* encrypt data in place */ | |
2027 | crypto_blkcipher_encrypt(&desc, &sg, &sg, | |
2028 | crypto_blkcipher_blocksize(blkcipher)); | |
2029 | ||
2030 | /* decrypt data in place | |
2031 | * crypto_blkcipher_decrypt(&desc, &sg, &sg, | |
2032 | */ crypto_blkcipher_blocksize(blkcipher)); | |
2033 | ||
2034 | ||
2035 | printk("Cipher operation completed\n"); | |
2036 | return 0; | |
2037 | ||
2038 | out: | |
2039 | if (blkcipher) | |
2040 | crypto_free_blkcipher(blkcipher); | |
2041 | if (scratchpad) | |
2042 | kzfree(scratchpad); | |
2043 | return ret; | |
2044 | } | |
2045 | </programlisting> | |
2046 | </sect1> | |
2047 | ||
2048 | <sect1><title>Code Example For Use of Operational State Memory With SHASH</title> | |
2049 | <programlisting> | |
2050 | ||
2051 | struct sdesc { | |
2052 | struct shash_desc shash; | |
2053 | char ctx[]; | |
2054 | }; | |
2055 | ||
2056 | static struct sdescinit_sdesc(struct crypto_shash *alg) | |
2057 | { | |
2058 | struct sdescsdesc; | |
2059 | int size; | |
2060 | ||
2061 | size = sizeof(struct shash_desc) + crypto_shash_descsize(alg); | |
2062 | sdesc = kmalloc(size, GFP_KERNEL); | |
2063 | if (!sdesc) | |
2064 | return ERR_PTR(-ENOMEM); | |
2065 | sdesc->shash.tfm = alg; | |
2066 | sdesc->shash.flags = 0x0; | |
2067 | return sdesc; | |
2068 | } | |
2069 | ||
2070 | static int calc_hash(struct crypto_shashalg, | |
2071 | const unsigned chardata, unsigned int datalen, | |
2072 | unsigned chardigest) { | |
2073 | struct sdescsdesc; | |
2074 | int ret; | |
2075 | ||
2076 | sdesc = init_sdesc(alg); | |
2077 | if (IS_ERR(sdesc)) { | |
2078 | pr_info("trusted_key: can't alloc %s\n", hash_alg); | |
2079 | return PTR_ERR(sdesc); | |
2080 | } | |
2081 | ||
2082 | ret = crypto_shash_digest(&sdesc->shash, data, datalen, digest); | |
2083 | kfree(sdesc); | |
2084 | return ret; | |
2085 | } | |
2086 | </programlisting> | |
2087 | </sect1> | |
2088 | ||
2089 | <sect1><title>Code Example For Random Number Generator Usage</title> | |
2090 | <programlisting> | |
2091 | ||
2092 | static int get_random_numbers(u8 *buf, unsigned int len) | |
2093 | { | |
2094 | struct crypto_rngrng = NULL; | |
2095 | chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */ | |
2096 | int ret; | |
2097 | ||
2098 | if (!buf || !len) { | |
2099 | pr_debug("No output buffer provided\n"); | |
2100 | return -EINVAL; | |
2101 | } | |
2102 | ||
2103 | rng = crypto_alloc_rng(drbg, 0, 0); | |
2104 | if (IS_ERR(rng)) { | |
2105 | pr_debug("could not allocate RNG handle for %s\n", drbg); | |
2106 | return -PTR_ERR(rng); | |
2107 | } | |
2108 | ||
2109 | ret = crypto_rng_get_bytes(rng, buf, len); | |
2110 | if (ret < 0) | |
2111 | pr_debug("generation of random numbers failed\n"); | |
2112 | else if (ret == 0) | |
2113 | pr_debug("RNG returned no data"); | |
2114 | else | |
2115 | pr_debug("RNG returned %d bytes of data\n", ret); | |
2116 | ||
2117 | out: | |
2118 | crypto_free_rng(rng); | |
2119 | return ret; | |
2120 | } | |
2121 | </programlisting> | |
2122 | </sect1> | |
2123 | </chapter> | |
2124 | </book> |