/share/man/man9/crypto.9

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