1 .\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $
3 .\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu)
5 .\" Copyright (c) 2000, 2001 Angelos D. Keromytis
7 .\" Permission to use, copy, and modify this software with or without fee
8 .\" is hereby granted, provided that this entire notice is included in
9 .\" all source code copies of any software which is or includes a copy or
10 .\" modification of this software.
12 .\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
13 .\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY
14 .\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
15 .\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
18 .\" $FreeBSD: src/share/man/man9/crypto.9,v 1.14 2007/09/19 16:28:46 brueffer Exp $
25 .Nd API for cryptographic services in the kernel
27 .In opencrypto/cryptodev.h
29 .Fn crypto_get_driverid "device_t dev" "int flags"
31 .Fn crypto_find_driver "const char *match"
33 .Fn crypto_find_device_byhid "int hid"
35 .Fn crypto_getcaps "int hid"
37 .Fn crypto_register "u_int32_t driverid" "int alg" "u_int16_t maxoplen" "u_int32_t flags"
39 .Fn crypto_kregister "u_int32_t driverid" "int kalg" "u_int32_t flags"
41 .Fn crypto_unregister "u_int32_t driverid" "int alg"
43 .Fn crypto_unregister_all "u_int32_t driverid"
45 .Fn crypto_done "struct cryptop *crp"
47 .Fn crypto_kdone "struct cryptkop *krp"
49 .Fn crypto_newsession "u_int64_t *sid" "struct cryptoini *cri" "int crid"
51 .Fn crypto_freesession "u_int64_t sid"
53 .Fn crypto_dispatch "struct cryptop *crp"
55 .Fn crypto_kdispatch "struct cryptkop *krp"
57 .Fn crypto_unblock "u_int32_t driverid" "int what"
58 .Ft "struct cryptop *"
59 .Fn crypto_getreq "int num"
61 .Fn crypto_freereq "struct cryptop *crp"
63 #define CRYPTO_SYMQ 0x1
64 #define CRYPTO_ASYMQ 0x2
66 #define EALG_MAX_BLOCK_LEN 16
73 u_int8_t cri_iv[EALG_MAX_BLOCK_LEN];
74 struct cryptoini *cri_next;
82 struct cryptoini CRD_INI;
83 #define crd_iv CRD_INI.cri_iv
84 #define crd_key CRD_INI.cri_key
85 #define crd_alg CRD_INI.cri_alg
86 #define crd_klen CRD_INI.cri_klen
87 struct cryptodesc *crd_next;
91 TAILQ_ENTRY(cryptop) crp_next;
99 struct cryptodesc *crp_desc;
100 int (*crp_callback) (struct cryptop *);
109 #define CRK_MAXPARAM 8
112 TAILQ_ENTRY(cryptkop) krp_next;
113 u_int krp_op; /* ie. CRK_MOD_EXP or other */
114 u_int krp_status; /* return status */
115 u_short krp_iparams; /* # of input parameters */
116 u_short krp_oparams; /* # of output parameters */
118 struct crparam krp_param[CRK_MAXPARAM];
119 int (*krp_callback)(struct cryptkop *);
124 is a framework for drivers of cryptographic hardware to register with
127 (other kernel subsystems, and
130 device) are able to make use of it.
131 Drivers register with the framework the algorithms they support,
132 and provide entry points (functions) the framework may call to
133 establish, use, and tear down sessions.
134 Sessions are used to cache cryptographic information in a particular driver
135 (or associated hardware), so initialization is not needed with every request.
136 Consumers of cryptographic services pass a set of
137 descriptors that instruct the framework (and the drivers registered
138 with it) of the operations that should be applied on the data (more
139 than one cryptographic operation can be requested).
141 Keying operations are supported as well.
142 Unlike the symmetric operators described above,
143 these sessionless commands perform mathematical operations using
144 input and output parameters.
146 Since the consumers may not be associated with a process, drivers may
149 The same holds for the framework.
150 Thus, a callback mechanism is used
151 to notify a consumer that a request has been completed (the
152 callback is specified by the consumer on an per-request basis).
153 The callback is invoked by the framework whether the request was
154 successfully completed or not.
155 An error indication is provided in the latter case.
156 A specific error code,
158 is used to indicate that a session number has changed and that the
159 request may be re-submitted immediately with the new session number.
160 Errors are only returned to the invoking function if not
161 enough information to call the callback is available (meaning, there
162 was a fatal error in verifying the arguments).
163 For session initialization and teardown there is no callback mechanism used.
166 .Fn crypto_newsession
167 routine is called by consumers of cryptographic services (such as the
169 stack) that wish to establish a new session with the framework.
170 On success, the first argument will contain the Session Identifier (SID).
171 The second argument contains all the necessary information for
172 the driver to establish the session.
173 The third argument indicates whether a
174 hardware driver (1) should be used or not (0).
175 The various fields in the
178 .Bl -tag -width ".Va cri_next"
180 Contains an algorithm identifier.
181 Currently supported algorithms are:
183 .Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
184 .It Dv CRYPTO_AES_CBC
185 .It Dv CRYPTO_AES_XTS
186 .It Dv CRYPTO_AES_CTR
187 .It Dv CRYPTO_AES_GCM
188 .It Dv CRYPTO_AES_GMAC
189 .It Dv CRYPTO_AES_128_GMAC
190 .It Dv CRYPTO_AES_192_GMAC
191 .It Dv CRYPTO_AES_256_GMAC
192 .It Dv CRYPTO_TWOFISH_CBC
193 .It Dv CRYPTO_TWOFISH_XTS
194 .It Dv CRYPTO_SERPENT_CBC
195 .It Dv CRYPTO_SERPENT_XTS
197 .It Dv CRYPTO_BLF_CBC
198 .It Dv CRYPTO_CAMELLIA_CBC
199 .It Dv CRYPTO_CAST_CBC
200 .It Dv CRYPTO_DES_CBC
201 .It Dv CRYPTO_3DES_CBC
202 .It Dv CRYPTO_SKIPJACK_CBC
204 .It Dv CRYPTO_MD5_HMAC
205 .It Dv CRYPTO_MD5_KPDK
206 .It Dv CRYPTO_RIPEMD160_HMAC
208 .It Dv CRYPTO_SHA1_HMAC
209 .It Dv CRYPTO_SHA1_KPDK
210 .It Dv CRYPTO_SHA2_256_HMAC
211 .It Dv CRYPTO_SHA2_384_HMAC
212 .It Dv CRYPTO_SHA2_512_HMAC
213 .It Dv CRYPTO_NULL_HMAC
214 .It Dv CRYPTO_NULL_CBC
217 Specifies the length of the key in bits, for variable-size key
220 Specifies how many bytes from the calculated hash should be copied back.
223 Contains the key to be used with the algorithm.
225 Contains an explicit initialization vector (IV), if it does not prefix
227 This field is ignored during initialization.
228 If no IV is explicitly passed (see below on details), a random IV is used
229 by the device driver processing the request.
231 Contains a pointer to another
234 Multiple such structures may be linked to establish multi-algorithm sessions
236 is an example consumer of such a feature).
241 structure and its contents will not be modified by the framework (or
243 Subsequent requests for processing that use the
244 SID returned will avoid the cost of re-initializing the hardware (in
245 essence, SID acts as an index in the session cache of the driver).
247 .Fn crypto_freesession
248 is called with the SID returned by
249 .Fn crypto_newsession
250 to disestablish the session.
253 is called to process a request.
254 The various fields in the
257 .Bl -tag -width ".Va crp_callback"
261 Indicates the total length in bytes of the buffer to be processed.
263 On return, contains the total length of the result.
264 For symmetric crypto operations, this will be the same as the input length.
265 This will be used if the framework needs to allocate a new
266 buffer for the result (or for re-formatting the input).
268 This routine is invoked upon completion of the request, whether
270 It is invoked through the
273 If the request was not successful, an error code is set in the
276 It is the responsibility of the callback routine to enter a critical
279 Contains the error type, if any errors were encountered, or zero if
280 the request was successfully processed.
283 error code is returned, the SID has changed (and has been recorded in the
286 The consumer should record the new SID and use it in all subsequent requests.
287 In this case, the request may be re-submitted immediately.
288 This mechanism is used by the framework to perform
289 session migration (move a session from one driver to another, because
290 of availability, performance, or other considerations).
292 Note that this field only makes sense when examined by
293 the callback routine specified in
295 Errors are returned to the invoker of
297 only when enough information is not present to call the callback
298 routine (i.e., if the pointer passed is
300 or if no callback routine was specified).
302 Is a bitmask of flags associated with this request.
303 Currently defined flags are:
304 .Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC"
305 .It Dv CRYPTO_F_IMBUF
306 The buffer pointed to by
310 The buffer pointed to by
316 Must return data in the same place.
317 .It Dv CRYPTO_F_BATCH
318 Batch operation if possible.
319 .It Dv CRYPTO_F_CBIMM
320 Do callback immediately instead of doing it from a dedicated kernel thread.
323 .It Dv CRYPTO_F_CBIFSYNC
324 Do callback immediately if operation is synchronous.
327 Points to the input buffer.
328 On return (when the callback is invoked),
329 it contains the result of the request.
330 The input buffer may be an mbuf
331 chain or a contiguous buffer,
335 This is passed through the crypto framework untouched and is
336 intended for the invoking application's use.
338 This is a linked list of descriptors.
339 Each descriptor provides
340 information about what type of cryptographic operation should be done
342 The various fields are:
343 .Bl -tag -width ".Va crd_inject"
345 The field where IV should be provided when the
346 .Dv CRD_F_IV_EXPLICIT
350 .Dv CRD_F_KEY_EXPLICIT
353 points to a buffer with encryption or authentication key.
356 Must be the same as the one given at newsession time.
362 The offset in the input buffer where processing should start.
364 How many bytes, after
368 Offset from the beginning of the buffer to insert any results.
369 For encryption algorithms, this is where the initialization vector
370 (IV) will be inserted when encrypting or where it can be found when
371 decrypting (subject to
373 For MAC algorithms, this is where the result of the keyed hash will be
376 The following flags are defined:
379 For encryption algorithms, this bit is set when encryption is required
380 (when not set, decryption is performed).
381 .It Dv CRD_F_IV_PRESENT
382 For encryption algorithms, this bit is set when the IV already
383 precedes the data, so the
385 value will be ignored and no IV will be written in the buffer.
386 Otherwise, the IV used to encrypt the packet will be written
387 at the location pointed to by
389 The IV length is assumed to be equal to the blocksize of the
390 encryption algorithm.
391 Some applications that do special
393 such as the half-IV mode in
395 can use this flag to indicate that the IV should not be written on the packet.
396 This flag is typically used in conjunction with the
397 .Dv CRD_F_IV_EXPLICIT
399 .It Dv CRD_F_IV_EXPLICIT
400 For encryption algorithms, this bit is set when the IV is explicitly
401 provided by the consumer in the
404 Otherwise, for encryption operations the IV is provided for by
405 the driver used to perform the operation, whereas for decryption
406 operations it is pointed to by the
409 This flag is typically used when the IV is calculated
411 by the consumer, and does not precede the data (some
413 configurations, and the encrypted swap are two such examples).
414 .It Dv CRD_F_KEY_EXPLICIT
415 For encryption and authentication (MAC) algorithms, this bit is set when the key
416 is explicitly provided by the consumer in the
418 field for the given operation.
419 Otherwise, the key is taken at newsession time from the
423 For compression algorithms, this bit is set when compression is required (when
424 not set, decompression is performed).
429 structure will not be modified by the framework or the device drivers.
430 Since this information accompanies every cryptographic
431 operation request, drivers may re-initialize state on-demand
432 (typically an expensive operation).
433 Furthermore, the cryptographic
434 framework may re-route requests as a result of full queues or hardware
435 failure, as described above.
437 Point to the next descriptor.
438 Linked operations are useful in protocols such as
440 where multiple cryptographic transforms may be applied on the same
448 structure with a linked list of as many
450 structures as were specified in the argument passed to it.
453 deallocates a structure
457 structures linked to it.
458 Note that it is the responsibility of the
459 callback routine to do the necessary cleanups associated with the
465 is called to perform a keying operation.
466 The various fields in the
469 .Bl -tag -width ".Va krp_callback"
471 Operation code, such as
477 variable indicates whether lower level reasons
478 for operation failure.
480 Number if input parameters to the specified operation.
481 Note that each operation has a (typically hardwired) number of such parameters.
483 Number if output parameters from the specified operation.
484 Note that each operation has a (typically hardwired) number of such parameters.
486 An array of kernel memory blocks containing the parameters.
488 Identifier specifying which low-level driver is being used.
490 Callback called on completion of a keying operation.
494 .Fn crypto_get_driverid ,
495 .Fn crypto_register ,
496 .Fn crypto_kregister ,
497 .Fn crypto_unregister ,
501 routines are used by drivers that provide support for cryptographic
502 primitives to register and unregister with the kernel crypto services
504 Drivers must first use the
505 .Fn crypto_get_driverid
506 function to acquire a driver identifier, specifying the
508 as an argument (normally 0, but software-only drivers should specify
509 .Dv CRYPTOCAP_F_SOFTWARE ) .
510 For each algorithm the driver supports, it must then call
511 .Fn crypto_register .
512 The first two arguments are the driver and algorithm identifiers.
513 The next two arguments specify the largest possible operator length (in bits,
514 important for public key operations) and flags for this algorithm.
515 The last four arguments must be provided in the first call to
517 and are ignored in all subsequent calls.
518 They are pointers to three
519 driver-provided functions that the framework may call to establish new
520 cryptographic context with the driver, free already established
521 context, and ask for a request to be processed (encrypt, decrypt,
522 etc.); and an opaque parameter to pass when calling each of these routines.
523 .Fn crypto_unregister
524 is called by drivers that wish to withdraw support for an algorithm.
525 The two arguments are the driver and algorithm identifiers, respectively.
526 Typically, drivers for
528 crypto cards that are being ejected will invoke this routine for all
529 algorithms supported by the card.
530 .Fn crypto_unregister_all
531 will unregister all algorithms registered by a driver
532 and the driver will be disabled (no new sessions will be allocated on
533 that driver, and any existing sessions will be migrated to other
535 The same will be done if all algorithms associated with a driver are
536 unregistered one by one.
538 The calling convention for the three driver-supplied routines is:
543 .Fn \*[lp]*newsession\*[rp] "void *" "u_int32_t *" "struct cryptoini *" ;
546 .Fn \*[lp]*freesession\*[rp] "void *" "u_int64_t" ;
549 .Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ;
552 .Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ;
555 On invocation, the first argument to
556 all routines is an opaque data value supplied when the algorithm
558 .Fn crypto_register .
559 The second argument to
561 contains the driver identifier obtained via
562 .Fn crypto_get_driverid .
563 On successful return, it should contain a driver-specific session
565 The third argument is identical to that of
566 .Fn crypto_newsession .
570 routine takes as arguments the opaque data value and the SID
571 (which is the concatenation of the
572 driver identifier and the driver-specific session identifier).
573 It should clear any context associated with the session (clear hardware
574 registers, memory, etc.).
578 routine is invoked with a request to perform crypto processing.
579 This routine must not block, but should queue the request and return
581 Upon processing the request, the callback routine should be invoked.
582 In case of an unrecoverable error, the error indication must be placed in the
587 When the request is completed, or an error is detected, the
589 routine should invoke
591 Session migration may be performed, as mentioned previously.
593 In case of a temporary resource exhaustion, the
597 in which case the crypto services will requeue the request, mark the driver
600 and stop submitting requests for processing.
601 The driver is then responsible for notifying the crypto services
602 when it is again able to process requests through the
605 This simple flow control mechanism should only be used for short-lived
606 resource exhaustion as it causes operations to be queued in the crypto
608 Doing so is preferable to returning an error in such cases as
609 it can cause network protocols to degrade performance by treating the
610 failure much like a lost packet.
614 routine is invoked with a request to perform crypto key processing.
615 This routine must not block, but should queue the request and return
617 Upon processing the request, the callback routine should be invoked.
618 In case of an unrecoverable error, the error indication must be placed in the
623 When the request is completed, or an error is detected, the
625 routine should invoked
628 .Fn crypto_register ,
629 .Fn crypto_kregister ,
630 .Fn crypto_unregister ,
631 .Fn crypto_newsession ,
632 .Fn crypto_freesession ,
635 return 0 on success, or an error code on failure.
636 .Fn crypto_get_driverid
637 returns a non-negative value on error, and \-1 on failure.
639 returns a pointer to a
647 if its argument or the callback function was
650 The callback is provided with an error code in case of failure, in the
654 .Bl -tag -width ".Pa sys/opencrypto/crypto.c"
655 .It Pa sys/opencrypto/crypto.c
656 most of the framework code
663 The cryptographic framework first appeared in
666 .An "Angelos D. Keromytis" Aq angelos@openbsd.org .
668 The framework currently assumes that all the algorithms in a
669 .Fn crypto_newsession
670 operation must be available by the same driver.
671 If that is not the case, session initialization will fail.
673 The framework also needs a mechanism for determining which driver is
674 best for a specific set of algorithms associated with a session.
675 Some type of benchmarking is in order here.
677 Multiple instances of the same algorithm in the same session are not
679 Note that 3DES is considered one algorithm (and not three
681 Thus, 3DES and DES could be mixed in the same request.