aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/DocBook/crypto-API.tmpl
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/DocBook/crypto-API.tmpl')
-rw-r--r--Documentation/DocBook/crypto-API.tmpl1253
1 files changed, 1253 insertions, 0 deletions
diff --git a/Documentation/DocBook/crypto-API.tmpl b/Documentation/DocBook/crypto-API.tmpl
new file mode 100644
index 000000000000..c763d30f4893
--- /dev/null
+++ b/Documentation/DocBook/crypto-API.tmpl
@@ -0,0 +1,1253 @@
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 discusses 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 interchangably.
123 </para>
124 </sect1>
125
126 <sect1><title>Terminology</title>
127 <para>
128 The transformation implementation is an actual code or interface
129 to hardware which implements a certain transformation with precisely
130 defined behavior.
131 </para>
132
133 <para>
134 The transformation object (TFM) is an instance of a transformation
135 implementation. There can be multiple transformation objects
136 associated with a single transformation implementation. Each of
137 those transformation objects is held by a crypto API consumer or
138 another transformation. Transformation object is allocated when a
139 crypto API consumer requests a transformation implementation.
140 The consumer is then provided with a structure, which contains
141 a transformation object (TFM).
142 </para>
143
144 <para>
145 The structure that contains transformation objects may also be
146 referred to as a "cipher handle". Such a cipher handle is always
147 subject to the following phases that are reflected in the API calls
148 applicable to such a cipher handle:
149 </para>
150
151 <orderedlist>
152 <listitem>
153 <para>Initialization of a cipher handle.</para>
154 </listitem>
155 <listitem>
156 <para>Execution of all intended cipher operations applicable
157 for the handle where the cipher handle must be furnished to
158 every API call.</para>
159 </listitem>
160 <listitem>
161 <para>Destruction of a cipher handle.</para>
162 </listitem>
163 </orderedlist>
164
165 <para>
166 When using the initialization API calls, a cipher handle is
167 created and returned to the consumer. Therefore, please refer
168 to all initialization API calls that refer to the data
169 structure type a consumer is expected to receive and subsequently
170 to use. The initialization API calls have all the same naming
171 conventions of crypto_alloc_*.
172 </para>
173
174 <para>
175 The transformation context is private data associated with
176 the transformation object.
177 </para>
178 </sect1>
179 </chapter>
180
181 <chapter id="Architecture"><title>Kernel Crypto API Architecture</title>
182 <sect1><title>Cipher algorithm types</title>
183 <para>
184 The kernel crypto API provides different API calls for the
185 following cipher types:
186
187 <itemizedlist>
188 <listitem><para>Symmetric ciphers</para></listitem>
189 <listitem><para>AEAD ciphers</para></listitem>
190 <listitem><para>Message digest, including keyed message digest</para></listitem>
191 <listitem><para>Random number generation</para></listitem>
192 <listitem><para>User space interface</para></listitem>
193 </itemizedlist>
194 </para>
195 </sect1>
196
197 <sect1><title>Ciphers And Templates</title>
198 <para>
199 The kernel crypto API provides implementations of single block
200 ciphers and message digests. In addition, the kernel crypto API
201 provides numerous "templates" that can be used in conjunction
202 with the single block ciphers and message digests. Templates
203 include all types of block chaining mode, the HMAC mechanism, etc.
204 </para>
205
206 <para>
207 Single block ciphers and message digests can either be directly
208 used by a caller or invoked together with a template to form
209 multi-block ciphers or keyed message digests.
210 </para>
211
212 <para>
213 A single block cipher may even be called with multiple templates.
214 However, templates cannot be used without a single cipher.
215 </para>
216
217 <para>
218 See /proc/crypto and search for "name". For example:
219
220 <itemizedlist>
221 <listitem><para>aes</para></listitem>
222 <listitem><para>ecb(aes)</para></listitem>
223 <listitem><para>cmac(aes)</para></listitem>
224 <listitem><para>ccm(aes)</para></listitem>
225 <listitem><para>rfc4106(gcm(aes))</para></listitem>
226 <listitem><para>sha1</para></listitem>
227 <listitem><para>hmac(sha1)</para></listitem>
228 <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem>
229 </itemizedlist>
230 </para>
231
232 <para>
233 In these examples, "aes" and "sha1" are the ciphers and all
234 others are the templates.
235 </para>
236 </sect1>
237
238 <sect1><title>Synchronous And Asynchronous Operation</title>
239 <para>
240 The kernel crypto API provides synchronous and asynchronous
241 API operations.
242 </para>
243
244 <para>
245 When using the synchronous API operation, the caller invokes
246 a cipher operation which is performed synchronously by the
247 kernel crypto API. That means, the caller waits until the
248 cipher operation completes. Therefore, the kernel crypto API
249 calls work like regular function calls. For synchronous
250 operation, the set of API calls is small and conceptually
251 similar to any other crypto library.
252 </para>
253
254 <para>
255 Asynchronous operation is provided by the kernel crypto API
256 which implies that the invocation of a cipher operation will
257 complete almost instantly. That invocation triggers the
258 cipher operation but it does not signal its completion. Before
259 invoking a cipher operation, the caller must provide a callback
260 function the kernel crypto API can invoke to signal the
261 completion of the cipher operation. Furthermore, the caller
262 must ensure it can handle such asynchronous events by applying
263 appropriate locking around its data. The kernel crypto API
264 does not perform any special serialization operation to protect
265 the caller's data integrity.
266 </para>
267 </sect1>
268
269 <sect1><title>Crypto API Cipher References And Priority</title>
270 <para>
271 A cipher is referenced by the caller with a string. That string
272 has the following semantics:
273
274 <programlisting>
275 template(single block cipher)
276 </programlisting>
277
278 where "template" and "single block cipher" is the aforementioned
279 template and single block cipher, respectively. If applicable,
280 additional templates may enclose other templates, such as
281
282 <programlisting>
283 template1(template2(single block cipher)))
284 </programlisting>
285 </para>
286
287 <para>
288 The kernel crypto API may provide multiple implementations of a
289 template or a single block cipher. For example, AES on newer
290 Intel hardware has the following implementations: AES-NI,
291 assembler implementation, or straight C. Now, when using the
292 string "aes" with the kernel crypto API, which cipher
293 implementation is used? The answer to that question is the
294 priority number assigned to each cipher implementation by the
295 kernel crypto API. When a caller uses the string to refer to a
296 cipher during initialization of a cipher handle, the kernel
297 crypto API looks up all implementations providing an
298 implementation with that name and selects the implementation
299 with the highest priority.
300 </para>
301
302 <para>
303 Now, a caller may have the need to refer to a specific cipher
304 implementation and thus does not want to rely on the
305 priority-based selection. To accommodate this scenario, the
306 kernel crypto API allows the cipher implementation to register
307 a unique name in addition to common names. When using that
308 unique name, a caller is therefore always sure to refer to
309 the intended cipher implementation.
310 </para>
311
312 <para>
313 The list of available ciphers is given in /proc/crypto. However,
314 that list does not specify all possible permutations of
315 templates and ciphers. Each block listed in /proc/crypto may
316 contain the following information -- if one of the components
317 listed as follows are not applicable to a cipher, it is not
318 displayed:
319 </para>
320
321 <itemizedlist>
322 <listitem>
323 <para>name: the generic name of the cipher that is subject
324 to the priority-based selection -- this name can be used by
325 the cipher allocation API calls (all names listed above are
326 examples for such generic names)</para>
327 </listitem>
328 <listitem>
329 <para>driver: the unique name of the cipher -- this name can
330 be used by the cipher allocation API calls</para>
331 </listitem>
332 <listitem>
333 <para>module: the kernel module providing the cipher
334 implementation (or "kernel" for statically linked ciphers)</para>
335 </listitem>
336 <listitem>
337 <para>priority: the priority value of the cipher implementation</para>
338 </listitem>
339 <listitem>
340 <para>refcnt: the reference count of the respective cipher
341 (i.e. the number of current consumers of this cipher)</para>
342 </listitem>
343 <listitem>
344 <para>selftest: specification whether the self test for the
345 cipher passed</para>
346 </listitem>
347 <listitem>
348 <para>type:
349 <itemizedlist>
350 <listitem>
351 <para>blkcipher for synchronous block ciphers</para>
352 </listitem>
353 <listitem>
354 <para>ablkcipher for asynchronous block ciphers</para>
355 </listitem>
356 <listitem>
357 <para>cipher for single block ciphers that may be used with
358 an additional template</para>
359 </listitem>
360 <listitem>
361 <para>shash for synchronous message digest</para>
362 </listitem>
363 <listitem>
364 <para>ahash for asynchronous message digest</para>
365 </listitem>
366 <listitem>
367 <para>aead for AEAD cipher type</para>
368 </listitem>
369 <listitem>
370 <para>compression for compression type transformations</para>
371 </listitem>
372 <listitem>
373 <para>rng for random number generator</para>
374 </listitem>
375 <listitem>
376 <para>givcipher for cipher with associated IV generator
377 (see the geniv entry below for the specification of the
378 IV generator type used by the cipher implementation)</para>
379 </listitem>
380 </itemizedlist>
381 </para>
382 </listitem>
383 <listitem>
384 <para>blocksize: blocksize of cipher in bytes</para>
385 </listitem>
386 <listitem>
387 <para>keysize: key size in bytes</para>
388 </listitem>
389 <listitem>
390 <para>ivsize: IV size in bytes</para>
391 </listitem>
392 <listitem>
393 <para>seedsize: required size of seed data for random number
394 generator</para>
395 </listitem>
396 <listitem>
397 <para>digestsize: output size of the message digest</para>
398 </listitem>
399 <listitem>
400 <para>geniv: IV generation type:
401 <itemizedlist>
402 <listitem>
403 <para>eseqiv for encrypted sequence number based IV
404 generation</para>
405 </listitem>
406 <listitem>
407 <para>seqiv for sequence number based IV generation</para>
408 </listitem>
409 <listitem>
410 <para>chainiv for chain iv generation</para>
411 </listitem>
412 <listitem>
413 <para>&lt;builtin&gt; is a marker that the cipher implements
414 IV generation and handling as it is specific to the given
415 cipher</para>
416 </listitem>
417 </itemizedlist>
418 </para>
419 </listitem>
420 </itemizedlist>
421 </sect1>
422
423 <sect1><title>Key Sizes</title>
424 <para>
425 When allocating a cipher handle, the caller only specifies the
426 cipher type. Symmetric ciphers, however, typically support
427 multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256).
428 These key sizes are determined with the length of the provided
429 key. Thus, the kernel crypto API does not provide a separate
430 way to select the particular symmetric cipher key size.
431 </para>
432 </sect1>
433
434 <sect1><title>Cipher Allocation Type And Masks</title>
435 <para>
436 The different cipher handle allocation functions allow the
437 specification of a type and mask flag. Both parameters have
438 the following meaning (and are therefore not covered in the
439 subsequent sections).
440 </para>
441
442 <para>
443 The type flag specifies the type of the cipher algorithm.
444 The caller usually provides a 0 when the caller wants the
445 default handling. Otherwise, the caller may provide the
446 following selections which match the the aforementioned
447 cipher types:
448 </para>
449
450 <itemizedlist>
451 <listitem>
452 <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para>
453 </listitem>
454 <listitem>
455 <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para>
456 </listitem>
457 <listitem>
458 <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with
459 Associated Data (MAC)</para>
460 </listitem>
461 <listitem>
462 <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para>
463 </listitem>
464 <listitem>
465 <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para>
466 </listitem>
467 <listitem>
468 <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block
469 cipher packed together with an IV generator (see geniv field
470 in the /proc/crypto listing for the known IV generators)</para>
471 </listitem>
472 <listitem>
473 <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para>
474 </listitem>
475 <listitem>
476 <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para>
477 </listitem>
478 <listitem>
479 <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para>
480 </listitem>
481 <listitem>
482 <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para>
483 </listitem>
484 <listitem>
485 <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para>
486 </listitem>
487 <listitem>
488 <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of
489 CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression /
490 decompression instead of performing the operation on one
491 segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace
492 CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para>
493 </listitem>
494 </itemizedlist>
495
496 <para>
497 The mask flag restricts the type of cipher. The only allowed
498 flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function
499 to asynchronous ciphers. Usually, a caller provides a 0 for the
500 mask flag.
501 </para>
502
503 <para>
504 When the caller provides a mask and type specification, the
505 caller limits the search the kernel crypto API can perform for
506 a suitable cipher implementation for the given cipher name.
507 That means, even when a caller uses a cipher name that exists
508 during its initialization call, the kernel crypto API may not
509 select it due to the used type and mask field.
510 </para>
511 </sect1>
512 </chapter>
513
514 <chapter id="Development"><title>Developing Cipher Algorithms</title>
515 <sect1><title>Registering And Unregistering Transformation</title>
516 <para>
517 There are three distinct types of registration functions in
518 the Crypto API. One is used to register a generic cryptographic
519 transformation, while the other two are specific to HASH
520 transformations and COMPRESSion. We will discuss the latter
521 two in a separate chapter, here we will only look at the
522 generic ones.
523 </para>
524
525 <para>
526 Before discussing the register functions, the data structure
527 to be filled with each, struct crypto_alg, must be considered
528 -- see below for a description of this data structure.
529 </para>
530
531 <para>
532 The generic registration functions can be found in
533 include/linux/crypto.h and their definition can be seen below.
534 The former function registers a single transformation, while
535 the latter works on an array of transformation descriptions.
536 The latter is useful when registering transformations in bulk.
537 </para>
538
539 <programlisting>
540 int crypto_register_alg(struct crypto_alg *alg);
541 int crypto_register_algs(struct crypto_alg *algs, int count);
542 </programlisting>
543
544 <para>
545 The counterparts to those functions are listed below.
546 </para>
547
548 <programlisting>
549 int crypto_unregister_alg(struct crypto_alg *alg);
550 int crypto_unregister_algs(struct crypto_alg *algs, int count);
551 </programlisting>
552
553 <para>
554 Notice that both registration and unregistration functions
555 do return a value, so make sure to handle errors. A return
556 code of zero implies success. Any return code &lt; 0 implies
557 an error.
558 </para>
559
560 <para>
561 The bulk registration / unregistration functions require
562 that struct crypto_alg is an array of count size. These
563 functions simply loop over that array and register /
564 unregister each individual algorithm. If an error occurs,
565 the loop is terminated at the offending algorithm definition.
566 That means, the algorithms prior to the offending algorithm
567 are successfully registered. Note, the caller has no way of
568 knowing which cipher implementations have successfully
569 registered. If this is important to know, the caller should
570 loop through the different implementations using the single
571 instance *_alg functions for each individual implementation.
572 </para>
573 </sect1>
574
575 <sect1><title>Single-Block Symmetric Ciphers [CIPHER]</title>
576 <para>
577 Example of transformations: aes, arc4, ...
578 </para>
579
580 <para>
581 This section describes the simplest of all transformation
582 implementations, that being the CIPHER type used for symmetric
583 ciphers. The CIPHER type is used for transformations which
584 operate on exactly one block at a time and there are no
585 dependencies between blocks at all.
586 </para>
587
588 <sect2><title>Registration specifics</title>
589 <para>
590 The registration of [CIPHER] algorithm is specific in that
591 struct crypto_alg field .cra_type is empty. The .cra_u.cipher
592 has to be filled in with proper callbacks to implement this
593 transformation.
594 </para>
595
596 <para>
597 See struct cipher_alg below.
598 </para>
599 </sect2>
600
601 <sect2><title>Cipher Definition With struct cipher_alg</title>
602 <para>
603 Struct cipher_alg defines a single block cipher.
604 </para>
605
606 <para>
607 Here are schematics of how these functions are called when
608 operated from other part of the kernel. Note that the
609 .cia_setkey() call might happen before or after any of these
610 schematics happen, but must not happen during any of these
611 are in-flight.
612 </para>
613
614 <para>
615 <programlisting>
616 KEY ---. PLAINTEXT ---.
617 v v
618 .cia_setkey() -&gt; .cia_encrypt()
619 |
620 '-----&gt; CIPHERTEXT
621 </programlisting>
622 </para>
623
624 <para>
625 Please note that a pattern where .cia_setkey() is called
626 multiple times is also valid:
627 </para>
628
629 <para>
630 <programlisting>
631
632 KEY1 --. PLAINTEXT1 --. KEY2 --. PLAINTEXT2 --.
633 v v v v
634 .cia_setkey() -&gt; .cia_encrypt() -&gt; .cia_setkey() -&gt; .cia_encrypt()
635 | |
636 '---&gt; CIPHERTEXT1 '---&gt; CIPHERTEXT2
637 </programlisting>
638 </para>
639
640 </sect2>
641 </sect1>
642
643 <sect1><title>Multi-Block Ciphers [BLKCIPHER] [ABLKCIPHER]</title>
644 <para>
645 Example of transformations: cbc(aes), ecb(arc4), ...
646 </para>
647
648 <para>
649 This section describes the multi-block cipher transformation
650 implementations for both synchronous [BLKCIPHER] and
651 asynchronous [ABLKCIPHER] case. The multi-block ciphers are
652 used for transformations which operate on scatterlists of
653 data supplied to the transformation functions. They output
654 the result into a scatterlist of data as well.
655 </para>
656
657 <sect2><title>Registration Specifics</title>
658
659 <para>
660 The registration of [BLKCIPHER] or [ABLKCIPHER] algorithms
661 is one of the most standard procedures throughout the crypto API.
662 </para>
663
664 <para>
665 Note, if a cipher implementation requires a proper alignment
666 of data, the caller should use the functions of
667 crypto_blkcipher_alignmask() or crypto_ablkcipher_alignmask()
668 respectively to identify a memory alignment mask. The kernel
669 crypto API is able to process requests that are unaligned.
670 This implies, however, additional overhead as the kernel
671 crypto API needs to perform the realignment of the data which
672 may imply moving of data.
673 </para>
674 </sect2>
675
676 <sect2><title>Cipher Definition With struct blkcipher_alg and ablkcipher_alg</title>
677 <para>
678 Struct blkcipher_alg defines a synchronous block cipher whereas
679 struct ablkcipher_alg defines an asynchronous block cipher.
680 </para>
681
682 <para>
683 Please refer to the single block cipher description for schematics
684 of the block cipher usage. The usage patterns are exactly the same
685 for [ABLKCIPHER] and [BLKCIPHER] as they are for plain [CIPHER].
686 </para>
687 </sect2>
688
689 <sect2><title>Specifics Of Asynchronous Multi-Block Cipher</title>
690 <para>
691 There are a couple of specifics to the [ABLKCIPHER] interface.
692 </para>
693
694 <para>
695 First of all, some of the drivers will want to use the
696 Generic ScatterWalk in case the hardware needs to be fed
697 separate chunks of the scatterlist which contains the
698 plaintext and will contain the ciphertext. Please refer
699 to the ScatterWalk interface offered by the Linux kernel
700 scatter / gather list implementation.
701 </para>
702 </sect2>
703 </sect1>
704
705 <sect1><title>Hashing [HASH]</title>
706
707 <para>
708 Example of transformations: crc32, md5, sha1, sha256,...
709 </para>
710
711 <sect2><title>Registering And Unregistering The Transformation</title>
712
713 <para>
714 There are multiple ways to register a HASH transformation,
715 depending on whether the transformation is synchronous [SHASH]
716 or asynchronous [AHASH] and the amount of HASH transformations
717 we are registering. You can find the prototypes defined in
718 include/crypto/internal/hash.h:
719 </para>
720
721 <programlisting>
722 int crypto_register_ahash(struct ahash_alg *alg);
723
724 int crypto_register_shash(struct shash_alg *alg);
725 int crypto_register_shashes(struct shash_alg *algs, int count);
726 </programlisting>
727
728 <para>
729 The respective counterparts for unregistering the HASH
730 transformation are as follows:
731 </para>
732
733 <programlisting>
734 int crypto_unregister_ahash(struct ahash_alg *alg);
735
736 int crypto_unregister_shash(struct shash_alg *alg);
737 int crypto_unregister_shashes(struct shash_alg *algs, int count);
738 </programlisting>
739 </sect2>
740
741 <sect2><title>Cipher Definition With struct shash_alg and ahash_alg</title>
742 <para>
743 Here are schematics of how these functions are called when
744 operated from other part of the kernel. Note that the .setkey()
745 call might happen before or after any of these schematics happen,
746 but must not happen during any of these are in-flight. Please note
747 that calling .init() followed immediately by .finish() is also a
748 perfectly valid transformation.
749 </para>
750
751 <programlisting>
752 I) DATA -----------.
753 v
754 .init() -&gt; .update() -&gt; .final() ! .update() might not be called
755 ^ | | at all in this scenario.
756 '----' '---&gt; HASH
757
758 II) DATA -----------.-----------.
759 v v
760 .init() -&gt; .update() -&gt; .finup() ! .update() may not be called
761 ^ | | at all in this scenario.
762 '----' '---&gt; HASH
763
764 III) DATA -----------.
765 v
766 .digest() ! The entire process is handled
767 | by the .digest() call.
768 '---------------&gt; HASH
769 </programlisting>
770
771 <para>
772 Here is a schematic of how the .export()/.import() functions are
773 called when used from another part of the kernel.
774 </para>
775
776 <programlisting>
777 KEY--. DATA--.
778 v v ! .update() may not be called
779 .setkey() -&gt; .init() -&gt; .update() -&gt; .export() at all in this scenario.
780 ^ | |
781 '-----' '--&gt; PARTIAL_HASH
782
783 ----------- other transformations happen here -----------
784
785 PARTIAL_HASH--. DATA1--.
786 v v
787 .import -&gt; .update() -&gt; .final() ! .update() may not be called
788 ^ | | at all in this scenario.
789 '----' '--&gt; HASH1
790
791 PARTIAL_HASH--. DATA2-.
792 v v
793 .import -&gt; .finup()
794 |
795 '---------------&gt; HASH2
796 </programlisting>
797 </sect2>
798
799 <sect2><title>Specifics Of Asynchronous HASH Transformation</title>
800 <para>
801 Some of the drivers will want to use the Generic ScatterWalk
802 in case the implementation needs to be fed separate chunks of the
803 scatterlist which contains the input data. The buffer containing
804 the resulting hash will always be properly aligned to
805 .cra_alignmask so there is no need to worry about this.
806 </para>
807 </sect2>
808 </sect1>
809 </chapter>
810
811 <chapter id="API"><title>Programming Interface</title>
812 <sect1><title>Block Cipher Context Data Structures</title>
813!Pinclude/linux/crypto.h Block Cipher Context Data Structures
814!Finclude/linux/crypto.h aead_request
815 </sect1>
816 <sect1><title>Block Cipher Algorithm Definitions</title>
817!Pinclude/linux/crypto.h Block Cipher Algorithm Definitions
818!Finclude/linux/crypto.h crypto_alg
819!Finclude/linux/crypto.h ablkcipher_alg
820!Finclude/linux/crypto.h aead_alg
821!Finclude/linux/crypto.h blkcipher_alg
822!Finclude/linux/crypto.h cipher_alg
823!Finclude/linux/crypto.h rng_alg
824 </sect1>
825 <sect1><title>Asynchronous Block Cipher API</title>
826!Pinclude/linux/crypto.h Asynchronous Block Cipher API
827!Finclude/linux/crypto.h crypto_alloc_ablkcipher
828!Finclude/linux/crypto.h crypto_free_ablkcipher
829!Finclude/linux/crypto.h crypto_has_ablkcipher
830!Finclude/linux/crypto.h crypto_ablkcipher_ivsize
831!Finclude/linux/crypto.h crypto_ablkcipher_blocksize
832!Finclude/linux/crypto.h crypto_ablkcipher_setkey
833!Finclude/linux/crypto.h crypto_ablkcipher_reqtfm
834!Finclude/linux/crypto.h crypto_ablkcipher_encrypt
835!Finclude/linux/crypto.h crypto_ablkcipher_decrypt
836 </sect1>
837 <sect1><title>Asynchronous Cipher Request Handle</title>
838!Pinclude/linux/crypto.h Asynchronous Cipher Request Handle
839!Finclude/linux/crypto.h crypto_ablkcipher_reqsize
840!Finclude/linux/crypto.h ablkcipher_request_set_tfm
841!Finclude/linux/crypto.h ablkcipher_request_alloc
842!Finclude/linux/crypto.h ablkcipher_request_free
843!Finclude/linux/crypto.h ablkcipher_request_set_callback
844!Finclude/linux/crypto.h ablkcipher_request_set_crypt
845 </sect1>
846 <sect1><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title>
847!Pinclude/linux/crypto.h Authenticated Encryption With Associated Data (AEAD) Cipher API
848!Finclude/linux/crypto.h crypto_alloc_aead
849!Finclude/linux/crypto.h crypto_free_aead
850!Finclude/linux/crypto.h crypto_aead_ivsize
851!Finclude/linux/crypto.h crypto_aead_authsize
852!Finclude/linux/crypto.h crypto_aead_blocksize
853!Finclude/linux/crypto.h crypto_aead_setkey
854!Finclude/linux/crypto.h crypto_aead_setauthsize
855!Finclude/linux/crypto.h crypto_aead_encrypt
856!Finclude/linux/crypto.h crypto_aead_decrypt
857 </sect1>
858 <sect1><title>Asynchronous AEAD Request Handle</title>
859!Pinclude/linux/crypto.h Asynchronous AEAD Request Handle
860!Finclude/linux/crypto.h crypto_aead_reqsize
861!Finclude/linux/crypto.h aead_request_set_tfm
862!Finclude/linux/crypto.h aead_request_alloc
863!Finclude/linux/crypto.h aead_request_free
864!Finclude/linux/crypto.h aead_request_set_callback
865!Finclude/linux/crypto.h aead_request_set_crypt
866!Finclude/linux/crypto.h aead_request_set_assoc
867 </sect1>
868 <sect1><title>Synchronous Block Cipher API</title>
869!Pinclude/linux/crypto.h Synchronous Block Cipher API
870!Finclude/linux/crypto.h crypto_alloc_blkcipher
871!Finclude/linux/crypto.h crypto_free_blkcipher
872!Finclude/linux/crypto.h crypto_has_blkcipher
873!Finclude/linux/crypto.h crypto_blkcipher_name
874!Finclude/linux/crypto.h crypto_blkcipher_ivsize
875!Finclude/linux/crypto.h crypto_blkcipher_blocksize
876!Finclude/linux/crypto.h crypto_blkcipher_setkey
877!Finclude/linux/crypto.h crypto_blkcipher_encrypt
878!Finclude/linux/crypto.h crypto_blkcipher_encrypt_iv
879!Finclude/linux/crypto.h crypto_blkcipher_decrypt
880!Finclude/linux/crypto.h crypto_blkcipher_decrypt_iv
881!Finclude/linux/crypto.h crypto_blkcipher_set_iv
882!Finclude/linux/crypto.h crypto_blkcipher_get_iv
883 </sect1>
884 <sect1><title>Single Block Cipher API</title>
885!Pinclude/linux/crypto.h Single Block Cipher API
886!Finclude/linux/crypto.h crypto_alloc_cipher
887!Finclude/linux/crypto.h crypto_free_cipher
888!Finclude/linux/crypto.h crypto_has_cipher
889!Finclude/linux/crypto.h crypto_cipher_blocksize
890!Finclude/linux/crypto.h crypto_cipher_setkey
891!Finclude/linux/crypto.h crypto_cipher_encrypt_one
892!Finclude/linux/crypto.h crypto_cipher_decrypt_one
893 </sect1>
894 <sect1><title>Synchronous Message Digest API</title>
895!Pinclude/linux/crypto.h Synchronous Message Digest API
896!Finclude/linux/crypto.h crypto_alloc_hash
897!Finclude/linux/crypto.h crypto_free_hash
898!Finclude/linux/crypto.h crypto_has_hash
899!Finclude/linux/crypto.h crypto_hash_blocksize
900!Finclude/linux/crypto.h crypto_hash_digestsize
901!Finclude/linux/crypto.h crypto_hash_init
902!Finclude/linux/crypto.h crypto_hash_update
903!Finclude/linux/crypto.h crypto_hash_final
904!Finclude/linux/crypto.h crypto_hash_digest
905!Finclude/linux/crypto.h crypto_hash_setkey
906 </sect1>
907 <sect1><title>Message Digest Algorithm Definitions</title>
908!Pinclude/crypto/hash.h Message Digest Algorithm Definitions
909!Finclude/crypto/hash.h hash_alg_common
910!Finclude/crypto/hash.h ahash_alg
911!Finclude/crypto/hash.h shash_alg
912 </sect1>
913 <sect1><title>Asynchronous Message Digest API</title>
914!Pinclude/crypto/hash.h Asynchronous Message Digest API
915!Finclude/crypto/hash.h crypto_alloc_ahash
916!Finclude/crypto/hash.h crypto_free_ahash
917!Finclude/crypto/hash.h crypto_ahash_init
918!Finclude/crypto/hash.h crypto_ahash_digestsize
919!Finclude/crypto/hash.h crypto_ahash_reqtfm
920!Finclude/crypto/hash.h crypto_ahash_reqsize
921!Finclude/crypto/hash.h crypto_ahash_setkey
922!Finclude/crypto/hash.h crypto_ahash_finup
923!Finclude/crypto/hash.h crypto_ahash_final
924!Finclude/crypto/hash.h crypto_ahash_digest
925!Finclude/crypto/hash.h crypto_ahash_export
926!Finclude/crypto/hash.h crypto_ahash_import
927 </sect1>
928 <sect1><title>Asynchronous Hash Request Handle</title>
929!Pinclude/crypto/hash.h Asynchronous Hash Request Handle
930!Finclude/crypto/hash.h ahash_request_set_tfm
931!Finclude/crypto/hash.h ahash_request_alloc
932!Finclude/crypto/hash.h ahash_request_free
933!Finclude/crypto/hash.h ahash_request_set_callback
934!Finclude/crypto/hash.h ahash_request_set_crypt
935 </sect1>
936 <sect1><title>Synchronous Message Digest API</title>
937!Pinclude/crypto/hash.h Synchronous Message Digest API
938!Finclude/crypto/hash.h crypto_alloc_shash
939!Finclude/crypto/hash.h crypto_free_shash
940!Finclude/crypto/hash.h crypto_shash_blocksize
941!Finclude/crypto/hash.h crypto_shash_digestsize
942!Finclude/crypto/hash.h crypto_shash_descsize
943!Finclude/crypto/hash.h crypto_shash_setkey
944!Finclude/crypto/hash.h crypto_shash_digest
945!Finclude/crypto/hash.h crypto_shash_export
946!Finclude/crypto/hash.h crypto_shash_import
947!Finclude/crypto/hash.h crypto_shash_init
948!Finclude/crypto/hash.h crypto_shash_update
949!Finclude/crypto/hash.h crypto_shash_final
950!Finclude/crypto/hash.h crypto_shash_finup
951 </sect1>
952 <sect1><title>Crypto API Random Number API</title>
953!Pinclude/crypto/rng.h Random number generator API
954!Finclude/crypto/rng.h crypto_alloc_rng
955!Finclude/crypto/rng.h crypto_rng_alg
956!Finclude/crypto/rng.h crypto_free_rng
957!Finclude/crypto/rng.h crypto_rng_get_bytes
958!Finclude/crypto/rng.h crypto_rng_reset
959!Finclude/crypto/rng.h crypto_rng_seedsize
960!Cinclude/crypto/rng.h
961 </sect1>
962 </chapter>
963
964 <chapter id="Code"><title>Code Examples</title>
965 <sect1><title>Code Example For Asynchronous Block Cipher Operation</title>
966 <programlisting>
967
968struct tcrypt_result {
969 struct completion completion;
970 int err;
971};
972
973/* tie all data structures together */
974struct ablkcipher_def {
975 struct scatterlist sg;
976 struct crypto_ablkcipher *tfm;
977 struct ablkcipher_request *req;
978 struct tcrypt_result result;
979};
980
981/* Callback function */
982static void test_ablkcipher_cb(struct crypto_async_request *req, int error)
983{
984 struct tcrypt_result *result = req-&gt;data;
985
986 if (error == -EINPROGRESS)
987 return;
988 result-&gt;err = error;
989 complete(&amp;result-&gt;completion);
990 pr_info("Encryption finished successfully\n");
991}
992
993/* Perform cipher operation */
994static unsigned int test_ablkcipher_encdec(struct ablkcipher_def *ablk,
995 int enc)
996{
997 int rc = 0;
998
999 if (enc)
1000 rc = crypto_ablkcipher_encrypt(ablk-&gt;req);
1001 else
1002 rc = crypto_ablkcipher_decrypt(ablk-&gt;req);
1003
1004 switch (rc) {
1005 case 0:
1006 break;
1007 case -EINPROGRESS:
1008 case -EBUSY:
1009 rc = wait_for_completion_interruptible(
1010 &amp;ablk-&gt;result.completion);
1011 if (!rc &amp;&amp; !ablk-&gt;result.err) {
1012 reinit_completion(&amp;ablk-&gt;result.completion);
1013 break;
1014 }
1015 default:
1016 pr_info("ablkcipher encrypt returned with %d result %d\n",
1017 rc, ablk-&gt;result.err);
1018 break;
1019 }
1020 init_completion(&amp;ablk-&gt;result.completion);
1021
1022 return rc;
1023}
1024
1025/* Initialize and trigger cipher operation */
1026static int test_ablkcipher(void)
1027{
1028 struct ablkcipher_def ablk;
1029 struct crypto_ablkcipher *ablkcipher = NULL;
1030 struct ablkcipher_request *req = NULL;
1031 char *scratchpad = NULL;
1032 char *ivdata = NULL;
1033 unsigned char key[32];
1034 int ret = -EFAULT;
1035
1036 ablkcipher = crypto_alloc_ablkcipher("cbc-aes-aesni", 0, 0);
1037 if (IS_ERR(ablkcipher)) {
1038 pr_info("could not allocate ablkcipher handle\n");
1039 return PTR_ERR(ablkcipher);
1040 }
1041
1042 req = ablkcipher_request_alloc(ablkcipher, GFP_KERNEL);
1043 if (IS_ERR(req)) {
1044 pr_info("could not allocate request queue\n");
1045 ret = PTR_ERR(req);
1046 goto out;
1047 }
1048
1049 ablkcipher_request_set_callback(req, CRYPTO_TFM_REQ_MAY_BACKLOG,
1050 test_ablkcipher_cb,
1051 &amp;ablk.result);
1052
1053 /* AES 256 with random key */
1054 get_random_bytes(&amp;key, 32);
1055 if (crypto_ablkcipher_setkey(ablkcipher, key, 32)) {
1056 pr_info("key could not be set\n");
1057 ret = -EAGAIN;
1058 goto out;
1059 }
1060
1061 /* IV will be random */
1062 ivdata = kmalloc(16, GFP_KERNEL);
1063 if (!ivdata) {
1064 pr_info("could not allocate ivdata\n");
1065 goto out;
1066 }
1067 get_random_bytes(ivdata, 16);
1068
1069 /* Input data will be random */
1070 scratchpad = kmalloc(16, GFP_KERNEL);
1071 if (!scratchpad) {
1072 pr_info("could not allocate scratchpad\n");
1073 goto out;
1074 }
1075 get_random_bytes(scratchpad, 16);
1076
1077 ablk.tfm = ablkcipher;
1078 ablk.req = req;
1079
1080 /* We encrypt one block */
1081 sg_init_one(&amp;ablk.sg, scratchpad, 16);
1082 ablkcipher_request_set_crypt(req, &amp;ablk.sg, &amp;ablk.sg, 16, ivdata);
1083 init_completion(&amp;ablk.result.completion);
1084
1085 /* encrypt data */
1086 ret = test_ablkcipher_encdec(&amp;ablk, 1);
1087 if (ret)
1088 goto out;
1089
1090 pr_info("Encryption triggered successfully\n");
1091
1092out:
1093 if (ablkcipher)
1094 crypto_free_ablkcipher(ablkcipher);
1095 if (req)
1096 ablkcipher_request_free(req);
1097 if (ivdata)
1098 kfree(ivdata);
1099 if (scratchpad)
1100 kfree(scratchpad);
1101 return ret;
1102}
1103 </programlisting>
1104 </sect1>
1105
1106 <sect1><title>Code Example For Synchronous Block Cipher Operation</title>
1107 <programlisting>
1108
1109static int test_blkcipher(void)
1110{
1111 struct crypto_blkcipher *blkcipher = NULL;
1112 char *cipher = "cbc(aes)";
1113 // AES 128
1114 charkey =
1115"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef";
1116 chariv =
1117"\x12\x34\x56\x78\x90\xab\xcd\xef\x12\x34\x56\x78\x90\xab\xcd\xef";
1118 unsigned int ivsize = 0;
1119 char *scratchpad = NULL; // holds plaintext and ciphertext
1120 struct scatterlist sg;
1121 struct blkcipher_desc desc;
1122 int ret = -EFAULT;
1123
1124 blkcipher = crypto_alloc_blkcipher(cipher, 0, 0);
1125 if (IS_ERR(blkcipher)) {
1126 printk("could not allocate blkcipher handle for %s\n", cipher);
1127 return -PTR_ERR(blkcipher);
1128 }
1129
1130 if (crypto_blkcipher_setkey(blkcipher, key, strlen(key))) {
1131 printk("key could not be set\n");
1132 ret = -EAGAIN;
1133 goto out;
1134 }
1135
1136 ivsize = crypto_blkcipher_ivsize(blkcipher);
1137 if (ivsize) {
1138 if (ivsize != strlen(iv))
1139 printk("IV length differs from expected length\n");
1140 crypto_blkcipher_set_iv(blkcipher, iv, ivsize);
1141 }
1142
1143 scratchpad = kmalloc(crypto_blkcipher_blocksize(blkcipher), GFP_KERNEL);
1144 if (!scratchpad) {
1145 printk("could not allocate scratchpad for %s\n", cipher);
1146 goto out;
1147 }
1148 /* get some random data that we want to encrypt */
1149 get_random_bytes(scratchpad, crypto_blkcipher_blocksize(blkcipher));
1150
1151 desc.flags = 0;
1152 desc.tfm = blkcipher;
1153 sg_init_one(&amp;sg, scratchpad, crypto_blkcipher_blocksize(blkcipher));
1154
1155 /* encrypt data in place */
1156 crypto_blkcipher_encrypt(&amp;desc, &amp;sg, &amp;sg,
1157 crypto_blkcipher_blocksize(blkcipher));
1158
1159 /* decrypt data in place
1160 * crypto_blkcipher_decrypt(&amp;desc, &amp;sg, &amp;sg,
1161 */ crypto_blkcipher_blocksize(blkcipher));
1162
1163
1164 printk("Cipher operation completed\n");
1165 return 0;
1166
1167out:
1168 if (blkcipher)
1169 crypto_free_blkcipher(blkcipher);
1170 if (scratchpad)
1171 kzfree(scratchpad);
1172 return ret;
1173}
1174 </programlisting>
1175 </sect1>
1176
1177 <sect1><title>Code Example For Use of Operational State Memory With SHASH</title>
1178 <programlisting>
1179
1180struct sdesc {
1181 struct shash_desc shash;
1182 char ctx[];
1183};
1184
1185static struct sdescinit_sdesc(struct crypto_shash *alg)
1186{
1187 struct sdescsdesc;
1188 int size;
1189
1190 size = sizeof(struct shash_desc) + crypto_shash_descsize(alg);
1191 sdesc = kmalloc(size, GFP_KERNEL);
1192 if (!sdesc)
1193 return ERR_PTR(-ENOMEM);
1194 sdesc-&gt;shash.tfm = alg;
1195 sdesc-&gt;shash.flags = 0x0;
1196 return sdesc;
1197}
1198
1199static int calc_hash(struct crypto_shashalg,
1200 const unsigned chardata, unsigned int datalen,
1201 unsigned chardigest) {
1202 struct sdescsdesc;
1203 int ret;
1204
1205 sdesc = init_sdesc(alg);
1206 if (IS_ERR(sdesc)) {
1207 pr_info("trusted_key: can't alloc %s\n", hash_alg);
1208 return PTR_ERR(sdesc);
1209 }
1210
1211 ret = crypto_shash_digest(&amp;sdesc-&gt;shash, data, datalen, digest);
1212 kfree(sdesc);
1213 return ret;
1214}
1215 </programlisting>
1216 </sect1>
1217
1218 <sect1><title>Code Example For Random Number Generator Usage</title>
1219 <programlisting>
1220
1221static int get_random_numbers(u8 *buf, unsigned int len)
1222{
1223 struct crypto_rngrng = NULL;
1224 chardrbg = "drbg_nopr_sha256"; /* Hash DRBG with SHA-256, no PR */
1225 int ret;
1226
1227 if (!buf || !len) {
1228 pr_debug("No output buffer provided\n");
1229 return -EINVAL;
1230 }
1231
1232 rng = crypto_alloc_rng(drbg, 0, 0);
1233 if (IS_ERR(rng)) {
1234 pr_debug("could not allocate RNG handle for %s\n", drbg);
1235 return -PTR_ERR(rng);
1236 }
1237
1238 ret = crypto_rng_get_bytes(rng, buf, len);
1239 if (ret &lt; 0)
1240 pr_debug("generation of random numbers failed\n");
1241 else if (ret == 0)
1242 pr_debug("RNG returned no data");
1243 else
1244 pr_debug("RNG returned %d bytes of data\n", ret);
1245
1246out:
1247 crypto_free_rng(rng);
1248 return ret;
1249}
1250 </programlisting>
1251 </sect1>
1252 </chapter>
1253 </book>
generated by cgit v1.2.2 (git 2.25.0) at 2024-11-28 09:34:47 -0500