Loading...
Note: File does not exist in v6.13.7.
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
114 specification, however, does not discuss all API calls available
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 interchangeably.
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>skcipher for symmetric key ciphers</para>
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>
484 <listitem>
485 <para>CRYPTO_ALG_TYPE_AKCIPHER Asymmetric cipher</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>
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
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.
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[
583kernel crypto API | IPSEC Layer
584 |
585+-----------+ |
586| | (1)
587| aead | <----------------------------------- esp_output
588| (seqiv) | ---+
589+-----------+ |
590 | (2)
591+-----------+ |
592| | <--+ (2)
593| aead | <----------------------------------- esp_input
594| (gcm) | ------------+
595+-----------+ |
596 | (3) | (5)
597 v v
598+-----------+ +-----------+
599| | | |
600| skcipher | | 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>
623 esp_output() invokes crypto_aead_encrypt() to trigger an encryption
624 operation of the AEAD cipher with IV generator.
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 SKCIPHER 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 SKCIPHER 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 SKCIPHER 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 SKCIPHER 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[
727kernel 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>
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</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. The multi-block ciphers are
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>
923 The registration of multi-block cipher algorithms
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
930 crypto_skcipher_alignmask() to identify a memory alignment mask.
931 The kernel crypto API is able to process requests that are unaligned.
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
946 of the block cipher usage.
947 </para>
948 </sect2>
949
950 <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title>
951 <para>
952 There are a couple of specifics to the asynchronous interface.
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
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>
1101 [1] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink>
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>
1223struct 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>
1277struct 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>
1362struct 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>
1533struct 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>
1563 In addition to the send/write/read/recv system call family, the AF_ALG
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>
1588int pipes[2];
1589
1590pipe(pipes);
1591/* input data in iov */
1592vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT);
1593/* opfd is the file descriptor returned from accept() system call */
1594splice(pipes[0], NULL, opfd, NULL, ret, 0);
1595read(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>
1661 [1] <ulink url="http://www.chronox.de/libkcapi.html">http://www.chronox.de/libkcapi.html</ulink>
1662 </para>
1663
1664 </sect1>
1665
1666 </chapter>
1667
1668 <chapter id="API"><title>Programming Interface</title>
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>
1679 <sect1><title>Block Cipher Context Data Structures</title>
1680!Pinclude/linux/crypto.h Block Cipher Context Data Structures
1681!Finclude/crypto/aead.h aead_request
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
1687!Finclude/crypto/aead.h aead_alg
1688!Finclude/linux/crypto.h blkcipher_alg
1689!Finclude/linux/crypto.h cipher_alg
1690!Finclude/crypto/rng.h rng_alg
1691 </sect1>
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>
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>
1725 <sect1><title>Asynchronous Cipher Request Handle - Deprecated</title>
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>
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
1745 </sect1>
1746 <sect1><title>Asynchronous AEAD Request Handle</title>
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
1754!Finclude/crypto/aead.h aead_request_set_ad
1755 </sect1>
1756 <sect1><title>Synchronous Block Cipher API - Deprecated</title>
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
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
1832!Finclude/crypto/rng.h crypto_rng_generate
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>
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>
1858 </chapter>
1859
1860 <chapter id="Code"><title>Code Examples</title>
1861 <sect1><title>Code Example For Symmetric Key Cipher Operation</title>
1862 <programlisting>
1863
1864struct tcrypt_result {
1865 struct completion completion;
1866 int err;
1867};
1868
1869/* tie all data structures together */
1870struct skcipher_def {
1871 struct scatterlist sg;
1872 struct crypto_skcipher *tfm;
1873 struct skcipher_request *req;
1874 struct tcrypt_result result;
1875};
1876
1877/* Callback function */
1878static void test_skcipher_cb(struct crypto_async_request *req, int error)
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 */
1890static unsigned int test_skcipher_encdec(struct skcipher_def *sk,
1891 int enc)
1892{
1893 int rc = 0;
1894
1895 if (enc)
1896 rc = crypto_skcipher_encrypt(sk->req);
1897 else
1898 rc = crypto_skcipher_decrypt(sk->req);
1899
1900 switch (rc) {
1901 case 0:
1902 break;
1903 case -EINPROGRESS:
1904 case -EBUSY:
1905 rc = wait_for_completion_interruptible(
1906 &sk->result.completion);
1907 if (!rc && !sk->result.err) {
1908 reinit_completion(&sk->result.completion);
1909 break;
1910 }
1911 default:
1912 pr_info("skcipher encrypt returned with %d result %d\n",
1913 rc, sk->result.err);
1914 break;
1915 }
1916 init_completion(&sk->result.completion);
1917
1918 return rc;
1919}
1920
1921/* Initialize and trigger cipher operation */
1922static int test_skcipher(void)
1923{
1924 struct skcipher_def sk;
1925 struct crypto_skcipher *skcipher = NULL;
1926 struct skcipher_request *req = NULL;
1927 char *scratchpad = NULL;
1928 char *ivdata = NULL;
1929 unsigned char key[32];
1930 int ret = -EFAULT;
1931
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);
1936 }
1937
1938 req = skcipher_request_alloc(skcipher, GFP_KERNEL);
1939 if (IS_ERR(req)) {
1940 pr_info("could not allocate request queue\n");
1941 ret = PTR_ERR(req);
1942 goto out;
1943 }
1944
1945 skcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,
1946 test_skcipher_cb,
1947 &sk.result);
1948
1949 /* AES 256 with random key */
1950 get_random_bytes(&key, 32);
1951 if (crypto_skcipher_setkey(skcipher, key, 32)) {
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
1973 sk.tfm = skcipher;
1974 sk.req = req;
1975
1976 /* We encrypt one block */
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);
1980
1981 /* encrypt data */
1982 ret = test_skcipher_encdec(&sk, 1);
1983 if (ret)
1984 goto out;
1985
1986 pr_info("Encryption triggered successfully\n");
1987
1988out:
1989 if (skcipher)
1990 crypto_free_skcipher(skcipher);
1991 if (req)
1992 skcipher_request_free(req);
1993 if (ivdata)
1994 kfree(ivdata);
1995 if (scratchpad)
1996 kfree(scratchpad);
1997 return ret;
1998}
1999 </programlisting>
2000 </sect1>
2001
2002 <sect1><title>Code Example For Use of Operational State Memory With SHASH</title>
2003 <programlisting>
2004
2005struct sdesc {
2006 struct shash_desc shash;
2007 char ctx[];
2008};
2009
2010static 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
2024static 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
2046static 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
2071out:
2072 crypto_free_rng(rng);
2073 return ret;
2074}
2075 </programlisting>
2076 </sect1>
2077 </chapter>
2078 </book>