CRYPTO_GET_DRIVERID(9) | Kernel Developer's Manual | CRYPTO_GET_DRIVERID(9) |
crypto_get_driverid
,
crypto_register
,
crypto_unregister
,
crypto_done
,
crypto_newsession
,
crypto_freesession
,
crypto_dispatch
,
crypto_getreq
,
crypto_freereq
— API for
cryptographic services in the kernel
#include
<crypto/cryptodev.h>
int32_t
crypto_get_driverid
(u_int8_t);
int
crypto_register
(u_int32_t,
int *,
int (*)(u_int32_t *, struct
cryptoini *), int
(*)(u_int64_t), int
(*)(struct cryptop *));
int
crypto_unregister
(u_int32_t,
int);
void
crypto_done
(struct
cryptop *);
int
crypto_newsession
(u_int64_t
*, struct cryptoini
*, int);
int
crypto_freesession
(u_int64_t);
int
crypto_dispatch
(struct
cryptop *);
struct cryptop *
crypto_getreq
(int);
void
crypto_freereq
(struct
cryptop *);
#define EALG_MAX_BLOCK_LEN 16 struct cryptoini { int cri_alg; int cri_klen; int cri_rnd; caddr_t cri_key; u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; struct cryptoini *cri_next; }; struct cryptodesc { int crd_skip; int crd_len; int crd_inject; int crd_flags; struct cryptoini CRD_INI; struct cryptodesc *crd_next; }; struct cryptop { u_int64_t crp_sid; int crp_ilen; int crp_olen; int crp_alloctype; int crp_etype; int crp_flags; void *crp_buf; void *crp_opaque; struct cryptodesc *crp_desc; int (*crp_callback)(struct cryptop *); struct cryptop *crp_next; caddr_t crp_mac; };
crypto_get_driverid
is a framework for
drivers of cryptographic hardware to register with the kernel so
“consumers” (other kernel subsystems, and eventually users
through an appropriate device) are able to make use of it. Drivers register
with the framework the algorithms they support, and provide entry points
(functions) the framework may call to establish, use, and tear down
sessions. Sessions are used to cache cryptographic information in a
particular driver (or associated hardware), so initialization is not needed
with every request. Consumers of cryptographic services pass a set of
descriptors that instruct the framework (and the drivers registered with it)
of the operations that should be applied on the data (more than one
cryptographic operation can be requested).
Since the consumers may not be associated with a process, drivers
may not use tsleep(9). The same holds for
the framework. Thus, a callback mechanism is used to notify a consumer that
a request has been completed (the callback is specified by the consumer on a
per-request basis). The callback is invoked by the framework whether the
request was successfully completed or not. An error indication is provided
in the latter case. A specific error code, EAGAIN
,
is used to indicate that a session number has changed and that the request
may be re-submitted immediately with the new session number. Errors are only
returned to the invoking function if not enough information to call the
callback is available (meaning, there was a fatal error in verifying the
arguments). For session initialization and teardown there is no callback
mechanism used.
The crypto_newsession
() routine is called
by consumers of cryptographic services (such as the
ipsec(4) stack) that wish to establish a
new session with the framework. On success, the first argument will contain
the Session Identifier (SID). The second argument contains all the necessary
information for the driver to establish the session. The third argument
indicates whether a hardware driver should be used (1) or not (0). The
various fields in the cryptoini structure are:
CRYPTO_3DES_CBC CRYPTO_BLF_CBC CRYPTO_CAST_CBC CRYPTO_AES_CBC CRYPTO_AES_CTR CRYPTO_AES_XTS
Authentication algorithms are:
CRYPTO_MD5_HMAC CRYPTO_SHA1_HMAC CRYPTO_RIPEMD160_HMAC CRYPTO_SHA2_256_HMAC CRYPTO_SHA2_384_HMAC CRYPTO_SHA2_512_HMAC
Algorithms performing authenticated encryption are:
CRYPTO_AES_GCM_16 CRYPTO_AES_GMAC CRYPTO_CHACHA20_POLY1305
In the case of the CRYPTO_AES_XTS transform, the IV should be provided as a 64-bit block number in host byte order.
The cryptoini structure and its contents will not be modified by the framework (or the drivers used). Subsequent requests for processing that use the SID returned will avoid the cost of re-initializing the hardware (in essence, SID acts as an index in the session cache of the driver).
crypto_freesession
() is called with the
SID returned by crypto_newsession
() to disestablish
the session.
crypto_dispatch
() is called to process a
request. The various fields in the cryptop structure
are:
crypto_done
()
routine. If the request was not successful, an error code is set in the
crp_etype field. It is the responsibility of the
callback routine to set the appropriate
spl(9) level.EAGAIN
error code is returned, the SID has changed (and has been recorded in the
crp_sid field). The consumer should record the new
SID and use it in all subsequent requests. In this case, the request may
be re-submitted immediately. This mechanism is used by the framework to
perform session migration (move a session from one driver to another,
because of availability, performance, or other considerations).
Note that this field only makes sense when examined by the
callback routine specified in crp_callback. Errors
are returned to the invoker of crypto_process
()
only when enough information is not present to call the callback routine
(i.e., if the pointer passed is NULL
or if no
callback routine was specified).
CRYPTO_F_IMBUF
CRD_F_ENCRYPT
CRD_F_IV_PRESENT
CRD_F_IV_EXPLICIT
flag.CRD_F_IV_EXPLICIT
CRD_F_COMP
crypto_getreq
() allocates a
cryptop structure with a linked list of as many
cryptodesc structures as were specified in the
argument passed to it.
crypto_freereq
() deallocates a structure
cryptop and any cryptodesc
structures linked to it. Note that it is the responsibility of the callback
routine to do the necessary cleanups associated with the opaque field in the
cryptop structure.
The crypto_get_driverid
(),
crypto_register
(),
crypto_unregister
(), and
crypto_done
() routines are used by drivers that
provide support for cryptographic primitives to register and unregister with
the kernel crypto services framework. Drivers must first use the
crypto_get_driverid
() function to acquire a driver
identifier, specifying the cc_flags as an argument
(normally 0, but software-only drivers should specify
CRYPTOCAP_F_SOFTWARE
). For each algorithm the driver
supports, it must then call crypto_register
(). The
first argument is the driver identifier. The second argument is an array of
CRYPTO_ALGORITHM_MAX + 1
elements, indicating which
algorithms are supported. The last three arguments are pointers to three
driver-provided functions that the framework may call to establish new
cryptographic context with the driver, free already established context, and
ask for a request to be processed (encrypt, decrypt, etc.)
crypto_unregister
() is called by drivers that wish
to withdraw support for an algorithm. The two arguments are the driver and
algorithm identifiers, respectively. Typically, drivers for
pcmcia(4) crypto cards that are being
ejected will invoke this routine for all algorithms supported by the card.
If called with CRYPTO_ALGORITHM_ALL
, all algorithms
registered for a driver will be unregistered in one go and the driver will
be disabled (no new sessions will be allocated on that driver, and any
existing sessions will be migrated to other drivers). The same will be done
if all algorithms associated with a driver are unregistered one by one.
The calling convention for the three driver-supplied routines is:
int (*newsession) (u_int32_t *, struct cryptoini *); int (*freesession) (u_int64_t); int (*process) (struct cryptop *);
On invocation, the first argument to
newsession
() contains the driver identifier obtained
via crypto_get_driverid
(). On successfully
returning, it should contain a driver-specific session identifier. The
second argument is identical to that of
crypto_newsession
().
The freesession
() routine takes as
argument the SID (which is the concatenation of the driver identifier and
the driver-specific session identifier). It should clear any context
associated with the session (clear hardware registers, memory, etc.).
The process
() routine is invoked with a
request to perform crypto processing. This routine must not block, but
should queue the request and return immediately. Upon processing the
request, the callback routine should be invoked. In case of error, the error
indication must be placed in the crp_etype field of
the cryptop structure. When the request is completed,
or an error is detected, the process
() routine
should invoke crypto_done
(). Session migration may
be performed, as mentioned previously.
crypto_register
(),
crypto_unregister
(),
crypto_newsession
(), and
crypto_freesession
() return 0 on success, or an
error code on failure. crypto_get_driverid
() returns
a non-negative value on error, and -1 on failure.
crypto_getreq
() returns a pointer to a
cryptop structure and NULL
on
failure. crypto_dispatch
() returns
EINVAL
if its argument or the callback function was
NULL
, and 0 otherwise. The callback is provided with
an error code in case of failure, in the crp_etype
field.
The cryptographic framework first appeared in OpenBSD 2.7 and was written by Angelos D. Keromytis <angelos@openbsd.org>.
The framework currently assumes that all the algorithms in a
crypto_newsession
() operation must be available by
the same driver. If that's not the case, session initialization will
fail.
The framework also needs a mechanism for determining which driver is best for a specific set of algorithms associated with a session. Some type of benchmarking is in order here.
Multiple instances of the same algorithm in the same session are not supported.
A queue for completed operations should be implemented and processed at some software spl(9) level, to avoid overall system latency issues, and potential kernel stack exhaustion while processing a callback.
December 10, 2015 | OpenBSD-current |