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