Commit | Line | Data |
---|---|---|
7d12993e SM |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | |
4 | ||
5 | <book id="KernelCryptoAPI"> | |
6 | <bookinfo> | |
7 | <title>Linux Kernel Crypto API</title> | |
8 | ||
9 | <authorgroup> | |
10 | <author> | |
11 | <firstname>Stephan</firstname> | |
12 | <surname>Mueller</surname> | |
13 | <affiliation> | |
14 | <address> | |
15 | <email>smueller@chronox.de</email> | |
16 | </address> | |
17 | </affiliation> | |
18 | </author> | |
19 | <author> | |
20 | <firstname>Marek</firstname> | |
21 | <surname>Vasut</surname> | |
22 | <affiliation> | |
23 | <address> | |
24 | <email>marek@denx.de</email> | |
25 | </address> | |
26 | </affiliation> | |
27 | </author> | |
28 | </authorgroup> | |
29 | ||
30 | <copyright> | |
31 | <year>2014</year> | |
32 | <holder>Stephan Mueller</holder> | |
33 | </copyright> | |
34 | ||
35 | ||
36 | <legalnotice> | |
37 | <para> | |
38 | This documentation is free software; you can redistribute | |
39 | it and/or modify it under the terms of the GNU General Public | |
40 | License as published by the Free Software Foundation; either | |
41 | version 2 of the License, or (at your option) any later | |
42 | version. | |
43 | </para> | |
44 | ||
45 | <para> | |
46 | This program is distributed in the hope that it will be | |
47 | useful, but WITHOUT ANY WARRANTY; without even the implied | |
48 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
49 | See the GNU General Public License for more details. | |
50 | </para> | |
51 | ||
52 | <para> | |
53 | You should have received a copy of the GNU General Public | |
54 | License along with this program; if not, write to the Free | |
55 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, | |
56 | MA 02111-1307 USA | |
57 | </para> | |
58 | ||
59 | <para> | |
60 | For more details see the file COPYING in the source | |
61 | distribution of Linux. | |
62 | </para> | |
63 | </legalnotice> | |
64 | </bookinfo> | |
65 | ||
66 | <toc></toc> | |
67 | ||
68 | <chapter id="Intro"> | |
69 | <title>Kernel Crypto API Interface Specification</title> | |
70 | ||
71 | <sect1><title>Introduction</title> | |
72 | ||
73 | <para> | |
74 | The kernel crypto API offers a rich set of cryptographic ciphers as | |
75 | well as other data transformation mechanisms and methods to invoke | |
76 | these. This document contains a description of the API and provides | |
77 | example code. | |
78 | </para> | |
79 | ||
80 | <para> | |
81 | To understand and properly use the kernel crypto API a brief | |
82 | explanation of its structure is given. Based on the architecture, | |
83 | the API can be separated into different components. Following the | |
84 | architecture specification, hints to developers of ciphers are | |
85 | provided. Pointers to the API function call documentation are | |
86 | given at the end. | |
87 | </para> | |
88 | ||
89 | <para> | |
90 | The kernel crypto API refers to all algorithms as "transformations". | |
91 | Therefore, a cipher handle variable usually has the name "tfm". | |
92 | Besides cryptographic operations, the kernel crypto API also knows | |
93 | compression transformations and handles them the same way as ciphers. | |
94 | </para> | |
95 | ||
96 | <para> | |
97 | The kernel crypto API serves the following entity types: | |
98 | ||
99 | <itemizedlist> | |
100 | <listitem> | |
101 | <para>consumers requesting cryptographic services</para> | |
102 | </listitem> | |
103 | <listitem> | |
104 | <para>data transformation implementations (typically ciphers) | |
105 | that can be called by consumers using the kernel crypto | |
106 | API</para> | |
107 | </listitem> | |
108 | </itemizedlist> | |
109 | </para> | |
110 | ||
111 | <para> | |
112 | This specification is intended for consumers of the kernel crypto | |
113 | API as well as for developers implementing ciphers. This API | |
f309f165 | 114 | specification, however, does not discuss all API calls available |
7d12993e SM |
115 | to data transformation implementations (i.e. implementations of |
116 | ciphers and other transformations (such as CRC or even compression | |
117 | algorithms) that can register with the kernel crypto API). | |
118 | </para> | |
119 | ||
120 | <para> | |
121 | Note: The terms "transformation" and cipher algorithm are used | |
122 | interchangably. | |
123 | </para> | |
124 | </sect1> | |
125 | ||
126 | <sect1><title>Terminology</title> | |
127 | <para> | |
128 | The transformation implementation is an actual code or interface | |
129 | to hardware which implements a certain transformation with precisely | |
130 | defined behavior. | |
131 | </para> | |
132 | ||
133 | <para> | |
134 | The transformation object (TFM) is an instance of a transformation | |
135 | implementation. There can be multiple transformation objects | |
136 | associated with a single transformation implementation. Each of | |
137 | those transformation objects is held by a crypto API consumer or | |
138 | another transformation. Transformation object is allocated when a | |
139 | crypto API consumer requests a transformation implementation. | |
140 | The consumer is then provided with a structure, which contains | |
141 | a transformation object (TFM). | |
142 | </para> | |
143 | ||
144 | <para> | |
145 | The structure that contains transformation objects may also be | |
146 | referred to as a "cipher handle". Such a cipher handle is always | |
147 | subject to the following phases that are reflected in the API calls | |
148 | applicable to such a cipher handle: | |
149 | </para> | |
150 | ||
151 | <orderedlist> | |
152 | <listitem> | |
153 | <para>Initialization of a cipher handle.</para> | |
154 | </listitem> | |
155 | <listitem> | |
156 | <para>Execution of all intended cipher operations applicable | |
157 | for the handle where the cipher handle must be furnished to | |
158 | every API call.</para> | |
159 | </listitem> | |
160 | <listitem> | |
161 | <para>Destruction of a cipher handle.</para> | |
162 | </listitem> | |
163 | </orderedlist> | |
164 | ||
165 | <para> | |
166 | When using the initialization API calls, a cipher handle is | |
167 | created and returned to the consumer. Therefore, please refer | |
168 | to all initialization API calls that refer to the data | |
169 | structure type a consumer is expected to receive and subsequently | |
170 | to use. The initialization API calls have all the same naming | |
171 | conventions of crypto_alloc_*. | |
172 | </para> | |
173 | ||
174 | <para> | |
175 | The transformation context is private data associated with | |
176 | the transformation object. | |
177 | </para> | |
178 | </sect1> | |
179 | </chapter> | |
180 | ||
181 | <chapter id="Architecture"><title>Kernel Crypto API Architecture</title> | |
182 | <sect1><title>Cipher algorithm types</title> | |
183 | <para> | |
184 | The kernel crypto API provides different API calls for the | |
185 | following cipher types: | |
186 | ||
187 | <itemizedlist> | |
188 | <listitem><para>Symmetric ciphers</para></listitem> | |
189 | <listitem><para>AEAD ciphers</para></listitem> | |
190 | <listitem><para>Message digest, including keyed message digest</para></listitem> | |
191 | <listitem><para>Random number generation</para></listitem> | |
192 | <listitem><para>User space interface</para></listitem> | |
193 | </itemizedlist> | |
194 | </para> | |
195 | </sect1> | |
196 | ||
197 | <sect1><title>Ciphers And Templates</title> | |
198 | <para> | |
199 | The kernel crypto API provides implementations of single block | |
200 | ciphers and message digests. In addition, the kernel crypto API | |
201 | provides numerous "templates" that can be used in conjunction | |
202 | with the single block ciphers and message digests. Templates | |
203 | include all types of block chaining mode, the HMAC mechanism, etc. | |
204 | </para> | |
205 | ||
206 | <para> | |
207 | Single block ciphers and message digests can either be directly | |
208 | used by a caller or invoked together with a template to form | |
209 | multi-block ciphers or keyed message digests. | |
210 | </para> | |
211 | ||
212 | <para> | |
213 | A single block cipher may even be called with multiple templates. | |
214 | However, templates cannot be used without a single cipher. | |
215 | </para> | |
216 | ||
217 | <para> | |
218 | See /proc/crypto and search for "name". For example: | |
219 | ||
220 | <itemizedlist> | |
221 | <listitem><para>aes</para></listitem> | |
222 | <listitem><para>ecb(aes)</para></listitem> | |
223 | <listitem><para>cmac(aes)</para></listitem> | |
224 | <listitem><para>ccm(aes)</para></listitem> | |
225 | <listitem><para>rfc4106(gcm(aes))</para></listitem> | |
226 | <listitem><para>sha1</para></listitem> | |
227 | <listitem><para>hmac(sha1)</para></listitem> | |
228 | <listitem><para>authenc(hmac(sha1),cbc(aes))</para></listitem> | |
229 | </itemizedlist> | |
230 | </para> | |
231 | ||
232 | <para> | |
233 | In these examples, "aes" and "sha1" are the ciphers and all | |
234 | others are the templates. | |
235 | </para> | |
236 | </sect1> | |
237 | ||
238 | <sect1><title>Synchronous And Asynchronous Operation</title> | |
239 | <para> | |
240 | The kernel crypto API provides synchronous and asynchronous | |
241 | API operations. | |
242 | </para> | |
243 | ||
244 | <para> | |
245 | When using the synchronous API operation, the caller invokes | |
246 | a cipher operation which is performed synchronously by the | |
247 | kernel crypto API. That means, the caller waits until the | |
248 | cipher operation completes. Therefore, the kernel crypto API | |
249 | calls work like regular function calls. For synchronous | |
250 | operation, the set of API calls is small and conceptually | |
251 | similar to any other crypto library. | |
252 | </para> | |
253 | ||
254 | <para> | |
255 | Asynchronous operation is provided by the kernel crypto API | |
256 | which implies that the invocation of a cipher operation will | |
257 | complete almost instantly. That invocation triggers the | |
258 | cipher operation but it does not signal its completion. Before | |
259 | invoking a cipher operation, the caller must provide a callback | |
260 | function the kernel crypto API can invoke to signal the | |
261 | completion of the cipher operation. Furthermore, the caller | |
262 | must ensure it can handle such asynchronous events by applying | |
263 | appropriate locking around its data. The kernel crypto API | |
264 | does not perform any special serialization operation to protect | |
265 | the caller's data integrity. | |
266 | </para> | |
267 | </sect1> | |
268 | ||
269 | <sect1><title>Crypto API Cipher References And Priority</title> | |
270 | <para> | |
271 | A cipher is referenced by the caller with a string. That string | |
272 | has the following semantics: | |
273 | ||
274 | <programlisting> | |
275 | template(single block cipher) | |
276 | </programlisting> | |
277 | ||
278 | where "template" and "single block cipher" is the aforementioned | |
279 | template and single block cipher, respectively. If applicable, | |
280 | additional templates may enclose other templates, such as | |
281 | ||
282 | <programlisting> | |
283 | template1(template2(single block cipher))) | |
284 | </programlisting> | |
285 | </para> | |
286 | ||
287 | <para> | |
288 | The kernel crypto API may provide multiple implementations of a | |
289 | template or a single block cipher. For example, AES on newer | |
290 | Intel hardware has the following implementations: AES-NI, | |
291 | assembler implementation, or straight C. Now, when using the | |
292 | string "aes" with the kernel crypto API, which cipher | |
293 | implementation is used? The answer to that question is the | |
294 | priority number assigned to each cipher implementation by the | |
295 | kernel crypto API. When a caller uses the string to refer to a | |
296 | cipher during initialization of a cipher handle, the kernel | |
297 | crypto API looks up all implementations providing an | |
298 | implementation with that name and selects the implementation | |
299 | with the highest priority. | |
300 | </para> | |
301 | ||
302 | <para> | |
303 | Now, a caller may have the need to refer to a specific cipher | |
304 | implementation and thus does not want to rely on the | |
305 | priority-based selection. To accommodate this scenario, the | |
306 | kernel crypto API allows the cipher implementation to register | |
307 | a unique name in addition to common names. When using that | |
308 | unique name, a caller is therefore always sure to refer to | |
309 | the intended cipher implementation. | |
310 | </para> | |
311 | ||
312 | <para> | |
313 | The list of available ciphers is given in /proc/crypto. However, | |
314 | that list does not specify all possible permutations of | |
315 | templates and ciphers. Each block listed in /proc/crypto may | |
316 | contain the following information -- if one of the components | |
317 | listed as follows are not applicable to a cipher, it is not | |
318 | displayed: | |
319 | </para> | |
320 | ||
321 | <itemizedlist> | |
322 | <listitem> | |
323 | <para>name: the generic name of the cipher that is subject | |
324 | to the priority-based selection -- this name can be used by | |
325 | the cipher allocation API calls (all names listed above are | |
326 | examples for such generic names)</para> | |
327 | </listitem> | |
328 | <listitem> | |
329 | <para>driver: the unique name of the cipher -- this name can | |
330 | be used by the cipher allocation API calls</para> | |
331 | </listitem> | |
332 | <listitem> | |
333 | <para>module: the kernel module providing the cipher | |
334 | implementation (or "kernel" for statically linked ciphers)</para> | |
335 | </listitem> | |
336 | <listitem> | |
337 | <para>priority: the priority value of the cipher implementation</para> | |
338 | </listitem> | |
339 | <listitem> | |
340 | <para>refcnt: the reference count of the respective cipher | |
341 | (i.e. the number of current consumers of this cipher)</para> | |
342 | </listitem> | |
343 | <listitem> | |
344 | <para>selftest: specification whether the self test for the | |
345 | cipher passed</para> | |
346 | </listitem> | |
347 | <listitem> | |
348 | <para>type: | |
349 | <itemizedlist> | |
350 | <listitem> | |
351 | <para>blkcipher for synchronous block ciphers</para> | |
352 | </listitem> | |
353 | <listitem> | |
354 | <para>ablkcipher for asynchronous block ciphers</para> | |
355 | </listitem> | |
356 | <listitem> | |
357 | <para>cipher for single block ciphers that may be used with | |
358 | an additional template</para> | |
359 | </listitem> | |
360 | <listitem> | |
361 | <para>shash for synchronous message digest</para> | |
362 | </listitem> | |
363 | <listitem> | |
364 | <para>ahash for asynchronous message digest</para> | |
365 | </listitem> | |
366 | <listitem> | |
367 | <para>aead for AEAD cipher type</para> | |
368 | </listitem> | |
369 | <listitem> | |
370 | <para>compression for compression type transformations</para> | |
371 | </listitem> | |
372 | <listitem> | |
373 | <para>rng for random number generator</para> | |
374 | </listitem> | |
375 | <listitem> | |
376 | <para>givcipher for cipher with associated IV generator | |
377 | (see the geniv entry below for the specification of the | |
378 | IV generator type used by the cipher implementation)</para> | |
379 | </listitem> | |
380 | </itemizedlist> | |
381 | </para> | |
382 | </listitem> | |
383 | <listitem> | |
384 | <para>blocksize: blocksize of cipher in bytes</para> | |
385 | </listitem> | |
386 | <listitem> | |
387 | <para>keysize: key size in bytes</para> | |
388 | </listitem> | |
389 | <listitem> | |
390 | <para>ivsize: IV size in bytes</para> | |
391 | </listitem> | |
392 | <listitem> | |
393 | <para>seedsize: required size of seed data for random number | |
394 | generator</para> | |
395 | </listitem> | |
396 | <listitem> | |
397 | <para>digestsize: output size of the message digest</para> | |
398 | </listitem> | |
399 | <listitem> | |
400 | <para>geniv: IV generation type: | |
401 | <itemizedlist> | |
402 | <listitem> | |
403 | <para>eseqiv for encrypted sequence number based IV | |
404 | generation</para> | |
405 | </listitem> | |
406 | <listitem> | |
407 | <para>seqiv for sequence number based IV generation</para> | |
408 | </listitem> | |
409 | <listitem> | |
410 | <para>chainiv for chain iv generation</para> | |
411 | </listitem> | |
412 | <listitem> | |
413 | <para><builtin> is a marker that the cipher implements | |
414 | IV generation and handling as it is specific to the given | |
415 | cipher</para> | |
416 | </listitem> | |
417 | </itemizedlist> | |
418 | </para> | |
419 | </listitem> | |
420 | </itemizedlist> | |
421 | </sect1> | |
422 | ||
423 | <sect1><title>Key Sizes</title> | |
424 | <para> | |
425 | When allocating a cipher handle, the caller only specifies the | |
426 | cipher type. Symmetric ciphers, however, typically support | |
427 | multiple key sizes (e.g. AES-128 vs. AES-192 vs. AES-256). | |
428 | These key sizes are determined with the length of the provided | |
429 | key. Thus, the kernel crypto API does not provide a separate | |
430 | way to select the particular symmetric cipher key size. | |
431 | </para> | |
432 | </sect1> | |
433 | ||
434 | <sect1><title>Cipher Allocation Type And Masks</title> | |
435 | <para> | |
436 | The different cipher handle allocation functions allow the | |
437 | specification of a type and mask flag. Both parameters have | |
438 | the following meaning (and are therefore not covered in the | |
439 | subsequent sections). | |
440 | </para> | |
441 | ||
442 | <para> | |
443 | The type flag specifies the type of the cipher algorithm. | |
444 | The caller usually provides a 0 when the caller wants the | |
445 | default handling. Otherwise, the caller may provide the | |
446 | following selections which match the the aforementioned | |
447 | cipher types: | |
448 | </para> | |
449 | ||
450 | <itemizedlist> | |
451 | <listitem> | |
452 | <para>CRYPTO_ALG_TYPE_CIPHER Single block cipher</para> | |
453 | </listitem> | |
454 | <listitem> | |
455 | <para>CRYPTO_ALG_TYPE_COMPRESS Compression</para> | |
456 | </listitem> | |
457 | <listitem> | |
458 | <para>CRYPTO_ALG_TYPE_AEAD Authenticated Encryption with | |
459 | Associated Data (MAC)</para> | |
460 | </listitem> | |
461 | <listitem> | |
462 | <para>CRYPTO_ALG_TYPE_BLKCIPHER Synchronous multi-block cipher</para> | |
463 | </listitem> | |
464 | <listitem> | |
465 | <para>CRYPTO_ALG_TYPE_ABLKCIPHER Asynchronous multi-block cipher</para> | |
466 | </listitem> | |
467 | <listitem> | |
468 | <para>CRYPTO_ALG_TYPE_GIVCIPHER Asynchronous multi-block | |
469 | cipher packed together with an IV generator (see geniv field | |
470 | in the /proc/crypto listing for the known IV generators)</para> | |
471 | </listitem> | |
472 | <listitem> | |
473 | <para>CRYPTO_ALG_TYPE_DIGEST Raw message digest</para> | |
474 | </listitem> | |
475 | <listitem> | |
476 | <para>CRYPTO_ALG_TYPE_HASH Alias for CRYPTO_ALG_TYPE_DIGEST</para> | |
477 | </listitem> | |
478 | <listitem> | |
479 | <para>CRYPTO_ALG_TYPE_SHASH Synchronous multi-block hash</para> | |
480 | </listitem> | |
481 | <listitem> | |
482 | <para>CRYPTO_ALG_TYPE_AHASH Asynchronous multi-block hash</para> | |
483 | </listitem> | |
484 | <listitem> | |
485 | <para>CRYPTO_ALG_TYPE_RNG Random Number Generation</para> | |
486 | </listitem> | |
487 | <listitem> | |
488 | <para>CRYPTO_ALG_TYPE_PCOMPRESS Enhanced version of | |
489 | CRYPTO_ALG_TYPE_COMPRESS allowing for segmented compression / | |
490 | decompression instead of performing the operation on one | |
491 | segment only. CRYPTO_ALG_TYPE_PCOMPRESS is intended to replace | |
492 | CRYPTO_ALG_TYPE_COMPRESS once existing consumers are converted.</para> | |
493 | </listitem> | |
494 | </itemizedlist> | |
495 | ||
496 | <para> | |
497 | The mask flag restricts the type of cipher. The only allowed | |
498 | flag is CRYPTO_ALG_ASYNC to restrict the cipher lookup function | |
499 | to asynchronous ciphers. Usually, a caller provides a 0 for the | |
500 | mask flag. | |
501 | </para> | |
502 | ||
503 | <para> | |
504 | When the caller provides a mask and type specification, the | |
505 | caller limits the search the kernel crypto API can perform for | |
506 | a suitable cipher implementation for the given cipher name. | |
507 | That means, even when a caller uses a cipher name that exists | |
508 | during its initialization call, the kernel crypto API may not | |
509 | select it due to the used type and mask field. | |
510 | </para> | |
511 | </sect1> | |
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 < 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() -> .cia_encrypt() | |
619 | | | |
620 | '-----> 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() -> .cia_encrypt() -> .cia_setkey() -> .cia_encrypt() | |
635 | | | | |
636 | '---> CIPHERTEXT1 '---> 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() -> .update() -> .final() ! .update() might not be called | |
755 | ^ | | at all in this scenario. | |
756 | '----' '---> HASH | |
757 | ||
758 | II) DATA -----------.-----------. | |
759 | v v | |
760 | .init() -> .update() -> .finup() ! .update() may not be called | |
761 | ^ | | at all in this scenario. | |
762 | '----' '---> HASH | |
763 | ||
764 | III) DATA -----------. | |
765 | v | |
766 | .digest() ! The entire process is handled | |
767 | | by the .digest() call. | |
768 | '---------------> 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() -> .init() -> .update() -> .export() at all in this scenario. | |
780 | ^ | | | |
781 | '-----' '--> PARTIAL_HASH | |
782 | ||
783 | ----------- other transformations happen here ----------- | |
784 | ||
785 | PARTIAL_HASH--. DATA1--. | |
786 | v v | |
787 | .import -> .update() -> .final() ! .update() may not be called | |
788 | ^ | | at all in this scenario. | |
789 | '----' '--> HASH1 | |
790 | ||
791 | PARTIAL_HASH--. DATA2-. | |
792 | v v | |
793 | .import -> .finup() | |
794 | | | |
795 | '---------------> 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 | ||
968 | struct tcrypt_result { | |
969 | struct completion completion; | |
970 | int err; | |
971 | }; | |
972 | ||
973 | /* tie all data structures together */ | |
974 | struct 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 */ | |
982 | static void test_ablkcipher_cb(struct crypto_async_request *req, int error) | |
983 | { | |
984 | struct tcrypt_result *result = req->data; | |
985 | ||
986 | if (error == -EINPROGRESS) | |
987 | return; | |
988 | result->err = error; | |
989 | complete(&result->completion); | |
990 | pr_info("Encryption finished successfully\n"); | |
991 | } | |
992 | ||
993 | /* Perform cipher operation */ | |
994 | static 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->req); | |
1001 | else | |
1002 | rc = crypto_ablkcipher_decrypt(ablk->req); | |
1003 | ||
1004 | switch (rc) { | |
1005 | case 0: | |
1006 | break; | |
1007 | case -EINPROGRESS: | |
1008 | case -EBUSY: | |
1009 | rc = wait_for_completion_interruptible( | |
1010 | &ablk->result.completion); | |
1011 | if (!rc && !ablk->result.err) { | |
1012 | reinit_completion(&ablk->result.completion); | |
1013 | break; | |
1014 | } | |
1015 | default: | |
1016 | pr_info("ablkcipher encrypt returned with %d result %d\n", | |
1017 | rc, ablk->result.err); | |
1018 | break; | |
1019 | } | |
1020 | init_completion(&ablk->result.completion); | |
1021 | ||
1022 | return rc; | |
1023 | } | |
1024 | ||
1025 | /* Initialize and trigger cipher operation */ | |
1026 | static 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 | &ablk.result); | |
1052 | ||
1053 | /* AES 256 with random key */ | |
1054 | get_random_bytes(&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(&ablk.sg, scratchpad, 16); | |
1082 | ablkcipher_request_set_crypt(req, &ablk.sg, &ablk.sg, 16, ivdata); | |
1083 | init_completion(&ablk.result.completion); | |
1084 | ||
1085 | /* encrypt data */ | |
1086 | ret = test_ablkcipher_encdec(&ablk, 1); | |
1087 | if (ret) | |
1088 | goto out; | |
1089 | ||
1090 | pr_info("Encryption triggered successfully\n"); | |
1091 | ||
1092 | out: | |
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 | ||
1109 | static 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(&sg, scratchpad, crypto_blkcipher_blocksize(blkcipher)); | |
1154 | ||
1155 | /* encrypt data in place */ | |
1156 | crypto_blkcipher_encrypt(&desc, &sg, &sg, | |
1157 | crypto_blkcipher_blocksize(blkcipher)); | |
1158 | ||
1159 | /* decrypt data in place | |
1160 | * crypto_blkcipher_decrypt(&desc, &sg, &sg, | |
1161 | */ crypto_blkcipher_blocksize(blkcipher)); | |
1162 | ||
1163 | ||
1164 | printk("Cipher operation completed\n"); | |
1165 | return 0; | |
1166 | ||
1167 | out: | |
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 | ||
1180 | struct sdesc { | |
1181 | struct shash_desc shash; | |
1182 | char ctx[]; | |
1183 | }; | |
1184 | ||
1185 | static 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->shash.tfm = alg; | |
1195 | sdesc->shash.flags = 0x0; | |
1196 | return sdesc; | |
1197 | } | |
1198 | ||
1199 | static 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(&sdesc->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 | ||
1221 | static 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 < 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 | ||
1246 | out: | |
1247 | crypto_free_rng(rng); | |
1248 | return ret; | |
1249 | } | |
1250 | </programlisting> | |
1251 | </sect1> | |
1252 | </chapter> | |
1253 | </book> |