19.\"
20.Dd May 17, 2006
21.Dt CRYPTO 9
22.Os
23.Sh NAME
24.Nm crypto
25.Nd API for cryptographic services in the kernel
26.Sh SYNOPSIS
27.In opencrypto/cryptodev.h
28.Ft int32_t
29.Fn crypto_get_driverid u_int8_t
30.Ft int
31.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 *"
32.Ft int
33.Fn crypto_kregister u_int32_t int u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *"
34.Ft int
35.Fn crypto_unregister u_int32_t int
36.Ft int
37.Fn crypto_unregister_all u_int32_t
38.Ft void
39.Fn crypto_done "struct cryptop *"
40.Ft void
41.Fn crypto_kdone "struct cryptkop *"
42.Ft int
43.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" int
44.Ft int
45.Fn crypto_freesession u_int64_t
46.Ft int
47.Fn crypto_dispatch "struct cryptop *"
48.Ft int
49.Fn crypto_kdispatch "struct cryptkop *"
50.Ft int
51.Fn crypto_unblock u_int32_t int
52.Ft "struct cryptop *"
53.Fn crypto_getreq int
54.Ft void
55.Fn crypto_freereq void
56.Bd -literal
57#define CRYPTO_SYMQ 0x1
58#define CRYPTO_ASYMQ 0x2
59
60#define EALG_MAX_BLOCK_LEN 16
61
62struct cryptoini {
63 int cri_alg;
64 int cri_klen;
65 int cri_mlen;
66 caddr_t cri_key;
67 u_int8_t cri_iv[EALG_MAX_BLOCK_LEN];
68 struct cryptoini *cri_next;
69};
70
71struct cryptodesc {
72 int crd_skip;
73 int crd_len;
74 int crd_inject;
75 int crd_flags;
76 struct cryptoini CRD_INI;
77 struct cryptodesc *crd_next;
78};
79
80struct cryptop {
81 TAILQ_ENTRY(cryptop) crp_next;
82 u_int64_t crp_sid;
83 int crp_ilen;
84 int crp_olen;
85 int crp_etype;
86 int crp_flags;
87 caddr_t crp_buf;
88 caddr_t crp_opaque;
89 struct cryptodesc *crp_desc;
90 int (*crp_callback) (struct cryptop *);
91 caddr_t crp_mac;
92};
93
94struct crparam {
95 caddr_t crp_p;
96 u_int crp_nbits;
97};
98
99#define CRK_MAXPARAM 8
100
101struct cryptkop {
102 TAILQ_ENTRY(cryptkop) krp_next;
103 u_int krp_op; /* ie. CRK_MOD_EXP or other */
104 u_int krp_status; /* return status */
105 u_short krp_iparams; /* # of input parameters */
106 u_short krp_oparams; /* # of output parameters */
107 u_int32_t krp_hid;
108 struct crparam krp_param[CRK_MAXPARAM];
109 int (*krp_callback)(struct cryptkop *);
110};
111.Ed
112.Sh DESCRIPTION
113.Nm
114is a framework for drivers of cryptographic hardware to register with
115the kernel so
116.Dq consumers
117(other kernel subsystems, and
118users through the
119.Pa /dev/crypto
120device) are able to make use of it.
121Drivers register with the framework the algorithms they support,
122and provide entry points (functions) the framework may call to
123establish, use, and tear down sessions.
124Sessions are used to cache cryptographic information in a particular driver
125(or associated hardware), so initialization is not needed with every request.
126Consumers of cryptographic services pass a set of
127descriptors that instruct the framework (and the drivers registered
128with it) of the operations that should be applied on the data (more
129than one cryptographic operation can be requested).
130.Pp
131Keying operations are supported as well.
132Unlike the symmetric operators described above,
133these sessionless commands perform mathematical operations using
134input and output parameters.
135.Pp
136Since the consumers may not be associated with a process, drivers may
137not
138.Xr sleep 9 .
139The same holds for the framework.
140Thus, a callback mechanism is used
141to notify a consumer that a request has been completed (the
142callback is specified by the consumer on an per-request basis).
143The callback is invoked by the framework whether the request was
144successfully completed or not.
145An error indication is provided in the latter case.
146A specific error code,
147.Er EAGAIN ,
148is used to indicate that a session number has changed and that the
149request may be re-submitted immediately with the new session number.
150Errors are only returned to the invoking function if not
151enough information to call the callback is available (meaning, there
152was a fatal error in verifying the arguments).
153For session initialization and teardown there is no callback mechanism used.
154.Pp
155The
156.Fn crypto_newsession
157routine is called by consumers of cryptographic services (such as the
158.Xr ipsec 4
159stack) that wish to establish a new session with the framework.
160On success, the first argument will contain the Session Identifier (SID).
161The second argument contains all the necessary information for
162the driver to establish the session.
163The third argument indicates whether a
164hardware driver (1) should be used or not (0).
165The various fields in the
166.Vt cryptoini
167structure are:
168.Bl -tag -width ".Va cri_next"
169.It Va cri_alg
170Contains an algorithm identifier.
171Currently supported algorithms are:
172.Pp
173.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
174.It Dv CRYPTO_DES_CBC
175.It Dv CRYPTO_3DES_CBC
176.It Dv CRYPTO_BLF_CBC
177.It Dv CRYPTO_CAST_CBC
178.It Dv CRYPTO_SKIPJACK_CBC
179.It Dv CRYPTO_MD5_HMAC
180.It Dv CRYPTO_SHA1_HMAC
181.It Dv CRYPTO_RIPEMD160_HMAC
182.It Dv CRYPTO_MD5_KPDK
183.It Dv CRYPTO_SHA1_KPDK
184.It Dv CRYPTO_AES_CBC
185.It Dv CRYPTO_ARC4
186.It Dv CRYPTO_MD5
187.It Dv CRYPTO_SHA1
| 19.\"
20.Dd May 17, 2006
21.Dt CRYPTO 9
22.Os
23.Sh NAME
24.Nm crypto
25.Nd API for cryptographic services in the kernel
26.Sh SYNOPSIS
27.In opencrypto/cryptodev.h
28.Ft int32_t
29.Fn crypto_get_driverid u_int8_t
30.Ft int
31.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 *"
32.Ft int
33.Fn crypto_kregister u_int32_t int u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *"
34.Ft int
35.Fn crypto_unregister u_int32_t int
36.Ft int
37.Fn crypto_unregister_all u_int32_t
38.Ft void
39.Fn crypto_done "struct cryptop *"
40.Ft void
41.Fn crypto_kdone "struct cryptkop *"
42.Ft int
43.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" int
44.Ft int
45.Fn crypto_freesession u_int64_t
46.Ft int
47.Fn crypto_dispatch "struct cryptop *"
48.Ft int
49.Fn crypto_kdispatch "struct cryptkop *"
50.Ft int
51.Fn crypto_unblock u_int32_t int
52.Ft "struct cryptop *"
53.Fn crypto_getreq int
54.Ft void
55.Fn crypto_freereq void
56.Bd -literal
57#define CRYPTO_SYMQ 0x1
58#define CRYPTO_ASYMQ 0x2
59
60#define EALG_MAX_BLOCK_LEN 16
61
62struct cryptoini {
63 int cri_alg;
64 int cri_klen;
65 int cri_mlen;
66 caddr_t cri_key;
67 u_int8_t cri_iv[EALG_MAX_BLOCK_LEN];
68 struct cryptoini *cri_next;
69};
70
71struct cryptodesc {
72 int crd_skip;
73 int crd_len;
74 int crd_inject;
75 int crd_flags;
76 struct cryptoini CRD_INI;
77 struct cryptodesc *crd_next;
78};
79
80struct cryptop {
81 TAILQ_ENTRY(cryptop) crp_next;
82 u_int64_t crp_sid;
83 int crp_ilen;
84 int crp_olen;
85 int crp_etype;
86 int crp_flags;
87 caddr_t crp_buf;
88 caddr_t crp_opaque;
89 struct cryptodesc *crp_desc;
90 int (*crp_callback) (struct cryptop *);
91 caddr_t crp_mac;
92};
93
94struct crparam {
95 caddr_t crp_p;
96 u_int crp_nbits;
97};
98
99#define CRK_MAXPARAM 8
100
101struct cryptkop {
102 TAILQ_ENTRY(cryptkop) krp_next;
103 u_int krp_op; /* ie. CRK_MOD_EXP or other */
104 u_int krp_status; /* return status */
105 u_short krp_iparams; /* # of input parameters */
106 u_short krp_oparams; /* # of output parameters */
107 u_int32_t krp_hid;
108 struct crparam krp_param[CRK_MAXPARAM];
109 int (*krp_callback)(struct cryptkop *);
110};
111.Ed
112.Sh DESCRIPTION
113.Nm
114is a framework for drivers of cryptographic hardware to register with
115the kernel so
116.Dq consumers
117(other kernel subsystems, and
118users through the
119.Pa /dev/crypto
120device) are able to make use of it.
121Drivers register with the framework the algorithms they support,
122and provide entry points (functions) the framework may call to
123establish, use, and tear down sessions.
124Sessions are used to cache cryptographic information in a particular driver
125(or associated hardware), so initialization is not needed with every request.
126Consumers of cryptographic services pass a set of
127descriptors that instruct the framework (and the drivers registered
128with it) of the operations that should be applied on the data (more
129than one cryptographic operation can be requested).
130.Pp
131Keying operations are supported as well.
132Unlike the symmetric operators described above,
133these sessionless commands perform mathematical operations using
134input and output parameters.
135.Pp
136Since the consumers may not be associated with a process, drivers may
137not
138.Xr sleep 9 .
139The same holds for the framework.
140Thus, a callback mechanism is used
141to notify a consumer that a request has been completed (the
142callback is specified by the consumer on an per-request basis).
143The callback is invoked by the framework whether the request was
144successfully completed or not.
145An error indication is provided in the latter case.
146A specific error code,
147.Er EAGAIN ,
148is used to indicate that a session number has changed and that the
149request may be re-submitted immediately with the new session number.
150Errors are only returned to the invoking function if not
151enough information to call the callback is available (meaning, there
152was a fatal error in verifying the arguments).
153For session initialization and teardown there is no callback mechanism used.
154.Pp
155The
156.Fn crypto_newsession
157routine is called by consumers of cryptographic services (such as the
158.Xr ipsec 4
159stack) that wish to establish a new session with the framework.
160On success, the first argument will contain the Session Identifier (SID).
161The second argument contains all the necessary information for
162the driver to establish the session.
163The third argument indicates whether a
164hardware driver (1) should be used or not (0).
165The various fields in the
166.Vt cryptoini
167structure are:
168.Bl -tag -width ".Va cri_next"
169.It Va cri_alg
170Contains an algorithm identifier.
171Currently supported algorithms are:
172.Pp
173.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
174.It Dv CRYPTO_DES_CBC
175.It Dv CRYPTO_3DES_CBC
176.It Dv CRYPTO_BLF_CBC
177.It Dv CRYPTO_CAST_CBC
178.It Dv CRYPTO_SKIPJACK_CBC
179.It Dv CRYPTO_MD5_HMAC
180.It Dv CRYPTO_SHA1_HMAC
181.It Dv CRYPTO_RIPEMD160_HMAC
182.It Dv CRYPTO_MD5_KPDK
183.It Dv CRYPTO_SHA1_KPDK
184.It Dv CRYPTO_AES_CBC
185.It Dv CRYPTO_ARC4
186.It Dv CRYPTO_MD5
187.It Dv CRYPTO_SHA1
|
189.It Dv CRYPTO_NULL_HMAC
190.It Dv CRYPTO_NULL_CBC
191.El
192.It Va cri_klen
193Specifies the length of the key in bits, for variable-size key
194algorithms.
195.It Va cri_mlen
196Specifies how many bytes from the calculated hash should be copied back.
1970 means entire hash.
198.It Va cri_key
199Contains the key to be used with the algorithm.
200.It Va cri_iv
201Contains an explicit initialization vector (IV), if it does not prefix
202the data.
203This field is ignored during initialization.
204If no IV is explicitly passed (see below on details), a random IV is used
205by the device driver processing the request.
206.It Va cri_next
207Contains a pointer to another
208.Vt cryptoini
209structure.
210Multiple such structures may be linked to establish multi-algorithm sessions
211.Xr ( ipsec 4
212is an example consumer of such a feature).
213.El
214.Pp
215The
216.Vt cryptoini
217structure and its contents will not be modified by the framework (or
218the drivers used).
219Subsequent requests for processing that use the
220SID returned will avoid the cost of re-initializing the hardware (in
221essence, SID acts as an index in the session cache of the driver).
222.Pp
223.Fn crypto_freesession
224is called with the SID returned by
225.Fn crypto_newsession
226to disestablish the session.
227.Pp
228.Fn crypto_dispatch
229is called to process a request.
230The various fields in the
231.Vt cryptop
232structure are:
233.Bl -tag -width ".Va crp_callback"
234.It Va crp_sid
235Contains the SID.
236.It Va crp_ilen
237Indicates the total length in bytes of the buffer to be processed.
238.It Va crp_olen
239On return, contains the total length of the result.
240For symmetric crypto operations, this will be the same as the input length.
241This will be used if the framework needs to allocate a new
242buffer for the result (or for re-formatting the input).
243.It Va crp_callback
244This routine is invoked upon completion of the request, whether
245successful or not.
246It is invoked through the
247.Fn crypto_done
248routine.
249If the request was not successful, an error code is set in the
250.Va crp_etype
251field.
252It is the responsibility of the callback routine to set the appropriate
253.Xr spl 9
254level.
255.It Va crp_etype
256Contains the error type, if any errors were encountered, or zero if
257the request was successfully processed.
258If the
259.Er EAGAIN
260error code is returned, the SID has changed (and has been recorded in the
261.Va crp_sid
262field).
263The consumer should record the new SID and use it in all subsequent requests.
264In this case, the request may be re-submitted immediately.
265This mechanism is used by the framework to perform
266session migration (move a session from one driver to another, because
267of availability, performance, or other considerations).
268.Pp
269Note that this field only makes sense when examined by
270the callback routine specified in
271.Va crp_callback .
272Errors are returned to the invoker of
273.Fn crypto_process
274only when enough information is not present to call the callback
275routine (i.e., if the pointer passed is
276.Dv NULL
277or if no callback routine was specified).
278.It Va crp_flags
279Is a bitmask of flags associated with this request.
280Currently defined flags are:
281.Bl -tag -width ".Dv CRYPTO_F_IMBUF"
282.It Dv CRYPTO_F_IMBUF
283The buffer pointed to by
284.Va crp_buf
285is an mbuf chain.
286.El
287.It Va crp_buf
288Points to the input buffer.
289On return (when the callback is invoked),
290it contains the result of the request.
291The input buffer may be an mbuf
292chain or a contiguous buffer,
293depending on
294.Va crp_flags .
295.It Va crp_opaque
296This is passed through the crypto framework untouched and is
297intended for the invoking application's use.
298.It Va crp_desc
299This is a linked list of descriptors.
300Each descriptor provides
301information about what type of cryptographic operation should be done
302on the input buffer.
303The various fields are:
304.Bl -tag -width ".Va crd_inject"
305.It Va crd_skip
306The offset in the input buffer where processing should start.
307.It Va crd_len
308How many bytes, after
309.Va crd_skip ,
310should be processed.
311.It Va crd_inject
312Offset from the beginning of the buffer to insert any results.
313For encryption algorithms, this is where the initialization vector
314(IV) will be inserted when encrypting or where it can be found when
315decrypting (subject to
316.Va crd_flags ) .
317For MAC algorithms, this is where the result of the keyed hash will be
318inserted.
319.It Va crd_flags
320The following flags are defined:
321.Bl -tag -width ".Dv CRD"
322.It Dv CRD_F_ENCRYPT
323For encryption algorithms, this bit is set when encryption is required
324(when not set, decryption is performed).
325.It Dv CRD_F_IV_PRESENT
326For encryption algorithms, this bit is set when the IV already
327precedes the data, so the
328.Va crd_inject
329value will be ignored and no IV will be written in the buffer.
330Otherwise, the IV used to encrypt the packet will be written
331at the location pointed to by
332.Va crd_inject .
333The IV length is assumed to be equal to the blocksize of the
334encryption algorithm.
335Some applications that do special
336.Dq "IV cooking" ,
337such as the half-IV mode in
338.Xr ipsec 4 ,
339can use this flag to indicate that the IV should not be written on the packet.
340This flag is typically used in conjunction with the
341.Dv CRD_F_IV_EXPLICIT
342flag.
343.It Dv CRD_F_IV_EXPLICIT
344For encryption algorithms, this bit is set when the IV is explicitly
345provided by the consumer in the
346.Va cri_iv
347field.
348Otherwise, for encryption operations the IV is provided for by
349the driver used to perform the operation, whereas for decryption
350operations it is pointed to by the
351.Va crd_inject
352field.
353This flag is typically used when the IV is calculated
354.Dq "on the fly"
355by the consumer, and does not precede the data (some
356.Xr ipsec 4
357configurations, and the encrypted swap are two such examples).
358.It Dv CRD_F_KEY_EXPLICIT
359For encryption algorithms, this bit is set when the key is explicitly
360provided by the consumer in the
361.Va cri_key
362field for the given operation.
363Otherwise, the key is taken at newsession time from the same field.
364.It Dv CRD_F_COMP
365For compression algorithms, this bit is set when compression is required (when
366not set, decompression is performed).
367.El
368.It Va CRD_INI
369This
370.Vt cryptoini
371structure will not be modified by the framework or the device drivers.
372Since this information accompanies every cryptographic
373operation request, drivers may re-initialize state on-demand
374(typically an expensive operation).
375Furthermore, the cryptographic
376framework may re-route requests as a result of full queues or hardware
377failure, as described above.
378.It Va crd_next
379Point to the next descriptor.
380Linked operations are useful in protocols such as
381.Xr ipsec 4 ,
382where multiple cryptographic transforms may be applied on the same
383block of data.
384.El
385.El
386.Pp
387.Fn crypto_getreq
388allocates a
389.Vt cryptop
390structure with a linked list of as many
391.Vt cryptodesc
392structures as were specified in the argument passed to it.
393.Pp
394.Fn crypto_freereq
395deallocates a structure
396.Vt cryptop
397and any
398.Vt cryptodesc
399structures linked to it.
400Note that it is the responsibility of the
401callback routine to do the necessary cleanups associated with the
402opaque field in the
403.Vt cryptop
404structure.
405.Pp
406.Fn crypto_kdispatch
407is called to perform a keying operation.
408The various fields in the
409.Vt cryptkop
410structure are:
411.Bl -tag -width ".Va krp_callback'
412.It Va krp_op
413Operation code, such as
414.Dv CRK_MOD_EXP .
415.It Va krp_status
416Return code.
417This
418.Va errno Ns -style
419variable indicates whether lower level reasons
420for operation failure.
421.It Va krp_iparams
422Number if input parameters to the specified operation.
423Note that each operation has a (typically hardwired) number of such parameters.
424.It Va krp_oparams
425Number if output parameters from the specified operation.
426Note that each operation has a (typically hardwired) number of such parameters.
427.It Va krp_kvp
428An array of kernel memory blocks containing the parameters.
429.It Va krp_hid
430Identifier specifying which low-level driver is being used.
431.It Va krp_callback
432Callback called on completion of a keying operation.
433.El
434.Sh DRIVER-SIDE API
435The
436.Fn crypto_get_driverid ,
437.Fn crypto_register ,
438.Fn crypto_kregister ,
439.Fn crypto_unregister ,
440.Fn crypto_unblock ,
441and
442.Fn crypto_done
443routines are used by drivers that provide support for cryptographic
444primitives to register and unregister with the kernel crypto services
445framework.
446Drivers must first use the
447.Fn crypto_get_driverid
448function to acquire a driver identifier, specifying the
449.Fa cc_flags
450as an argument (normally 0, but software-only drivers should specify
451.Dv CRYPTOCAP_F_SOFTWARE ) .
452For each algorithm the driver supports, it must then call
453.Fn crypto_register .
454The first two arguments are the driver and algorithm identifiers.
455The next two arguments specify the largest possible operator length (in bits,
456important for public key operations) and flags for this algorithm.
457The last four arguments must be provided in the first call to
458.Fn crypto_register
459and are ignored in all subsequent calls.
460They are pointers to three
461driver-provided functions that the framework may call to establish new
462cryptographic context with the driver, free already established
463context, and ask for a request to be processed (encrypt, decrypt,
464etc.); and an opaque parameter to pass when calling each of these routines.
465.Fn crypto_unregister
466is called by drivers that wish to withdraw support for an algorithm.
467The two arguments are the driver and algorithm identifiers, respectively.
468Typically, drivers for
469PCMCIA
470crypto cards that are being ejected will invoke this routine for all
471algorithms supported by the card.
472.Fn crypto_unregister_all
473will unregister all algorithms registered by a driver
474and the driver will be disabled (no new sessions will be allocated on
475that driver, and any existing sessions will be migrated to other
476drivers).
477The same will be done if all algorithms associated with a driver are
478unregistered one by one.
479.Pp
480The calling convention for the three driver-supplied routines is:
481.Pp
482.Bl -item -compact
483.It
484.Ft int
485.Fn \*[lp]*newsession\*[rp] "void *" "u_int32_t *" "struct cryptoini *" ;
486.It
487.Ft int
488.Fn \*[lp]*freesession\*[rp] "void *" "u_int64_t" ;
489.It
490.Ft int
491.Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ;
492.It
493.Ft int
494.Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ;
495.El
496.Pp
497On invocation, the first argument to
498all routines is an opaque data value supplied when the algorithm
499is registered with
500.Fn crypto_register .
501The second argument to
502.Fn newsession
503contains the driver identifier obtained via
504.Fn crypto_get_driverid .
505On successful return, it should contain a driver-specific session
506identifier.
507The third argument is identical to that of
508.Fn crypto_newsession .
509.Pp
510The
511.Fn freesession
512routine takes as arguments the opaque data value and the SID
513(which is the concatenation of the
514driver identifier and the driver-specific session identifier).
515It should clear any context associated with the session (clear hardware
516registers, memory, etc.).
517.Pp
518The
519.Fn process
520routine is invoked with a request to perform crypto processing.
521This routine must not block, but should queue the request and return
522immediately.
523Upon processing the request, the callback routine should be invoked.
524In case of an unrecoverable error, the error indication must be placed in the
525.Va crp_etype
526field of the
527.Vt cryptop
528structure.
529When the request is completed, or an error is detected, the
530.Fn process
531routine should invoke
532.Fn crypto_done .
533Session migration may be performed, as mentioned previously.
534.Pp
535In case of a temporary resource exhaustion, the
536.Fn process
537routine may return
538.Er ERESTART
539in which case the crypto services will requeue the request, mark the driver
540as
541.Dq blocked ,
542and stop submitting requests for processing.
543The driver is then responsible for notifying the crypto services
544when it is again able to process requests through the
545.Fn crypto_unblock
546routine.
547This simple flow control mechanism should only be used for short-lived
548resource exhaustion as it causes operations to be queued in the crypto
549layer.
550Doing so is preferable to returning an error in such cases as
551it can cause network protocols to degrade performance by treating the
552failure much like a lost packet.
553.Pp
554The
555.Fn kprocess
556routine is invoked with a request to perform crypto key processing.
557This routine must not block, but should queue the request and return
558immediately.
559Upon processing the request, the callback routine should be invoked.
560In case of an unrecoverable error, the error indication must be placed in the
561.Va krp_status
562field of the
563.Vt cryptkop
564structure.
565When the request is completed, or an error is detected, the
566.Fn kprocess
567routine should invoked
568.Fn crypto_kdone .
569.Sh RETURN VALUES
570.Fn crypto_register ,
571.Fn crypto_kregister ,
572.Fn crypto_unregister ,
573.Fn crypto_newsession ,
574.Fn crypto_freesession ,
575and
576.Fn crypto_unblock
577return 0 on success, or an error code on failure.
578.Fn crypto_get_driverid
579returns a non-negative value on error, and \-1 on failure.
580.Fn crypto_getreq
581returns a pointer to a
582.Vt cryptop
583structure and
584.Dv NULL
585on failure.
586.Fn crypto_dispatch
587returns
588.Er EINVAL
589if its argument or the callback function was
590.Dv NULL ,
591and 0 otherwise.
592The callback is provided with an error code in case of failure, in the
593.Va crp_etype
594field.
595.Sh FILES
596.Bl -tag -width ".Pa sys/opencrypto/crypto.c"
597.It Pa sys/opencrypto/crypto.c
598most of the framework code
599.El
600.Sh SEE ALSO
601.Xr ipsec 4 ,
602.Xr malloc 9 ,
603.Xr sleep 9
604.Sh HISTORY
605The cryptographic framework first appeared in
606.Ox 2.7
607and was written by
608.An "Angelos D. Keromytis" Aq angelos@openbsd.org .
609.Sh BUGS
610The framework currently assumes that all the algorithms in a
611.Fn crypto_newsession
612operation must be available by the same driver.
613If that is not the case, session initialization will fail.
614.Pp
615The framework also needs a mechanism for determining which driver is
616best for a specific set of algorithms associated with a session.
617Some type of benchmarking is in order here.
618.Pp
619Multiple instances of the same algorithm in the same session are not
620supported.
621Note that 3DES is considered one algorithm (and not three
622instances of DES).
623Thus, 3DES and DES could be mixed in the same request.
| 191.It Dv CRYPTO_NULL_HMAC
192.It Dv CRYPTO_NULL_CBC
193.El
194.It Va cri_klen
195Specifies the length of the key in bits, for variable-size key
196algorithms.
197.It Va cri_mlen
198Specifies how many bytes from the calculated hash should be copied back.
1990 means entire hash.
200.It Va cri_key
201Contains the key to be used with the algorithm.
202.It Va cri_iv
203Contains an explicit initialization vector (IV), if it does not prefix
204the data.
205This field is ignored during initialization.
206If no IV is explicitly passed (see below on details), a random IV is used
207by the device driver processing the request.
208.It Va cri_next
209Contains a pointer to another
210.Vt cryptoini
211structure.
212Multiple such structures may be linked to establish multi-algorithm sessions
213.Xr ( ipsec 4
214is an example consumer of such a feature).
215.El
216.Pp
217The
218.Vt cryptoini
219structure and its contents will not be modified by the framework (or
220the drivers used).
221Subsequent requests for processing that use the
222SID returned will avoid the cost of re-initializing the hardware (in
223essence, SID acts as an index in the session cache of the driver).
224.Pp
225.Fn crypto_freesession
226is called with the SID returned by
227.Fn crypto_newsession
228to disestablish the session.
229.Pp
230.Fn crypto_dispatch
231is called to process a request.
232The various fields in the
233.Vt cryptop
234structure are:
235.Bl -tag -width ".Va crp_callback"
236.It Va crp_sid
237Contains the SID.
238.It Va crp_ilen
239Indicates the total length in bytes of the buffer to be processed.
240.It Va crp_olen
241On return, contains the total length of the result.
242For symmetric crypto operations, this will be the same as the input length.
243This will be used if the framework needs to allocate a new
244buffer for the result (or for re-formatting the input).
245.It Va crp_callback
246This routine is invoked upon completion of the request, whether
247successful or not.
248It is invoked through the
249.Fn crypto_done
250routine.
251If the request was not successful, an error code is set in the
252.Va crp_etype
253field.
254It is the responsibility of the callback routine to set the appropriate
255.Xr spl 9
256level.
257.It Va crp_etype
258Contains the error type, if any errors were encountered, or zero if
259the request was successfully processed.
260If the
261.Er EAGAIN
262error code is returned, the SID has changed (and has been recorded in the
263.Va crp_sid
264field).
265The consumer should record the new SID and use it in all subsequent requests.
266In this case, the request may be re-submitted immediately.
267This mechanism is used by the framework to perform
268session migration (move a session from one driver to another, because
269of availability, performance, or other considerations).
270.Pp
271Note that this field only makes sense when examined by
272the callback routine specified in
273.Va crp_callback .
274Errors are returned to the invoker of
275.Fn crypto_process
276only when enough information is not present to call the callback
277routine (i.e., if the pointer passed is
278.Dv NULL
279or if no callback routine was specified).
280.It Va crp_flags
281Is a bitmask of flags associated with this request.
282Currently defined flags are:
283.Bl -tag -width ".Dv CRYPTO_F_IMBUF"
284.It Dv CRYPTO_F_IMBUF
285The buffer pointed to by
286.Va crp_buf
287is an mbuf chain.
288.El
289.It Va crp_buf
290Points to the input buffer.
291On return (when the callback is invoked),
292it contains the result of the request.
293The input buffer may be an mbuf
294chain or a contiguous buffer,
295depending on
296.Va crp_flags .
297.It Va crp_opaque
298This is passed through the crypto framework untouched and is
299intended for the invoking application's use.
300.It Va crp_desc
301This is a linked list of descriptors.
302Each descriptor provides
303information about what type of cryptographic operation should be done
304on the input buffer.
305The various fields are:
306.Bl -tag -width ".Va crd_inject"
307.It Va crd_skip
308The offset in the input buffer where processing should start.
309.It Va crd_len
310How many bytes, after
311.Va crd_skip ,
312should be processed.
313.It Va crd_inject
314Offset from the beginning of the buffer to insert any results.
315For encryption algorithms, this is where the initialization vector
316(IV) will be inserted when encrypting or where it can be found when
317decrypting (subject to
318.Va crd_flags ) .
319For MAC algorithms, this is where the result of the keyed hash will be
320inserted.
321.It Va crd_flags
322The following flags are defined:
323.Bl -tag -width ".Dv CRD"
324.It Dv CRD_F_ENCRYPT
325For encryption algorithms, this bit is set when encryption is required
326(when not set, decryption is performed).
327.It Dv CRD_F_IV_PRESENT
328For encryption algorithms, this bit is set when the IV already
329precedes the data, so the
330.Va crd_inject
331value will be ignored and no IV will be written in the buffer.
332Otherwise, the IV used to encrypt the packet will be written
333at the location pointed to by
334.Va crd_inject .
335The IV length is assumed to be equal to the blocksize of the
336encryption algorithm.
337Some applications that do special
338.Dq "IV cooking" ,
339such as the half-IV mode in
340.Xr ipsec 4 ,
341can use this flag to indicate that the IV should not be written on the packet.
342This flag is typically used in conjunction with the
343.Dv CRD_F_IV_EXPLICIT
344flag.
345.It Dv CRD_F_IV_EXPLICIT
346For encryption algorithms, this bit is set when the IV is explicitly
347provided by the consumer in the
348.Va cri_iv
349field.
350Otherwise, for encryption operations the IV is provided for by
351the driver used to perform the operation, whereas for decryption
352operations it is pointed to by the
353.Va crd_inject
354field.
355This flag is typically used when the IV is calculated
356.Dq "on the fly"
357by the consumer, and does not precede the data (some
358.Xr ipsec 4
359configurations, and the encrypted swap are two such examples).
360.It Dv CRD_F_KEY_EXPLICIT
361For encryption algorithms, this bit is set when the key is explicitly
362provided by the consumer in the
363.Va cri_key
364field for the given operation.
365Otherwise, the key is taken at newsession time from the same field.
366.It Dv CRD_F_COMP
367For compression algorithms, this bit is set when compression is required (when
368not set, decompression is performed).
369.El
370.It Va CRD_INI
371This
372.Vt cryptoini
373structure will not be modified by the framework or the device drivers.
374Since this information accompanies every cryptographic
375operation request, drivers may re-initialize state on-demand
376(typically an expensive operation).
377Furthermore, the cryptographic
378framework may re-route requests as a result of full queues or hardware
379failure, as described above.
380.It Va crd_next
381Point to the next descriptor.
382Linked operations are useful in protocols such as
383.Xr ipsec 4 ,
384where multiple cryptographic transforms may be applied on the same
385block of data.
386.El
387.El
388.Pp
389.Fn crypto_getreq
390allocates a
391.Vt cryptop
392structure with a linked list of as many
393.Vt cryptodesc
394structures as were specified in the argument passed to it.
395.Pp
396.Fn crypto_freereq
397deallocates a structure
398.Vt cryptop
399and any
400.Vt cryptodesc
401structures linked to it.
402Note that it is the responsibility of the
403callback routine to do the necessary cleanups associated with the
404opaque field in the
405.Vt cryptop
406structure.
407.Pp
408.Fn crypto_kdispatch
409is called to perform a keying operation.
410The various fields in the
411.Vt cryptkop
412structure are:
413.Bl -tag -width ".Va krp_callback'
414.It Va krp_op
415Operation code, such as
416.Dv CRK_MOD_EXP .
417.It Va krp_status
418Return code.
419This
420.Va errno Ns -style
421variable indicates whether lower level reasons
422for operation failure.
423.It Va krp_iparams
424Number if input parameters to the specified operation.
425Note that each operation has a (typically hardwired) number of such parameters.
426.It Va krp_oparams
427Number if output parameters from the specified operation.
428Note that each operation has a (typically hardwired) number of such parameters.
429.It Va krp_kvp
430An array of kernel memory blocks containing the parameters.
431.It Va krp_hid
432Identifier specifying which low-level driver is being used.
433.It Va krp_callback
434Callback called on completion of a keying operation.
435.El
436.Sh DRIVER-SIDE API
437The
438.Fn crypto_get_driverid ,
439.Fn crypto_register ,
440.Fn crypto_kregister ,
441.Fn crypto_unregister ,
442.Fn crypto_unblock ,
443and
444.Fn crypto_done
445routines are used by drivers that provide support for cryptographic
446primitives to register and unregister with the kernel crypto services
447framework.
448Drivers must first use the
449.Fn crypto_get_driverid
450function to acquire a driver identifier, specifying the
451.Fa cc_flags
452as an argument (normally 0, but software-only drivers should specify
453.Dv CRYPTOCAP_F_SOFTWARE ) .
454For each algorithm the driver supports, it must then call
455.Fn crypto_register .
456The first two arguments are the driver and algorithm identifiers.
457The next two arguments specify the largest possible operator length (in bits,
458important for public key operations) and flags for this algorithm.
459The last four arguments must be provided in the first call to
460.Fn crypto_register
461and are ignored in all subsequent calls.
462They are pointers to three
463driver-provided functions that the framework may call to establish new
464cryptographic context with the driver, free already established
465context, and ask for a request to be processed (encrypt, decrypt,
466etc.); and an opaque parameter to pass when calling each of these routines.
467.Fn crypto_unregister
468is called by drivers that wish to withdraw support for an algorithm.
469The two arguments are the driver and algorithm identifiers, respectively.
470Typically, drivers for
471PCMCIA
472crypto cards that are being ejected will invoke this routine for all
473algorithms supported by the card.
474.Fn crypto_unregister_all
475will unregister all algorithms registered by a driver
476and the driver will be disabled (no new sessions will be allocated on
477that driver, and any existing sessions will be migrated to other
478drivers).
479The same will be done if all algorithms associated with a driver are
480unregistered one by one.
481.Pp
482The calling convention for the three driver-supplied routines is:
483.Pp
484.Bl -item -compact
485.It
486.Ft int
487.Fn \*[lp]*newsession\*[rp] "void *" "u_int32_t *" "struct cryptoini *" ;
488.It
489.Ft int
490.Fn \*[lp]*freesession\*[rp] "void *" "u_int64_t" ;
491.It
492.Ft int
493.Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ;
494.It
495.Ft int
496.Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ;
497.El
498.Pp
499On invocation, the first argument to
500all routines is an opaque data value supplied when the algorithm
501is registered with
502.Fn crypto_register .
503The second argument to
504.Fn newsession
505contains the driver identifier obtained via
506.Fn crypto_get_driverid .
507On successful return, it should contain a driver-specific session
508identifier.
509The third argument is identical to that of
510.Fn crypto_newsession .
511.Pp
512The
513.Fn freesession
514routine takes as arguments the opaque data value and the SID
515(which is the concatenation of the
516driver identifier and the driver-specific session identifier).
517It should clear any context associated with the session (clear hardware
518registers, memory, etc.).
519.Pp
520The
521.Fn process
522routine is invoked with a request to perform crypto processing.
523This routine must not block, but should queue the request and return
524immediately.
525Upon processing the request, the callback routine should be invoked.
526In case of an unrecoverable error, the error indication must be placed in the
527.Va crp_etype
528field of the
529.Vt cryptop
530structure.
531When the request is completed, or an error is detected, the
532.Fn process
533routine should invoke
534.Fn crypto_done .
535Session migration may be performed, as mentioned previously.
536.Pp
537In case of a temporary resource exhaustion, the
538.Fn process
539routine may return
540.Er ERESTART
541in which case the crypto services will requeue the request, mark the driver
542as
543.Dq blocked ,
544and stop submitting requests for processing.
545The driver is then responsible for notifying the crypto services
546when it is again able to process requests through the
547.Fn crypto_unblock
548routine.
549This simple flow control mechanism should only be used for short-lived
550resource exhaustion as it causes operations to be queued in the crypto
551layer.
552Doing so is preferable to returning an error in such cases as
553it can cause network protocols to degrade performance by treating the
554failure much like a lost packet.
555.Pp
556The
557.Fn kprocess
558routine is invoked with a request to perform crypto key processing.
559This routine must not block, but should queue the request and return
560immediately.
561Upon processing the request, the callback routine should be invoked.
562In case of an unrecoverable error, the error indication must be placed in the
563.Va krp_status
564field of the
565.Vt cryptkop
566structure.
567When the request is completed, or an error is detected, the
568.Fn kprocess
569routine should invoked
570.Fn crypto_kdone .
571.Sh RETURN VALUES
572.Fn crypto_register ,
573.Fn crypto_kregister ,
574.Fn crypto_unregister ,
575.Fn crypto_newsession ,
576.Fn crypto_freesession ,
577and
578.Fn crypto_unblock
579return 0 on success, or an error code on failure.
580.Fn crypto_get_driverid
581returns a non-negative value on error, and \-1 on failure.
582.Fn crypto_getreq
583returns a pointer to a
584.Vt cryptop
585structure and
586.Dv NULL
587on failure.
588.Fn crypto_dispatch
589returns
590.Er EINVAL
591if its argument or the callback function was
592.Dv NULL ,
593and 0 otherwise.
594The callback is provided with an error code in case of failure, in the
595.Va crp_etype
596field.
597.Sh FILES
598.Bl -tag -width ".Pa sys/opencrypto/crypto.c"
599.It Pa sys/opencrypto/crypto.c
600most of the framework code
601.El
602.Sh SEE ALSO
603.Xr ipsec 4 ,
604.Xr malloc 9 ,
605.Xr sleep 9
606.Sh HISTORY
607The cryptographic framework first appeared in
608.Ox 2.7
609and was written by
610.An "Angelos D. Keromytis" Aq angelos@openbsd.org .
611.Sh BUGS
612The framework currently assumes that all the algorithms in a
613.Fn crypto_newsession
614operation must be available by the same driver.
615If that is not the case, session initialization will fail.
616.Pp
617The framework also needs a mechanism for determining which driver is
618best for a specific set of algorithms associated with a session.
619Some type of benchmarking is in order here.
620.Pp
621Multiple instances of the same algorithm in the same session are not
622supported.
623Note that 3DES is considered one algorithm (and not three
624instances of DES).
625Thus, 3DES and DES could be mixed in the same request.
|