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