1 .\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $
3 .\" The author of this man 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.3.2.2 2003/01/28 17:11:48 sam Exp $
19 .\" $DragonFly: src/share/man/man9/crypto.9,v 1.2 2003/06/17 04:37:01 dillon Exp $
26 .Nd API for cryptographic services in the kernel
28 .In opencrypto/cryptodev.h
30 .Fn crypto_get_driverid u_int8_t
32 .Fn crypto_register u_int32_t int u_int16_t u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, u_int32_t *, struct cryptoini *\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, u_int64_t\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, struct cryptop *\*[rp]" "void *"
34 .Fn crypto_kregister u_int32_t int u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *"
36 .Fn crypto_unregister u_int32_t int
38 .Fn crypto_unregister_all u_int32_t
40 .Fn crypto_done "struct cryptop *"
42 .Fn crypto_kdone "struct cryptkop *"
44 .Fn crypto_newsession "u_int64_t *" "struct cryptoini *" int
46 .Fn crypto_freesession u_int64_t
48 .Fn crypto_dispatch "struct cryptop *"
50 .Fn crypto_kdispatch "struct cryptkop *"
52 .Fn crypto_unblock u_int32_t int
53 .Ft "struct cryptop *"
56 .Fn crypto_freereq void
58 #define CRYPTO_SYMQ 0x1
59 #define CRYPTO_ASYMQ 0x2
61 #define EALG_MAX_BLOCK_LEN 16
68 u_int8_t cri_iv[EALG_MAX_BLOCK_LEN];
69 struct cryptoini *cri_next;
77 struct cryptoini CRD_INI;
78 struct cryptodesc *crd_next;
82 TAILQ_ENTRY(cryptop) crp_next;
90 struct cryptodesc *crp_desc;
91 int (*crp_callback) (struct cryptop *);
100 #define CRK_MAXPARAM 8
103 TAILQ_ENTRY(cryptkop) krp_next;
104 u_int krp_op; /* ie. CRK_MOD_EXP or other */
105 u_int krp_status; /* return status */
106 u_short krp_iparams; /* # of input parameters */
107 u_short krp_oparams; /* # of output parameters */
109 struct crparam krp_param[CRK_MAXPARAM];
110 int (*krp_callback)(struct cryptkop *);
115 is a framework for drivers of cryptographic hardware to register with
118 (other kernel subsystems, and
121 device) are able to make use of it.
122 Drivers register with the framework the algorithms they support,
123 and provide entry points (functions) the framework may call to
124 establish, use, and tear down sessions.
125 Sessions are used to cache cryptographic information in a particular driver
126 (or associated hardware), so initialization is not needed with every request.
127 Consumers of cryptographic services pass a set of
128 descriptors that instruct the framework (and the drivers registered
129 with it) of the operations that should be applied on the data (more
130 than one cryptographic operation can be requested).
132 Keying operations are supported as well.
133 Unlike the symmetric operators described above,
134 these sessionless commands perform mathematical operations using
135 input and output parameters.
137 Since the consumers may not be associated with a process, drivers may
140 The same holds for the framework.
141 Thus, a callback mechanism is used
142 to notify a consumer that a request has been completed (the
143 callback is specified by the consumer on an per-request basis).
144 The callback is invoked by the framework whether the request was
145 successfully completed or not.
146 An error indication is provided in the latter case.
147 A specific error code,
149 is used to indicate that a session number has changed and that the
150 request may be re-submitted immediately with the new session number.
151 Errors are only returned to the invoking function if not
152 enough information to call the callback is available (meaning, there
153 was a fatal error in verifying the arguments).
154 For session initialization and teardown there is no callback mechanism used.
157 .Fn crypto_newsession
158 routine is called by consumers of cryptographic services (such as the
160 stack) that wish to establish a new session with the framework.
161 On success, the first argument will contain the Session Identifier (SID).
162 The second argument contains all the necessary information for
163 the driver to establish the session.
164 The third argument indicates whether a
165 hardware driver (1) should be used or not (0).
166 The various fields in the
169 .Bl -tag -width ".Va cri_next"
171 Contains an algorithm identifier.
172 Currently supported algorithms are:
174 .Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
175 .It Dv CRYPTO_DES_CBC
176 .It Dv CRYPTO_3DES_CBC
177 .It Dv CRYPTO_BLF_CBC
178 .It Dv CRYPTO_CAST_CBC
179 .It Dv CRYPTO_SKIPJACK_CBC
180 .It Dv CRYPTO_MD5_HMAC
181 .It Dv CRYPTO_SHA1_HMAC
182 .It Dv CRYPTO_RIPEMD160_HMAC
183 .It Dv CRYPTO_MD5_KPDK
184 .It Dv CRYPTO_SHA1_KPDK
185 .It Dv CRYPTO_AES_CBC
189 .It Dv CRYPTO_SHA2_HMAC
190 .It Dv CRYPTO_NULL_HMAC
191 .It Dv CRYPTO_NULL_CBC
194 Specifies the length of the key in bits, for variable-size key
197 Specifies the number of rounds to be used with the algorithm, for
198 variable-round algorithms.
200 Contains the key to be used with the algorithm.
202 Contains an explicit initialization vector (IV), if it does not prefix
204 This field is ignored during initialization.
205 If no IV is explicitly passed (see below on details), a random IV is used
206 by the device driver processing the request.
208 Contains a pointer to another
211 Multiple such structures may be linked to establish multi-algorithm sessions
213 is an example consumer of such a feature).
218 structure and its contents will not be modified by the framework (or
220 Subsequent requests for processing that use the
221 SID returned will avoid the cost of re-initializing the hardware (in
222 essence, SID acts as an index in the session cache of the driver).
224 .Fn crypto_freesession
225 is called with the SID returned by
226 .Fn crypto_newsession
227 to disestablish the session.
230 is called to process a request.
231 The various fields in the
234 .Bl -tag -width ".Va crp_callback"
238 Indicates the total length in bytes of the buffer to be processed.
240 On return, contains the total length of the result.
241 For symmetric crypto operations, this will be the same as the input length.
242 This will be used if the framework needs to allocate a new
243 buffer for the result (or for re-formatting the input).
245 This routine is invoked upon completion of the request, whether
247 It is invoked through the
250 If the request was not successful, an error code is set in the
253 It is the responsibility of the callback routine to set the appropriate
257 Contains the error type, if any errors were encountered, or zero if
258 the request was successfully processed.
261 error code is returned, the SID has changed (and has been recorded in the
264 The consumer should record the new SID and use it in all subsequent requests.
265 In this case, the request may be re-submitted immediately.
266 This mechanism is used by the framework to perform
267 session migration (move a session from one driver to another, because
268 of availability, performance, or other considerations).
270 Note that this field only makes sense when examined by
271 the callback routine specified in
273 Errors are returned to the invoker of
275 only when enough information is not present to call the callback
276 routine (i.e., if the pointer passed is
278 or if no callback routine was specified).
280 Is a bitmask of flags associated with this request.
281 Currently defined flags are:
282 .Bl -tag -width ".Dv CRYPTO_F_IMBUF"
283 .It Dv CRYPTO_F_IMBUF
284 The buffer pointed to by
289 Points to the input buffer.
290 On return (when the callback is invoked),
291 it contains the result of the request.
292 The input buffer may be an mbuf
293 chain or a contiguous buffer,
297 This is passed through the crypto framework untouched and is
298 intended for the invoking application's use.
300 This is a linked list of descriptors.
301 Each descriptor provides
302 information about what type of cryptographic operation should be done
304 The various fields are:
305 .Bl -tag -width ".Va crd_inject"
307 The offset in the input buffer where processing should start.
309 How many bytes, after
313 Offset from the beginning of the buffer to insert any results.
314 For encryption algorithms, this is where the initialization vector
315 (IV) will be inserted when encrypting or where it can be found when
316 decrypting (subject to
318 For MAC algorithms, this is where the result of the keyed hash will be
321 The following flags are defined:
322 .Bl -tag -width ".Dv CRD_F_IV_EXPLICIT"
324 For encryption algorithms, this bit is set when encryption is required
325 (when not set, decryption is performed).
326 .It Dv CRD_F_IV_PRESENT
327 For encryption algorithms, this bit is set when the IV already
328 precedes the data, so the
330 value will be ignored and no IV will be written in the buffer.
331 Otherwise, the IV used to encrypt the packet will be written
332 at the location pointed to by
334 The IV length is assumed to be equal to the blocksize of the
335 encryption algorithm.
336 Some applications that do special
338 such as the half-IV mode in
340 can use this flag to indicate that the IV should not be written on the packet.
341 This flag is typically used in conjunction with the
342 .Dv CRD_F_IV_EXPLICIT
344 .It Dv CRD_F_IV_EXPLICIT
345 For encryption algorithms, this bit is set when the IV is explicitly
346 provided by the consumer in the
349 Otherwise, for encryption operations the IV is provided for by
350 the driver used to perform the operation, whereas for decryption
351 operations it is pointed to by the
354 This flag is typically used when the IV is calculated
356 by the consumer, and does not precede the data (some
358 configurations, and the encrypted swap are two such examples).
360 For compression algorithms, this bit is set when compression is required (when
361 not set, decompression is performed).
366 structure will not be modified by the framework or the device drivers.
367 Since this information accompanies every cryptographic
368 operation request, drivers may re-initialize state on-demand
369 (typically an expensive operation).
370 Furthermore, the cryptographic
371 framework may re-route requests as a result of full queues or hardware
372 failure, as described above.
374 Point to the next descriptor.
375 Linked operations are useful in protocols such as
377 where multiple cryptographic transforms may be applied on the same
385 structure with a linked list of as many
387 structures as were specified in the argument passed to it.
390 deallocates a structure
394 structures linked to it.
395 Note that it is the responsibility of the
396 callback routine to do the necessary cleanups associated with the
402 is called to perform a keying operation.
403 The various fields in the
406 .Bl -tag -width ".Va krp_callback'
408 Operation code, such as
414 variable indicates whether lower level reasons
415 for operation failure.
417 Number if input parameters to the specified operation.
418 Note that each operation has a (typically hardwired) number of such parameters.
420 Number if output parameters from the specified operation.
421 Note that each operation has a (typically hardwired) number of such parameters.
423 An array of kernel memory blocks containing the parameters.
425 Identifier specifying which low-level driver is being used.
427 Callback called on completion of a keying operation.
431 .Fn crypto_get_driverid ,
432 .Fn crypto_register ,
433 .Fn crypto_kregister ,
434 .Fn crypto_unregister ,
438 routines are used by drivers that provide support for cryptographic
439 primitives to register and unregister with the kernel crypto services
441 Drivers must first use the
442 .Fn crypto_get_driverid
443 function to acquire a driver identifier, specifying the
445 as an argument (normally 0, but software-only drivers should specify
446 .Dv CRYPTOCAP_F_SOFTWARE ) .
447 For each algorithm the driver supports, it must then call
448 .Fn crypto_register .
449 The first two arguments are the driver and algorithm identifiers.
450 The next two arguments specify the largest possible operator length (in bits,
451 important for public key operations) and flags for this algorithm.
452 The last four arguments must be provided in the first call to
454 and are ignored in all subsequent calls.
455 They are pointers to three
456 driver-provided functions that the framework may call to establish new
457 cryptographic context with the driver, free already established
458 context, and ask for a request to be processed (encrypt, decrypt,
459 etc.); and an opaque parameter to pass when calling each of these routines.
460 .Fn crypto_unregister
461 is called by drivers that wish to withdraw support for an algorithm.
462 The two arguments are the driver and algorithm identifiers, respectively.
463 Typically, drivers for
465 crypto cards that are being ejected will invoke this routine for all
466 algorithms supported by the card.
467 .Fn crypto_unregister_all
468 will unregister all algorithms registered by a driver
469 and the driver will be disabled (no new sessions will be allocated on
470 that driver, and any existing sessions will be migrated to other
472 The same will be done if all algorithms associated with a driver are
473 unregistered one by one.
475 The calling convention for the three driver-supplied routines is:
480 .Fn \*[lp]*newsession\*[rp] "void *" "u_int32_t *" "struct cryptoini *" ;
483 .Fn \*[lp]*freesession\*[rp] "void *" "u_int64_t" ;
486 .Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ;
489 .Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ;
492 On invocation, the first argument to
493 all routines is an opaque data value supplied when the algorithm
495 .Fn crypto_register .
496 The second argument to
498 contains the driver identifier obtained via
499 .Fn crypto_get_driverid .
500 On successful return, it should contain a driver-specific session
502 The third argument is identical to that of
503 .Fn crypto_newsession .
507 routine takes as arguments the opaque data value and the SID
508 (which is the concatenation of the
509 driver identifier and the driver-specific session identifier).
510 It should clear any context associated with the session (clear hardware
511 registers, memory, etc.).
515 routine is invoked with a request to perform crypto processing.
516 This routine must not block, but should queue the request and return
518 Upon processing the request, the callback routine should be invoked.
519 In case of an unrecoverable error, the error indication must be placed in the
524 When the request is completed, or an error is detected, the
526 routine should invoke
528 Session migration may be performed, as mentioned previously.
530 In case of a temporary resource exhaustion, the
534 in which case the crypto services will requeue the request, mark the driver
537 and stop submitting requests for processing.
538 The driver is then responsible for notifying the crypto services
539 when it is again able to process requests through the
542 This simple flow control mechanism should only be used for short-lived
543 resource exhaustion as it causes operations to be queued in the crypto
545 Doing so is preferable to returning an error in such cases as
546 it can cause network protocols to degrade performance by treating the
547 failure much like a lost packet.
551 routine is invoked with a request to perform crypto key processing.
552 This routine must not block, but should queue the request and return
554 Upon processing the request, the callback routine should be invoked.
555 In case of an unrecoverable error, the error indication must be placed in the
560 When the request is completed, or an error is detected, the
562 routine should invoked
565 .Fn crypto_register ,
566 .Fn crypto_kregister ,
567 .Fn crypto_unregister ,
568 .Fn crypto_newsession ,
569 .Fn crypto_freesession ,
572 return 0 on success, or an error code on failure.
573 .Fn crypto_get_driverid
574 returns a non-negative value on error, and \-1 on failure.
576 returns a pointer to a
584 if its argument or the callback function was
587 The callback is provided with an error code in case of failure, in the
591 .Bl -tag -width ".Pa sys/opencrypto/crypto.c"
592 .It Pa sys/opencrypto/crypto.c
593 most of the framework code
600 The cryptographic framework first appeared in
603 .An "Angelos D. Keromytis" Aq angelos@openbsd.org .
605 The framework currently assumes that all the algorithms in a
606 .Fn crypto_newsession
607 operation must be available by the same driver.
608 If that is not the case, session initialization will fail.
610 The framework also needs a mechanism for determining which driver is
611 best for a specific set of algorithms associated with a session.
612 Some type of benchmarking is in order here.
614 Multiple instances of the same algorithm in the same session are not
616 Note that 3DES is considered one algorithm (and not three
618 Thus, 3DES and DES could be mixed in the same request.