xref: /freebsd/share/man/man9/crypto.9 (revision 7621fdab1a007818670d381e5ce0cfd93d94bb3b)
1f4bf4335SSam Leffler.\"	$OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $
2f4bf4335SSam Leffler.\"
3f4bf4335SSam Leffler.\" The author of this man page is Angelos D. Keromytis (angelos@cis.upenn.edu)
4f4bf4335SSam Leffler.\"
5f4bf4335SSam Leffler.\" Copyright (c) 2000, 2001 Angelos D. Keromytis
6f4bf4335SSam Leffler.\"
7f4bf4335SSam Leffler.\" Permission to use, copy, and modify this software with or without fee
8f4bf4335SSam Leffler.\" is hereby granted, provided that this entire notice is included in
9f4bf4335SSam Leffler.\" all source code copies of any software which is or includes a copy or
10f4bf4335SSam Leffler.\" modification of this software.
11f4bf4335SSam Leffler.\"
12f4bf4335SSam Leffler.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
13f4bf4335SSam Leffler.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY
14f4bf4335SSam Leffler.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
15f4bf4335SSam Leffler.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
16f4bf4335SSam Leffler.\" PURPOSE.
17f4bf4335SSam Leffler.\"
187621fdabSRuslan Ermilov.\" $FreeBSD$
197621fdabSRuslan Ermilov.\"
201403a8c7SSam Leffler.Dd October 14, 2002
21f4bf4335SSam Leffler.Dt CRYPTO 9
22f4bf4335SSam Leffler.Os
23f4bf4335SSam Leffler.Sh NAME
24f4bf4335SSam Leffler.Nm crypto
25f4bf4335SSam Leffler.Nd API for cryptographic services in the kernel
26f4bf4335SSam Leffler.Sh SYNOPSIS
277621fdabSRuslan Ermilov.In opencrypto/cryptodev.h
28f4bf4335SSam Leffler.Ft int32_t
297621fdabSRuslan Ermilov.Fn crypto_get_driverid u_int8_t
30f4bf4335SSam Leffler.Ft int
317621fdabSRuslan Ermilov.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 *"
32f4bf4335SSam Leffler.Ft int
337621fdabSRuslan Ermilov.Fn crypto_kregister u_int32_t int u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *"
34f4bf4335SSam Leffler.Ft int
357621fdabSRuslan Ermilov.Fn crypto_unregister u_int32_t int
361403a8c7SSam Leffler.Ft int
377621fdabSRuslan Ermilov.Fn crypto_unregister_all u_int32_t
38f4bf4335SSam Leffler.Ft void
39f4bf4335SSam Leffler.Fn crypto_done "struct cryptop *"
40f4bf4335SSam Leffler.Ft void
41f4bf4335SSam Leffler.Fn crypto_kdone "struct cryptkop *"
42f4bf4335SSam Leffler.Ft int
437621fdabSRuslan Ermilov.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" int
44f4bf4335SSam Leffler.Ft int
457621fdabSRuslan Ermilov.Fn crypto_freesession u_int64_t
46f4bf4335SSam Leffler.Ft int
47f4bf4335SSam Leffler.Fn crypto_dispatch "struct cryptop *"
48f4bf4335SSam Leffler.Ft int
49f4bf4335SSam Leffler.Fn crypto_kdispatch "struct cryptkop *"
501403a8c7SSam Leffler.Ft int
517621fdabSRuslan Ermilov.Fn crypto_unblock u_int32_t int
527621fdabSRuslan Ermilov.Ft "struct cryptop *"
537621fdabSRuslan Ermilov.Fn crypto_getreq int
54f4bf4335SSam Leffler.Ft void
557621fdabSRuslan Ermilov.Fn crypto_freereq void
56f4bf4335SSam Leffler.Bd -literal
571403a8c7SSam Leffler#define	CRYPTO_SYMQ	0x1
581403a8c7SSam Leffler#define	CRYPTO_ASYMQ	0x2
591403a8c7SSam Leffler
60f4bf4335SSam Leffler#define EALG_MAX_BLOCK_LEN      16
61f4bf4335SSam Leffler
62f4bf4335SSam Lefflerstruct cryptoini {
63f4bf4335SSam Leffler	int                cri_alg;
64f4bf4335SSam Leffler	int                cri_klen;
65f4bf4335SSam Leffler	int                cri_rnd;
66f4bf4335SSam Leffler	caddr_t            cri_key;
67f4bf4335SSam Leffler	u_int8_t           cri_iv[EALG_MAX_BLOCK_LEN];
68f4bf4335SSam Leffler	struct cryptoini  *cri_next;
69f4bf4335SSam Leffler};
70f4bf4335SSam Leffler
71f4bf4335SSam Lefflerstruct cryptodesc {
72f4bf4335SSam Leffler	int                crd_skip;
73f4bf4335SSam Leffler	int                crd_len;
74f4bf4335SSam Leffler	int                crd_inject;
75f4bf4335SSam Leffler	int                crd_flags;
76f4bf4335SSam Leffler	struct cryptoini   CRD_INI;
77f4bf4335SSam Leffler	struct cryptodesc *crd_next;
78f4bf4335SSam Leffler};
79f4bf4335SSam Leffler
80f4bf4335SSam Lefflerstruct cryptop {
811403a8c7SSam Leffler	TAILQ_ENTRY(cryptop) crp_next;
82f4bf4335SSam Leffler	u_int64_t          crp_sid;
83f4bf4335SSam Leffler	int                crp_ilen;
84f4bf4335SSam Leffler	int                crp_olen;
85f4bf4335SSam Leffler	int                crp_etype;
86f4bf4335SSam Leffler	int                crp_flags;
87f4bf4335SSam Leffler	caddr_t            crp_buf;
88f4bf4335SSam Leffler	caddr_t            crp_opaque;
89f4bf4335SSam Leffler	struct cryptodesc *crp_desc;
90f4bf4335SSam Leffler	int              (*crp_callback) (struct cryptop *);
91f4bf4335SSam Leffler	caddr_t            crp_mac;
92f4bf4335SSam Leffler};
93f4bf4335SSam Leffler
94f4bf4335SSam Lefflerstruct crparam {
95f4bf4335SSam Leffler        caddr_t         crp_p;
96f4bf4335SSam Leffler        u_int           crp_nbits;
97f4bf4335SSam Leffler};
98f4bf4335SSam Leffler
99f4bf4335SSam Leffler#define CRK_MAXPARAM    8
100f4bf4335SSam Leffler
101f4bf4335SSam Lefflerstruct cryptkop {
1021403a8c7SSam Leffler        TAILQ_ENTRY(cryptkop) krp_next;
103f4bf4335SSam Leffler        u_int              krp_op;         /* ie. CRK_MOD_EXP or other */
104f4bf4335SSam Leffler        u_int              krp_status;     /* return status */
105f4bf4335SSam Leffler        u_short            krp_iparams;    /* # of input parameters */
106f4bf4335SSam Leffler        u_short            krp_oparams;    /* # of output parameters */
107f4bf4335SSam Leffler	u_int32_t	   krp_hid;
1081403a8c7SSam Leffler        struct crparam     krp_param[CRK_MAXPARAM];
109f4bf4335SSam Leffler        int               (*krp_callback)(struct cryptkop *);
110f4bf4335SSam Leffler};
111f4bf4335SSam Leffler.Ed
112f4bf4335SSam Leffler.Sh DESCRIPTION
113f4bf4335SSam Leffler.Nm
114f4bf4335SSam Leffleris a framework for drivers of cryptographic hardware to register with
115f4bf4335SSam Lefflerthe kernel so
116f4bf4335SSam Leffler.Dq consumers
1171403a8c7SSam Leffler(other kernel subsystems, and
1181403a8c7SSam Lefflerusers through the
1191403a8c7SSam Leffler.Pa /dev/crypto
1201403a8c7SSam Lefflerdevice) are able to make use of it.
121f4bf4335SSam LefflerDrivers register with the framework the algorithms they support,
122f4bf4335SSam Lefflerand provide entry points (functions) the framework may call to
123f4bf4335SSam Lefflerestablish, use, and tear down sessions.
124f4bf4335SSam LefflerSessions are used to cache cryptographic information in a particular driver
125f4bf4335SSam Leffler(or associated hardware), so initialization is not needed with every request.
126f4bf4335SSam LefflerConsumers of cryptographic services pass a set of
127f4bf4335SSam Lefflerdescriptors that instruct the framework (and the drivers registered
128f4bf4335SSam Lefflerwith it) of the operations that should be applied on the data (more
129f4bf4335SSam Lefflerthan one cryptographic operation can be requested).
130f4bf4335SSam Leffler.Pp
131f4bf4335SSam LefflerKeying operations are supported as well.
132f4bf4335SSam LefflerUnlike the symmetric operators described above,
133f4bf4335SSam Lefflerthese sessionless commands perform mathematical operations using
134f4bf4335SSam Lefflerinput and output parameters.
135f4bf4335SSam Leffler.Pp
136f4bf4335SSam LefflerSince the consumers may not be associated with a process, drivers may
1371403a8c7SSam Lefflernot
1381403a8c7SSam Leffler.Xr sleep 9 .
139f4bf4335SSam LefflerThe same holds for the framework.
140f4bf4335SSam LefflerThus, a callback mechanism is used
141f4bf4335SSam Lefflerto notify a consumer that a request has been completed (the
142f4bf4335SSam Lefflercallback is specified by the consumer on an per-request basis).
143f4bf4335SSam LefflerThe callback is invoked by the framework whether the request was
144f4bf4335SSam Lefflersuccessfully completed or not.
145f4bf4335SSam LefflerAn error indication is provided in the latter case.
146f4bf4335SSam LefflerA specific error code,
147f4bf4335SSam Leffler.Er EAGAIN ,
148f4bf4335SSam Leffleris used to indicate that a session number has changed and that the
149f4bf4335SSam Lefflerrequest may be re-submitted immediately with the new session number.
150f4bf4335SSam LefflerErrors are only returned to the invoking function if not
151f4bf4335SSam Lefflerenough information to call the callback is available (meaning, there
152f4bf4335SSam Lefflerwas a fatal error in verifying the arguments).
153f4bf4335SSam LefflerFor session initialization and teardown there is no callback mechanism used.
154f4bf4335SSam Leffler.Pp
155f4bf4335SSam LefflerThe
156f4bf4335SSam Leffler.Fn crypto_newsession
157f4bf4335SSam Lefflerroutine is called by consumers of cryptographic services (such as the
158f4bf4335SSam Leffler.Xr ipsec 4
159f4bf4335SSam Lefflerstack) that wish to establish a new session with the framework.
160f4bf4335SSam LefflerOn success, the first argument will contain the Session Identifier (SID).
161f4bf4335SSam LefflerThe second argument contains all the necessary information for
162f4bf4335SSam Lefflerthe driver to establish the session.
163f4bf4335SSam LefflerThe third argument indicates whether a
164f4bf4335SSam Lefflerhardware driver (1) should be used or not (0).
165f4bf4335SSam LefflerThe various fields in the
1667621fdabSRuslan Ermilov.Vt cryptoini
167f4bf4335SSam Lefflerstructure are:
1687621fdabSRuslan Ermilov.Bl -tag -width ".Va cri_next"
1697621fdabSRuslan Ermilov.It Va cri_alg
170f4bf4335SSam LefflerContains an algorithm identifier.
171f4bf4335SSam LefflerCurrently supported algorithms are:
172f4bf4335SSam Leffler.Pp
1737621fdabSRuslan Ermilov.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
1747621fdabSRuslan Ermilov.It Dv CRYPTO_DES_CBC
1757621fdabSRuslan Ermilov.It Dv CRYPTO_3DES_CBC
1767621fdabSRuslan Ermilov.It Dv CRYPTO_BLF_CBC
1777621fdabSRuslan Ermilov.It Dv CRYPTO_CAST_CBC
1787621fdabSRuslan Ermilov.It Dv CRYPTO_SKIPJACK_CBC
1797621fdabSRuslan Ermilov.It Dv CRYPTO_MD5_HMAC
1807621fdabSRuslan Ermilov.It Dv CRYPTO_SHA1_HMAC
1817621fdabSRuslan Ermilov.It Dv CRYPTO_RIPEMD160_HMAC
1827621fdabSRuslan Ermilov.It Dv CRYPTO_MD5_KPDK
1837621fdabSRuslan Ermilov.It Dv CRYPTO_SHA1_KPDK
1847621fdabSRuslan Ermilov.It Dv CRYPTO_AES_CBC
1857621fdabSRuslan Ermilov.It Dv CRYPTO_ARC4
1867621fdabSRuslan Ermilov.It Dv CRYPTO_MD5
1877621fdabSRuslan Ermilov.It Dv CRYPTO_SHA1
1887621fdabSRuslan Ermilov.It Dv CRYPTO_SHA2_HMAC
1897621fdabSRuslan Ermilov.It Dv CRYPTO_NULL_HMAC
1907621fdabSRuslan Ermilov.It Dv CRYPTO_NULL_CBC
1917621fdabSRuslan Ermilov.El
1927621fdabSRuslan Ermilov.It Va cri_klen
193f4bf4335SSam LefflerSpecifies the length of the key in bits, for variable-size key
194f4bf4335SSam Leffleralgorithms.
1957621fdabSRuslan Ermilov.It Va cri_rnd
196f4bf4335SSam LefflerSpecifies the number of rounds to be used with the algorithm, for
197f4bf4335SSam Lefflervariable-round algorithms.
1987621fdabSRuslan Ermilov.It Va cri_key
199f4bf4335SSam LefflerContains the key to be used with the algorithm.
2007621fdabSRuslan Ermilov.It Va cri_iv
201f4bf4335SSam LefflerContains an explicit initialization vector (IV), if it does not prefix
202f4bf4335SSam Lefflerthe data.
203f4bf4335SSam LefflerThis field is ignored during initialization.
204f4bf4335SSam LefflerIf no IV is explicitly passed (see below on details), a random IV is used
205f4bf4335SSam Lefflerby the device driver processing the request.
2067621fdabSRuslan Ermilov.It Va cri_next
207f4bf4335SSam LefflerContains a pointer to another
2087621fdabSRuslan Ermilov.Vt cryptoini
209f4bf4335SSam Lefflerstructure.
210f4bf4335SSam LefflerMultiple such structures may be linked to establish multi-algorithm sessions
2117621fdabSRuslan Ermilov.Xr ( ipsec 4
212f4bf4335SSam Leffleris an example consumer of such a feature).
213f4bf4335SSam Leffler.El
214f4bf4335SSam Leffler.Pp
215f4bf4335SSam LefflerThe
2167621fdabSRuslan Ermilov.Vt cryptoini
217f4bf4335SSam Lefflerstructure and its contents will not be modified by the framework (or
218f4bf4335SSam Lefflerthe drivers used).
219f4bf4335SSam LefflerSubsequent requests for processing that use the
220f4bf4335SSam LefflerSID returned will avoid the cost of re-initializing the hardware (in
221f4bf4335SSam Leffleressence, SID acts as an index in the session cache of the driver).
222f4bf4335SSam Leffler.Pp
223f4bf4335SSam Leffler.Fn crypto_freesession
224f4bf4335SSam Leffleris called with the SID returned by
225f4bf4335SSam Leffler.Fn crypto_newsession
226f4bf4335SSam Lefflerto disestablish the session.
227f4bf4335SSam Leffler.Pp
228f4bf4335SSam Leffler.Fn crypto_dispatch
229f4bf4335SSam Leffleris called to process a request.
230f4bf4335SSam LefflerThe various fields in the
2317621fdabSRuslan Ermilov.Vt cryptop
232f4bf4335SSam Lefflerstructure are:
2337621fdabSRuslan Ermilov.Bl -tag -width ".Va crp_callback"
2347621fdabSRuslan Ermilov.It Va crp_sid
235f4bf4335SSam LefflerContains the SID.
2367621fdabSRuslan Ermilov.It Va crp_ilen
237f4bf4335SSam LefflerIndicates the total length in bytes of the buffer to be processed.
2387621fdabSRuslan Ermilov.It Va crp_olen
239f4bf4335SSam LefflerOn return, contains the total length of the result.
240f4bf4335SSam LefflerFor symmetric crypto operations, this will be the same as the input length.
241f4bf4335SSam LefflerThis will be used if the framework needs to allocate a new
242f4bf4335SSam Lefflerbuffer for the result (or for re-formatting the input).
2437621fdabSRuslan Ermilov.It Va crp_callback
244f4bf4335SSam LefflerThis routine is invoked upon completion of the request, whether
245f4bf4335SSam Lefflersuccessful or not.
246f4bf4335SSam LefflerIt is invoked through the
247f4bf4335SSam Leffler.Fn crypto_done
248f4bf4335SSam Lefflerroutine.
249f4bf4335SSam LefflerIf the request was not successful, an error code is set in the
2507621fdabSRuslan Ermilov.Va crp_etype
251f4bf4335SSam Lefflerfield.
252f4bf4335SSam LefflerIt is the responsibility of the callback routine to set the appropriate
253f4bf4335SSam Leffler.Xr spl 9
254f4bf4335SSam Lefflerlevel.
2557621fdabSRuslan Ermilov.It Va crp_etype
256f4bf4335SSam LefflerContains the error type, if any errors were encountered, or zero if
257f4bf4335SSam Lefflerthe request was successfully processed.
258f4bf4335SSam LefflerIf the
259f4bf4335SSam Leffler.Er EAGAIN
260f4bf4335SSam Lefflererror code is returned, the SID has changed (and has been recorded in the
2617621fdabSRuslan Ermilov.Va crp_sid
262f4bf4335SSam Lefflerfield).
263f4bf4335SSam LefflerThe consumer should record the new SID and use it in all subsequent requests.
264f4bf4335SSam LefflerIn this case, the request may be re-submitted immediately.
265f4bf4335SSam LefflerThis mechanism is used by the framework to perform
266f4bf4335SSam Lefflersession migration (move a session from one driver to another, because
267f4bf4335SSam Lefflerof availability, performance, or other considerations).
268f4bf4335SSam Leffler.Pp
269f4bf4335SSam LefflerNote that this field only makes sense when examined by
270f4bf4335SSam Lefflerthe callback routine specified in
2717621fdabSRuslan Ermilov.Va crp_callback .
272f4bf4335SSam LefflerErrors are returned to the invoker of
273f4bf4335SSam Leffler.Fn crypto_process
274f4bf4335SSam Leffleronly when enough information is not present to call the callback
275f4bf4335SSam Lefflerroutine (i.e., if the pointer passed is
276f4bf4335SSam Leffler.Dv NULL
277f4bf4335SSam Leffleror if no callback routine was specified).
2787621fdabSRuslan Ermilov.It Va crp_flags
279f4bf4335SSam LefflerIs a bitmask of flags associated with this request.
280f4bf4335SSam LefflerCurrently defined flags are:
2817621fdabSRuslan Ermilov.Bl -tag -width ".Dv CRYPTO_F_IMBUF"
282f4bf4335SSam Leffler.It Dv CRYPTO_F_IMBUF
283f4bf4335SSam LefflerThe buffer pointed to by
2847621fdabSRuslan Ermilov.Va crp_buf
285f4bf4335SSam Leffleris an mbuf chain.
286f4bf4335SSam Leffler.El
2877621fdabSRuslan Ermilov.It Va crp_buf
288f4bf4335SSam LefflerPoints to the input buffer.
289f4bf4335SSam LefflerOn return (when the callback is invoked),
290f4bf4335SSam Lefflerit contains the result of the request.
291f4bf4335SSam LefflerThe input buffer may be an mbuf
2921403a8c7SSam Lefflerchain or a contiguous buffer,
293f4bf4335SSam Lefflerdepending on
2947621fdabSRuslan Ermilov.Va crp_flags .
2957621fdabSRuslan Ermilov.It Va crp_opaque
296f4bf4335SSam LefflerThis is passed through the crypto framework untouched and is
297f4bf4335SSam Lefflerintended for the invoking application's use.
2987621fdabSRuslan Ermilov.It Va crp_desc
299f4bf4335SSam LefflerThis is a linked list of descriptors.
300f4bf4335SSam LefflerEach descriptor provides
301f4bf4335SSam Lefflerinformation about what type of cryptographic operation should be done
302f4bf4335SSam Leffleron the input buffer.
303f4bf4335SSam LefflerThe various fields are:
3047621fdabSRuslan Ermilov.Bl -tag -width ".Va crd_inject"
3057621fdabSRuslan Ermilov.It Va crd_skip
306f4bf4335SSam LefflerThe offset in the input buffer where processing should start.
3077621fdabSRuslan Ermilov.It Va crd_len
308f4bf4335SSam LefflerHow many bytes, after
3097621fdabSRuslan Ermilov.Va crd_skip ,
310f4bf4335SSam Lefflershould be processed.
3117621fdabSRuslan Ermilov.It Va crd_inject
312f4bf4335SSam LefflerOffset from the beginning of the buffer to insert any results.
313f4bf4335SSam LefflerFor encryption algorithms, this is where the initialization vector
314f4bf4335SSam Leffler(IV) will be inserted when encrypting or where it can be found when
315f4bf4335SSam Lefflerdecrypting (subject to
3167621fdabSRuslan Ermilov.Va crd_flags ) .
317f4bf4335SSam LefflerFor MAC algorithms, this is where the result of the keyed hash will be
318f4bf4335SSam Lefflerinserted.
3197621fdabSRuslan Ermilov.It Va crd_flags
320f4bf4335SSam LefflerThe following flags are defined:
3217621fdabSRuslan Ermilov.Bl -tag -width ".Dv CRD_F_IV_EXPLICIT"
322f4bf4335SSam Leffler.It Dv CRD_F_ENCRYPT
323f4bf4335SSam LefflerFor encryption algorithms, this bit is set when encryption is required
324f4bf4335SSam Leffler(when not set, decryption is performed).
325f4bf4335SSam Leffler.It Dv CRD_F_IV_PRESENT
326f4bf4335SSam LefflerFor encryption algorithms, this bit is set when the IV already
327f4bf4335SSam Lefflerprecedes the data, so the
3287621fdabSRuslan Ermilov.Va crd_inject
329f4bf4335SSam Lefflervalue will be ignored and no IV will be written in the buffer.
330f4bf4335SSam LefflerOtherwise, the IV used to encrypt the packet will be written
331f4bf4335SSam Lefflerat the location pointed to by
3327621fdabSRuslan Ermilov.Va crd_inject .
333f4bf4335SSam LefflerThe IV length is assumed to be equal to the blocksize of the
334f4bf4335SSam Lefflerencryption algorithm.
335f4bf4335SSam LefflerSome applications that do special
3367621fdabSRuslan Ermilov.Dq "IV cooking" ,
337f4bf4335SSam Lefflersuch as the half-IV mode in
338f4bf4335SSam Leffler.Xr ipsec 4 ,
339f4bf4335SSam Lefflercan use this flag to indicate that the IV should not be written on the packet.
340f4bf4335SSam LefflerThis flag is typically used in conjunction with the
341f4bf4335SSam Leffler.Dv CRD_F_IV_EXPLICIT
342f4bf4335SSam Lefflerflag.
343f4bf4335SSam Leffler.It Dv CRD_F_IV_EXPLICIT
344f4bf4335SSam LefflerFor encryption algorithms, this bit is set when the IV is explicitly
345f4bf4335SSam Lefflerprovided by the consumer in the
3467621fdabSRuslan Ermilov.Va cri_iv
347f4bf4335SSam Lefflerfields.
348f4bf4335SSam LefflerOtherwise, for encryption operations the IV is provided for by
349f4bf4335SSam Lefflerthe driver used to perform the operation, whereas for decryption
350f4bf4335SSam Leffleroperations it is pointed to by the
3517621fdabSRuslan Ermilov.Va crd_inject
352f4bf4335SSam Lefflerfield.
353f4bf4335SSam LefflerThis flag is typically used when the IV is calculated
3547621fdabSRuslan Ermilov.Dq "on the fly"
355f4bf4335SSam Lefflerby the consumer, and does not precede the data (some
356f4bf4335SSam Leffler.Xr ipsec 4
357f4bf4335SSam Lefflerconfigurations, and the encrypted swap are two such examples).
358f4bf4335SSam Leffler.It Dv CRD_F_COMP
359f4bf4335SSam LefflerFor compression algorithms, this bit is set when compression is required (when
360f4bf4335SSam Lefflernot set, decompression is performed).
361f4bf4335SSam Leffler.El
3627621fdabSRuslan Ermilov.It Va CRD_INI
363f4bf4335SSam LefflerThis
3647621fdabSRuslan Ermilov.Vt cryptoini
365f4bf4335SSam Lefflerstructure will not be modified by the framework or the device drivers.
366f4bf4335SSam LefflerSince this information accompanies every cryptographic
367f4bf4335SSam Leffleroperation request, drivers may re-initialize state on-demand
368f4bf4335SSam Leffler(typically an expensive operation).
369f4bf4335SSam LefflerFurthermore, the cryptographic
370f4bf4335SSam Lefflerframework may re-route requests as a result of full queues or hardware
371f4bf4335SSam Lefflerfailure, as described above.
3727621fdabSRuslan Ermilov.It Va crd_next
373f4bf4335SSam LefflerPoint to the next descriptor.
374f4bf4335SSam LefflerLinked operations are useful in protocols such as
375f4bf4335SSam Leffler.Xr ipsec 4 ,
376f4bf4335SSam Lefflerwhere multiple cryptographic transforms may be applied on the same
377f4bf4335SSam Lefflerblock of data.
378f4bf4335SSam Leffler.El
379f4bf4335SSam Leffler.El
380f4bf4335SSam Leffler.Pp
381f4bf4335SSam Leffler.Fn crypto_getreq
382f4bf4335SSam Lefflerallocates a
3837621fdabSRuslan Ermilov.Vt cryptop
384f4bf4335SSam Lefflerstructure with a linked list of as many
3857621fdabSRuslan Ermilov.Vt cryptodesc
386f4bf4335SSam Lefflerstructures as were specified in the argument passed to it.
387f4bf4335SSam Leffler.Pp
388f4bf4335SSam Leffler.Fn crypto_freereq
389f4bf4335SSam Lefflerdeallocates a structure
3907621fdabSRuslan Ermilov.Vt cryptop
391f4bf4335SSam Lefflerand any
3927621fdabSRuslan Ermilov.Vt cryptodesc
393f4bf4335SSam Lefflerstructures linked to it.
394f4bf4335SSam LefflerNote that it is the responsibility of the
395f4bf4335SSam Lefflercallback routine to do the necessary cleanups associated with the
396f4bf4335SSam Leffleropaque field in the
3977621fdabSRuslan Ermilov.Vt cryptop
398f4bf4335SSam Lefflerstructure.
399f4bf4335SSam Leffler.Pp
400f4bf4335SSam Leffler.Fn crypto_kdispatch
401f4bf4335SSam Leffleris called to perform a keying operation.
402f4bf4335SSam LefflerThe various fields in the
4037621fdabSRuslan Ermilov.Vt cryptkop
404f4bf4335SSam Lefflerstructure are:
4057621fdabSRuslan Ermilov.Bl -tag -width ".Va krp_callback'
4067621fdabSRuslan Ermilov.It Va krp_op
4077621fdabSRuslan ErmilovOperation code, such as
4087621fdabSRuslan Ermilov.Dv CRK_MOD_EXP .
4097621fdabSRuslan Ermilov.It Va krp_status
410f4bf4335SSam LefflerReturn code.
4117621fdabSRuslan ErmilovThis
4127621fdabSRuslan Ermilov.Va errno Ns -style
4137621fdabSRuslan Ermilovvariable indicates whether lower level reasons
414f4bf4335SSam Lefflerfor operation failure.
4157621fdabSRuslan Ermilov.It Va krp_iparams
416f4bf4335SSam LefflerNumber if input parameters to the specified operation.
417f4bf4335SSam LefflerNote that each operation has a (typically hardwired) number of such parameters.
4187621fdabSRuslan Ermilov.It Va krp_oparams
419f4bf4335SSam LefflerNumber if output parameters from the specified operation.
420f4bf4335SSam LefflerNote that each operation has a (typically hardwired) number of such parameters.
4217621fdabSRuslan Ermilov.It Va krp_kvp
422f4bf4335SSam LefflerAn array of kernel memory blocks containing the parameters.
4237621fdabSRuslan Ermilov.It Va krp_hid
424f4bf4335SSam LefflerIdentifier specifying which low-level driver is being used.
4257621fdabSRuslan Ermilov.It Va krp_callback
426f4bf4335SSam LefflerCallback called on completion of a keying operation.
427f4bf4335SSam Leffler.El
428f4bf4335SSam Leffler.Sh DRIVER-SIDE API
429f4bf4335SSam LefflerThe
430f4bf4335SSam Leffler.Fn crypto_get_driverid ,
431f4bf4335SSam Leffler.Fn crypto_register ,
432f4bf4335SSam Leffler.Fn crypto_kregister ,
433f4bf4335SSam Leffler.Fn crypto_unregister ,
4341403a8c7SSam Leffler.Fn crypto_unblock ,
435f4bf4335SSam Lefflerand
436f4bf4335SSam Leffler.Fn crypto_done
437f4bf4335SSam Lefflerroutines are used by drivers that provide support for cryptographic
438f4bf4335SSam Lefflerprimitives to register and unregister with the kernel crypto services
439f4bf4335SSam Lefflerframework.
440f4bf4335SSam LefflerDrivers must first use the
441f4bf4335SSam Leffler.Fn crypto_get_driverid
442f4bf4335SSam Lefflerfunction to acquire a driver identifier, specifying the
443f4bf4335SSam Leffler.Fa cc_flags
444f4bf4335SSam Leffleras an argument (normally 0, but software-only drivers should specify
4457621fdabSRuslan Ermilov.Dv CRYPTOCAP_F_SOFTWARE ) .
446f4bf4335SSam LefflerFor each algorithm the driver supports, it must then call
447f4bf4335SSam Leffler.Fn crypto_register .
448f4bf4335SSam LefflerThe first two arguments are the driver and algorithm identifiers.
449f4bf4335SSam LefflerThe next two arguments specify the largest possible operator length (in bits,
4501403a8c7SSam Lefflerimportant for public key operations) and flags for this algorithm.
4511403a8c7SSam LefflerThe last four arguments must be provided in the first call to
452f4bf4335SSam Leffler.Fn crypto_register
453f4bf4335SSam Lefflerand are ignored in all subsequent calls.
454f4bf4335SSam LefflerThey are pointers to three
455f4bf4335SSam Lefflerdriver-provided functions that the framework may call to establish new
456f4bf4335SSam Lefflercryptographic context with the driver, free already established
457f4bf4335SSam Lefflercontext, and ask for a request to be processed (encrypt, decrypt,
4581403a8c7SSam Leffleretc.); and an opaque parameter to pass when calling each of these routines.
459f4bf4335SSam Leffler.Fn crypto_unregister
460f4bf4335SSam Leffleris called by drivers that wish to withdraw support for an algorithm.
461f4bf4335SSam LefflerThe two arguments are the driver and algorithm identifiers, respectively.
462f4bf4335SSam LefflerTypically, drivers for
4631403a8c7SSam LefflerPCMCIA
464f4bf4335SSam Lefflercrypto cards that are being ejected will invoke this routine for all
465f4bf4335SSam Leffleralgorithms supported by the card.
4661403a8c7SSam Leffler.Fn crypto_unregister_all
4671403a8c7SSam Lefflerwill unregister all algorithms registered by a driver
468f4bf4335SSam Lefflerand the driver will be disabled (no new sessions will be allocated on
469f4bf4335SSam Lefflerthat driver, and any existing sessions will be migrated to other
470f4bf4335SSam Lefflerdrivers).
471f4bf4335SSam LefflerThe same will be done if all algorithms associated with a driver are
472f4bf4335SSam Lefflerunregistered one by one.
473f4bf4335SSam Leffler.Pp
474f4bf4335SSam LefflerThe calling convention for the three driver-supplied routines is:
4757621fdabSRuslan Ermilov.Pp
4767621fdabSRuslan Ermilov.Bl -item -compact
4777621fdabSRuslan Ermilov.It
4787621fdabSRuslan Ermilov.Ft int
4797621fdabSRuslan Ermilov.Fn \*[lp]*newsession\*[rp] "void *" "u_int32_t *" "struct cryptoini *" ;
4807621fdabSRuslan Ermilov.It
4817621fdabSRuslan Ermilov.Ft int
4827621fdabSRuslan Ermilov.Fn \*[lp]*freesession\*[rp] "void *" "u_int64_t" ;
4837621fdabSRuslan Ermilov.It
4847621fdabSRuslan Ermilov.Ft int
4857621fdabSRuslan Ermilov.Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ;
4867621fdabSRuslan Ermilov.It
4877621fdabSRuslan Ermilov.Ft int
4887621fdabSRuslan Ermilov.Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ;
4897621fdabSRuslan Ermilov.El
490f4bf4335SSam Leffler.Pp
491f4bf4335SSam LefflerOn invocation, the first argument to
4921403a8c7SSam Lefflerall routines is an opaque data value supplied when the algorithm
4931403a8c7SSam Leffleris registered with
4941403a8c7SSam Leffler.Fn crypto_register .
4951403a8c7SSam LefflerThe second argument to
496f4bf4335SSam Leffler.Fn newsession
497f4bf4335SSam Lefflercontains the driver identifier obtained via
498f4bf4335SSam Leffler.Fn crypto_get_driverid .
4997621fdabSRuslan ErmilovOn successful return, it should contain a driver-specific session
500f4bf4335SSam Leffleridentifier.
5011403a8c7SSam LefflerThe third argument is identical to that of
502f4bf4335SSam Leffler.Fn crypto_newsession .
503f4bf4335SSam Leffler.Pp
504f4bf4335SSam LefflerThe
505f4bf4335SSam Leffler.Fn freesession
5061403a8c7SSam Lefflerroutine takes as arguments the opaque data value and the SID
5071403a8c7SSam Leffler(which is the concatenation of the
508f4bf4335SSam Lefflerdriver identifier and the driver-specific session identifier).
509f4bf4335SSam LefflerIt should clear any context associated with the session (clear hardware
510f4bf4335SSam Lefflerregisters, memory, etc.).
511f4bf4335SSam Leffler.Pp
512f4bf4335SSam LefflerThe
513f4bf4335SSam Leffler.Fn process
514f4bf4335SSam Lefflerroutine is invoked with a request to perform crypto processing.
515f4bf4335SSam LefflerThis routine must not block, but should queue the request and return
516f4bf4335SSam Lefflerimmediately.
517f4bf4335SSam LefflerUpon processing the request, the callback routine should be invoked.
5181403a8c7SSam LefflerIn case of an unrecoverable error, the error indication must be placed in the
5197621fdabSRuslan Ermilov.Va crp_etype
520f4bf4335SSam Lefflerfield of the
5217621fdabSRuslan Ermilov.Vt cryptop
522f4bf4335SSam Lefflerstructure.
523f4bf4335SSam LefflerWhen the request is completed, or an error is detected, the
524f4bf4335SSam Leffler.Fn process
5251403a8c7SSam Lefflerroutine should invoke
526f4bf4335SSam Leffler.Fn crypto_done .
527f4bf4335SSam LefflerSession migration may be performed, as mentioned previously.
528f4bf4335SSam Leffler.Pp
5291403a8c7SSam LefflerIn case of a temporary resource exhaustion, the
5307621fdabSRuslan Ermilov.Fn process
5311403a8c7SSam Lefflerroutine may return
5321403a8c7SSam Leffler.Er ERESTART
5331403a8c7SSam Lefflerin which case the crypto services will requeue the request, mark the driver
5347621fdabSRuslan Ermilovas
5357621fdabSRuslan Ermilov.Dq blocked ,
5367621fdabSRuslan Ermilovand stop submitting requests for processing.
5371403a8c7SSam LefflerThe driver is then responsible for notifying the crypto services
5381403a8c7SSam Lefflerwhen it is again able to process requests through the
5391403a8c7SSam Leffler.Fn crypto_unblock
5401403a8c7SSam Lefflerroutine.
5411403a8c7SSam LefflerThis simple flow control mechanism should only be used for short-lived
5421403a8c7SSam Lefflerresource exhaustion as it causes operations to be queued in the crypto
5431403a8c7SSam Lefflerlayer.
5447621fdabSRuslan ErmilovDoing so is preferable to returning an error in such cases as
5457621fdabSRuslan Ermilovit can cause network protocols to degrade performance by treating the
5461403a8c7SSam Lefflerfailure much like a lost packet.
5471403a8c7SSam Leffler.Pp
548f4bf4335SSam LefflerThe
549f4bf4335SSam Leffler.Fn kprocess
550f4bf4335SSam Lefflerroutine is invoked with a request to perform crypto key processing.
551f4bf4335SSam LefflerThis routine must not block, but should queue the request and return
552f4bf4335SSam Lefflerimmediately.
553f4bf4335SSam LefflerUpon processing the request, the callback routine should be invoked.
5541403a8c7SSam LefflerIn case of an unrecoverable error, the error indication must be placed in the
5557621fdabSRuslan Ermilov.Va krp_status
556f4bf4335SSam Lefflerfield of the
5577621fdabSRuslan Ermilov.Vt cryptkop
558f4bf4335SSam Lefflerstructure.
559f4bf4335SSam LefflerWhen the request is completed, or an error is detected, the
560f4bf4335SSam Leffler.Fn kprocess
561f4bf4335SSam Lefflerroutine should invoked
562f4bf4335SSam Leffler.Fn crypto_kdone .
563f4bf4335SSam Leffler.Sh RETURN VALUES
564f4bf4335SSam Leffler.Fn crypto_register ,
565f4bf4335SSam Leffler.Fn crypto_kregister ,
566f4bf4335SSam Leffler.Fn crypto_unregister ,
567f4bf4335SSam Leffler.Fn crypto_newsession ,
5681403a8c7SSam Leffler.Fn crypto_freesession ,
569f4bf4335SSam Lefflerand
5707621fdabSRuslan Ermilov.Fn crypto_unblock
571f4bf4335SSam Lefflerreturn 0 on success, or an error code on failure.
572f4bf4335SSam Leffler.Fn crypto_get_driverid
573f4bf4335SSam Lefflerreturns a non-negative value on error, and \-1 on failure.
574f4bf4335SSam Leffler.Fn crypto_getreq
575f4bf4335SSam Lefflerreturns a pointer to a
5767621fdabSRuslan Ermilov.Vt cryptop
577f4bf4335SSam Lefflerstructure and
578f4bf4335SSam Leffler.Dv NULL
579f4bf4335SSam Leffleron failure.
580f4bf4335SSam Leffler.Fn crypto_dispatch
581f4bf4335SSam Lefflerreturns
582f4bf4335SSam Leffler.Er EINVAL
5837621fdabSRuslan Ermilovif its argument or the callback function was
584f4bf4335SSam Leffler.Dv NULL ,
585f4bf4335SSam Lefflerand 0 otherwise.
586f4bf4335SSam LefflerThe callback is provided with an error code in case of failure, in the
5877621fdabSRuslan Ermilov.Va crp_etype
588f4bf4335SSam Lefflerfield.
589f4bf4335SSam Leffler.Sh FILES
5907621fdabSRuslan Ermilov.Bl -tag -width ".Pa sys/crypto/crypto.c"
591f4bf4335SSam Leffler.It Pa sys/crypto/crypto.c
592f4bf4335SSam Lefflermost of the framework code
593f4bf4335SSam Leffler.El
594f4bf4335SSam Leffler.Sh SEE ALSO
595f4bf4335SSam Leffler.Xr ipsec 4 ,
596f4bf4335SSam Leffler.Xr malloc 9 ,
5971403a8c7SSam Leffler.Xr sleep 9
598f4bf4335SSam Leffler.Sh HISTORY
599f4bf4335SSam LefflerThe cryptographic framework first appeared in
6007621fdabSRuslan Ermilov.Ox 2.7
6017621fdabSRuslan Ermilovand was written by
6027621fdabSRuslan Ermilov.An "Angelos D. Keromytis" Aq angelos@openbsd.org .
603f4bf4335SSam Leffler.Sh BUGS
604f4bf4335SSam LefflerThe framework currently assumes that all the algorithms in a
605f4bf4335SSam Leffler.Fn crypto_newsession
606f4bf4335SSam Leffleroperation must be available by the same driver.
6077621fdabSRuslan ErmilovIf that is not the case, session initialization will fail.
608f4bf4335SSam Leffler.Pp
609f4bf4335SSam LefflerThe framework also needs a mechanism for determining which driver is
610f4bf4335SSam Lefflerbest for a specific set of algorithms associated with a session.
611f4bf4335SSam LefflerSome type of benchmarking is in order here.
612f4bf4335SSam Leffler.Pp
613f4bf4335SSam LefflerMultiple instances of the same algorithm in the same session are not
614f4bf4335SSam Lefflersupported.
615f4bf4335SSam LefflerNote that 3DES is considered one algorithm (and not three
616f4bf4335SSam Lefflerinstances of DES).
617f4bf4335SSam LefflerThus, 3DES and DES could be mixed in the same request.
618