1.\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $
2.\"
3.\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu)
4.\"
5.\" Copyright (c) 2000, 2001 Angelos D. Keromytis
6.\"
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.
11.\"
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
16.\" PURPOSE.
17.\"
| 1.\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $
2.\"
3.\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu)
4.\"
5.\" Copyright (c) 2000, 2001 Angelos D. Keromytis
6.\"
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.
11.\"
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
16.\" PURPOSE.
17.\"
|
18.\" $FreeBSD: head/share/man/man9/crypto.9 157635 2006-04-10 18:17:43Z pjd $
| 18.\" $FreeBSD: head/share/man/man9/crypto.9 157636 2006-04-10 18:19:29Z pjd $
|
19.\"
20.Dd October 14, 2002
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_rnd;
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
188.It Dv CRYPTO_SHA2_HMAC
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_rnd
196Specifies the number of rounds to be used with the algorithm, for
197variable-round algorithms.
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.
| 19.\"
20.Dd October 14, 2002
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_rnd;
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
188.It Dv CRYPTO_SHA2_HMAC
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_rnd
196Specifies the number of rounds to be used with the algorithm, for
197variable-round algorithms.
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 from at newsession time from the same field.
| 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.
| 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.
|