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
25 .Nd API for cryptographic services in the kernel
27 .In opencrypto/cryptodev.h
29 .Fn crypto_get_driverid "device_t dev" "size_t session_size" "int flags"
31 .Fn crypto_register "uint32_t driverid" "int alg" "uint16_t maxoplen" "uint32_t flags"
33 .Fn crypto_kregister "uint32_t driverid" "int kalg" "uint32_t flags"
35 .Fn crypto_unregister "uint32_t driverid" "int alg"
37 .Fn crypto_unregister_all "uint32_t driverid"
39 .Fn crypto_done "struct cryptop *crp"
41 .Fn crypto_kdone "struct cryptkop *krp"
43 .Fn crypto_find_driver "const char *match"
45 .Fn crypto_newsession "crypto_session_t *cses" "struct cryptoini *cri" "int crid"
47 .Fn crypto_freesession "crypto_session_t cses"
49 .Fn crypto_dispatch "struct cryptop *crp"
51 .Fn crypto_kdispatch "struct cryptkop *krp"
53 .Fn crypto_unblock "uint32_t driverid" "int what"
54 .Ft "struct cryptop *"
55 .Fn crypto_getreq "int num"
57 .Fn crypto_freereq "struct cryptop *crp"
59 #define CRYPTO_SYMQ 0x1
60 #define CRYPTO_ASYMQ 0x2
62 #define EALG_MAX_BLOCK_LEN 16
69 uint8_t cri_iv[EALG_MAX_BLOCK_LEN];
70 struct cryptoini *cri_next;
78 struct cryptoini CRD_INI;
79 #define crd_iv CRD_INI.cri_iv
80 #define crd_key CRD_INI.cri_key
81 #define crd_alg CRD_INI.cri_alg
82 #define crd_klen CRD_INI.cri_klen
83 struct cryptodesc *crd_next;
87 TAILQ_ENTRY(cryptop) crp_next;
88 crypto_session_t crp_session;
95 struct cryptodesc *crp_desc;
96 int (*crp_callback) (struct cryptop *);
105 #define CRK_MAXPARAM 8
108 TAILQ_ENTRY(cryptkop) krp_next;
109 u_int krp_op; /* ie. CRK_MOD_EXP or other */
110 u_int krp_status; /* return status */
111 u_short krp_iparams; /* # of input parameters */
112 u_short krp_oparams; /* # of output parameters */
114 struct crparam krp_param[CRK_MAXPARAM];
115 int (*krp_callback)(struct cryptkop *);
120 is a framework for drivers of cryptographic hardware to register with
123 (other kernel subsystems, and
126 device) are able to make use of it.
127 Drivers register with the framework the algorithms they support,
128 and provide entry points (functions) the framework may call to
129 establish, use, and tear down sessions.
130 Sessions are used to cache cryptographic information in a particular driver
131 (or associated hardware), so initialization is not needed with every request.
132 Consumers of cryptographic services pass a set of
133 descriptors that instruct the framework (and the drivers registered
134 with it) of the operations that should be applied on the data (more
135 than one cryptographic operation can be requested).
137 Keying operations are supported as well.
138 Unlike the symmetric operators described above,
139 these sessionless commands perform mathematical operations using
140 input and output parameters.
142 Since the consumers may not be associated with a process, drivers may
145 The same holds for the framework.
146 Thus, a callback mechanism is used
147 to notify a consumer that a request has been completed (the
148 callback is specified by the consumer on a per-request basis).
149 The callback is invoked by the framework whether the request was
150 successfully completed or not.
151 An error indication is provided in the latter case.
152 A specific error code,
154 is used to indicate that a session handle has changed and that the
155 request may be re-submitted immediately with the new session.
156 Errors are only returned to the invoking function if not
157 enough information to call the callback is available (meaning, there
158 was a fatal error in verifying the arguments).
159 For session initialization and teardown no callback mechanism is used.
162 .Fn crypto_find_driver
163 returns the driver id of the device whose name matches
166 can either be the exact name of a device including the unit
167 or the driver name without a unit.
169 the id of the first device with the matching driver name is returned.
170 If no matching device is found,
171 the value -1 is returned.
174 .Fn crypto_newsession
175 routine is called by consumers of cryptographic services (such as the
177 stack) that wish to establish a new session with the framework.
182 structure containing all the necessary information for
183 the driver to establish the session.
186 argument is either a specific driver id or a bitmask of flags.
188 .Dv CRYPTOCAP_F_HARDWARE ,
189 to select hardware devices,
191 .Dv CRYPTOCAP_F_SOFTWARE ,
192 to select software devices.
193 If both are specified, hardware devices are preferred over software
195 On success, the opaque session handle of the new session will be stored in
199 structure pointed to by
201 contains these fields:
202 .Bl -tag -width ".Va cri_next"
204 An algorithm identifier.
205 Currently supported algorithms are:
207 .Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
208 .It Dv CRYPTO_AES_128_NIST_GMAC
209 .It Dv CRYPTO_AES_192_NIST_GMAC
210 .It Dv CRYPTO_AES_256_NIST_GMAC
211 .It Dv CRYPTO_AES_CBC
212 .It Dv CRYPTO_AES_CCM_16
213 .It Dv CRYPTO_AES_CCM_CBC_MAC
214 .It Dv CRYPTO_AES_ICM
215 .It Dv CRYPTO_AES_NIST_GCM_16
216 .It Dv CRYPTO_AES_NIST_GMAC
217 .It Dv CRYPTO_AES_XTS
219 .It Dv CRYPTO_BLAKE2B
220 .It Dv CRYPTO_BLAKE2S
221 .It Dv CRYPTO_BLF_CBC
222 .It Dv CRYPTO_CAMELLIA_CBC
223 .It Dv CRYPTO_CAST_CBC
224 .It Dv CRYPTO_CHACHA20
225 .It Dv CRYPTO_DEFLATE_COMP
226 .It Dv CRYPTO_DES_CBC
227 .It Dv CRYPTO_3DES_CBC
229 .It Dv CRYPTO_MD5_HMAC
230 .It Dv CRYPTO_MD5_KPDK
231 .It Dv CRYPTO_NULL_HMAC
232 .It Dv CRYPTO_NULL_CBC
233 .It Dv CRYPTO_POLY1305
234 .It Dv CRYPTO_RIPEMD160
235 .It Dv CRYPTO_RIPEMD160_HMAC
237 .It Dv CRYPTO_SHA1_HMAC
238 .It Dv CRYPTO_SHA1_KPDK
239 .It Dv CRYPTO_SHA2_224
240 .It Dv CRYPTO_SHA2_224_HMAC
241 .It Dv CRYPTO_SHA2_256
242 .It Dv CRYPTO_SHA2_256_HMAC
243 .It Dv CRYPTO_SHA2_384
244 .It Dv CRYPTO_SHA2_384_HMAC
245 .It Dv CRYPTO_SHA2_512
246 .It Dv CRYPTO_SHA2_512_HMAC
247 .It Dv CRYPTO_SKIPJACK_CBC
250 For variable-size key algorithms, the length of the key in bits.
252 If non-zero, truncate the calculated hash to this many bytes.
256 An explicit initialization vector if it does not prefix
258 This field is ignored during initialization
259 .Pq Nm crypto_newsession .
260 If no IV is explicitly passed (see below on details), a random IV is used
261 by the device driver processing the request.
266 This is used to establish dual-algorithm sessions, such as combining a
272 structure and its contents will not be modified or referenced by the
273 framework or any cryptographic drivers.
274 The memory associated with
277 .Fn crypto_newsession
280 .Fn crypto_freesession
281 is called with the session handle returned by
282 .Fn crypto_newsession
286 is called to process a request.
287 The various fields in the
290 .Bl -tag -width ".Va crp_callback"
294 The total length in bytes of the buffer to be processed.
296 On return, contains the total length of the result.
297 For symmetric crypto operations, this will be the same as the input length.
298 This will be used if the framework needs to allocate a new
299 buffer for the result (or for re-formatting the input).
301 Callback routine invoked when a request is completed via
303 The callback routine should inspect the
305 to determine if the request was successfully completed.
307 The error type, if any errors were encountered, or zero if
308 the request was successfully processed.
311 error code is returned, the session handle has changed (and has been recorded
315 The consumer should record the new session handle and use it in all subsequent
317 In this case, the request may be re-submitted immediately.
318 This mechanism is used by the framework to perform
319 session migration (move a session from one driver to another, because
320 of availability, performance, or other considerations).
322 This field is only valid in the context of the callback routine specified by
324 Errors are returned to the invoker of
326 only when enough information is not present to call the callback
327 routine (i.e., if the pointer passed is
329 or if no callback routine was specified).
331 A bitmask of flags associated with this request.
332 Currently defined flags are:
333 .Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC"
334 .It Dv CRYPTO_F_IMBUF
335 The buffer is an mbuf chain pointed to by
340 structure pointed to by
342 .It Dv CRYPTO_F_BATCH
343 Batch operation if possible.
344 .It Dv CRYPTO_F_CBIMM
345 Do callback immediately instead of doing it from a dedicated kernel thread.
348 .It Dv CRYPTO_F_CBIFSYNC
349 Do callback immediately if operation is synchronous (that the driver
353 .It Dv CRYPTO_F_ASYNC
354 Try to do the crypto operation in a pool of workers
355 if the operation is synchronous (that is, if the driver specified the
358 It aims to speed up processing by dispatching crypto operations
359 on different processors.
360 .It Dv CRYPTO_F_ASYNC_KEEPORDER
361 Dispatch callbacks in the same order they are posted.
364 flag is set and if the operation is synchronous.
373 The length in bytes is set in
376 Data buffer mbuf chain when
387 Cookie passed through the crypto framework untouched.
389 intended for the invoking application's use.
391 A linked list of descriptors.
392 Each descriptor provides
393 information about what type of cryptographic operation should be done
395 The various fields are:
396 .Bl -tag -width ".Va crd_inject"
399 .Dv CRD_F_IV_EXPLICIT
400 is set, this field contains the IV.
403 .Dv CRD_F_KEY_EXPLICIT
406 points to a buffer with encryption or authentication key.
409 Must be the same as the one given at newsession time.
415 The offset in the input buffer where processing should start.
417 How many bytes, after
423 field specifies an offset in bytes from the beginning of the buffer.
424 For encryption algorithms, this may be where the IV will be inserted
425 when encrypting or where the IV may be found for
426 decryption (subject to
428 For MAC algorithms, this is where the result of the keyed hash will be
431 The following flags are defined:
434 For encryption algorithms, this bit is set when encryption is required
435 (when not set, decryption is performed).
436 .It Dv CRD_F_IV_PRESENT
437 .\" This flag name has nothing to do w/ it's behavior, fix the name.
438 For encryption, if this bit is not set the IV used to encrypt the packet
439 will be written at the location pointed to by
441 The IV length is assumed to be equal to the blocksize of the
442 encryption algorithm.
443 For encryption, if this bit is set, nothing is done.
444 For decryption, this flag has no meaning.
445 Applications that do special
447 such as the half-IV mode in
449 can use this flag to indicate that the IV should not be written on the packet.
450 This flag is typically used in conjunction with the
451 .Dv CRD_F_IV_EXPLICIT
453 .It Dv CRD_F_IV_EXPLICIT
454 This bit is set when the IV is explicitly
455 provided by the consumer in the
458 Otherwise, for encryption operations the IV is provided for by
459 the driver used to perform the operation, whereas for decryption
460 operations the offset of the IV is provided by the
463 This flag is typically used when the IV is calculated
465 by the consumer, and does not precede the data.
466 .It Dv CRD_F_KEY_EXPLICIT
467 For encryption and authentication (MAC) algorithms, this bit is set when the key
468 is explicitly provided by the consumer in the
470 field for the given operation.
471 Otherwise, the key is taken at newsession time from the
474 As calculating the key schedule may take a while, it is recommended that often
475 used keys are given their own session.
477 For compression algorithms, this bit is set when compression is required (when
478 not set, decompression is performed).
483 structure will not be modified by the framework or the device drivers.
484 Since this information accompanies every cryptographic
485 operation request, drivers may re-initialize state on-demand
486 (typically an expensive operation).
487 Furthermore, the cryptographic
488 framework may re-route requests as a result of full queues or hardware
489 failure, as described above.
491 Point to the next descriptor.
492 Linked operations are useful in protocols such as
494 where multiple cryptographic transforms may be applied on the same
502 structure with a linked list of
508 deallocates a structure
512 structures linked to it.
513 Note that it is the responsibility of the
514 callback routine to do the necessary cleanups associated with the
520 is called to perform a keying operation.
521 The various fields in the
524 .Bl -tag -width ".Va krp_callback"
526 Operation code, such as
532 variable indicates whether lower level reasons
533 for operation failure.
535 Number of input parameters to the specified operation.
536 Note that each operation has a (typically hardwired) number of such parameters.
538 Number of output parameters from the specified operation.
539 Note that each operation has a (typically hardwired) number of such parameters.
541 An array of kernel memory blocks containing the parameters.
543 Identifier specifying which low-level driver is being used.
545 Callback called on completion of a keying operation.
549 .Fn crypto_get_driverid ,
550 .Fn crypto_get_driver_session ,
551 .Fn crypto_register ,
552 .Fn crypto_kregister ,
553 .Fn crypto_unregister ,
557 routines are used by drivers that provide support for cryptographic
558 primitives to register and unregister with the kernel crypto services
561 Drivers must first use the
562 .Fn crypto_get_driverid
563 function to acquire a driver identifier, specifying the
567 .Dv CRYPTOCAP_F_SOFTWARE
569 .Dv CRYPTOCAP_F_HARDWARE
573 may also be specified, and should be specified if the driver does all of
574 it's operations synchronously.
575 Drivers must pass the size of their session structure as the second argument.
576 An appropriately sized memory will be allocated by the framework, zeroed, and
577 passed to the driver's
581 For each algorithm the driver supports, it must then call
582 .Fn crypto_register .
583 The first two arguments are the driver and algorithm identifiers.
584 The next two arguments specify the largest possible operator length (in bits,
585 important for public key operations) and flags for this algorithm.
587 .Fn crypto_unregister
588 is called by drivers that wish to withdraw support for an algorithm.
589 The two arguments are the driver and algorithm identifiers, respectively.
590 Typically, drivers for
592 crypto cards that are being ejected will invoke this routine for all
593 algorithms supported by the card.
594 .Fn crypto_unregister_all
595 will unregister all algorithms registered by a driver
596 and the driver will be disabled (no new sessions will be allocated on
597 that driver, and any existing sessions will be migrated to other
599 The same will be done if all algorithms associated with a driver are
600 unregistered one by one.
602 .Fn crypto_unregister_all
603 there will be no threads in either the newsession or freesession function
606 The calling convention for the driver-supplied routines are:
611 .Fn \*[lp]*newsession\*[rp] "device_t" "crypto_session_t" "struct cryptoini *" ;
614 .Fn \*[lp]*freesession\*[rp] "device_t" "crypto_session_t" ;
617 .Fn \*[lp]*process\*[rp] "device_t" "struct cryptop *" "int" ;
620 .Fn \*[lp]*kprocess\*[rp] "device_t" "struct cryptkop *" "int" ;
623 On invocation, the first argument to
627 .Fn crypto_get_driverid .
628 The second argument to
630 is the opaque session handle for the new session.
631 The third argument is identical to that of
632 .Fn crypto_newsession .
634 Drivers obtain a pointer to their session memory by invoking
635 .Fn crypto_get_driver_session
642 routine takes as arguments the opaque data value and the session handle.
643 It should clear any context associated with the session (clear hardware
644 registers, memory, etc.).
645 If no resources need to be released other than the contents of session memory,
646 the method is optional.
649 framework will zero and release the allocated session memory (after running the
651 method, if one exists).
655 routine is invoked with a request to perform crypto processing.
656 This routine must not block or sleep, but should queue the request and return
657 immediately or process the request to completion.
658 In case of an unrecoverable error, the error indication must be placed in the
663 When the request is completed, or an error is detected, the
667 Session migration may be performed, as mentioned previously.
669 In case of a temporary resource exhaustion, the
673 in which case the crypto services will requeue the request, mark the driver
676 and stop submitting requests for processing.
677 The driver is then responsible for notifying the crypto services
678 when it is again able to process requests through the
681 This simple flow control mechanism should only be used for short-lived
682 resource exhaustion as it causes operations to be queued in the crypto
684 Doing so is preferable to returning an error in such cases as
685 it can cause network protocols to degrade performance by treating the
686 failure much like a lost packet.
690 routine is invoked with a request to perform crypto key processing.
691 This routine must not block, but should queue the request and return
693 Upon processing the request, the callback routine should be invoked.
694 In case of an unrecoverable error, the error indication must be placed in the
699 When the request is completed, or an error is detected, the
701 routine should invoked
704 .Fn crypto_register ,
705 .Fn crypto_kregister ,
706 .Fn crypto_unregister ,
707 .Fn crypto_newsession ,
708 .Fn crypto_freesession ,
711 return 0 on success, or an error code on failure.
712 .Fn crypto_get_driverid
713 returns a non-negative value on error, and \-1 on failure.
715 returns a pointer to a
723 if its argument or the callback function was
726 The callback is provided with an error code in case of failure, in the
730 .Bl -tag -width ".Pa sys/opencrypto/crypto.c"
731 .It Pa sys/opencrypto/crypto.c
732 most of the framework code
741 The cryptographic framework first appeared in
744 .An Angelos D. Keromytis Aq Mt angelos@openbsd.org .
746 The framework currently assumes that all the algorithms in a
747 .Fn crypto_newsession
748 operation must be available by the same driver.
749 If that is not the case, session initialization will fail.
751 The framework also needs a mechanism for determining which driver is
752 best for a specific set of algorithms associated with a session.
753 Some type of benchmarking is in order here.
755 Multiple instances of the same algorithm in the same session are not