711 lines
22 KiB
Groff
711 lines
22 KiB
Groff
.\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $
|
|
.\"
|
|
.\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu)
|
|
.\"
|
|
.\" Copyright (c) 2000, 2001 Angelos D. Keromytis
|
|
.\"
|
|
.\" Permission to use, copy, and modify this software with or without fee
|
|
.\" is hereby granted, provided that this entire notice is included in
|
|
.\" all source code copies of any software which is or includes a copy or
|
|
.\" modification of this software.
|
|
.\"
|
|
.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY
|
|
.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE
|
|
.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR
|
|
.\" PURPOSE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd July 10, 2015
|
|
.Dt CRYPTO 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm crypto
|
|
.Nd API for cryptographic services in the kernel
|
|
.Sh SYNOPSIS
|
|
.In opencrypto/cryptodev.h
|
|
.Ft int32_t
|
|
.Fn crypto_get_driverid device_t int
|
|
.Ft int
|
|
.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 *"
|
|
.Ft int
|
|
.Fn crypto_kregister uint32_t int uint32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *"
|
|
.Ft int
|
|
.Fn crypto_unregister uint32_t int
|
|
.Ft int
|
|
.Fn crypto_unregister_all uint32_t
|
|
.Ft void
|
|
.Fn crypto_done "struct cryptop *"
|
|
.Ft void
|
|
.Fn crypto_kdone "struct cryptkop *"
|
|
.Ft int
|
|
.Fn crypto_find_driver "const char *"
|
|
.Ft int
|
|
.Fn crypto_newsession "uint64_t *" "struct cryptoini *" int
|
|
.Ft int
|
|
.Fn crypto_freesession uint64_t
|
|
.Ft int
|
|
.Fn crypto_dispatch "struct cryptop *"
|
|
.Ft int
|
|
.Fn crypto_kdispatch "struct cryptkop *"
|
|
.Ft int
|
|
.Fn crypto_unblock uint32_t int
|
|
.Ft "struct cryptop *"
|
|
.Fn crypto_getreq int
|
|
.Ft void
|
|
.Fn crypto_freereq void
|
|
.Bd -literal
|
|
#define CRYPTO_SYMQ 0x1
|
|
#define CRYPTO_ASYMQ 0x2
|
|
|
|
#define EALG_MAX_BLOCK_LEN 16
|
|
|
|
struct cryptoini {
|
|
int cri_alg;
|
|
int cri_klen;
|
|
int cri_mlen;
|
|
caddr_t cri_key;
|
|
uint8_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;
|
|
#define crd_iv CRD_INI.cri_iv
|
|
#define crd_key CRD_INI.cri_key
|
|
#define crd_alg CRD_INI.cri_alg
|
|
#define crd_klen CRD_INI.cri_klen
|
|
struct cryptodesc *crd_next;
|
|
};
|
|
|
|
struct cryptop {
|
|
TAILQ_ENTRY(cryptop) crp_next;
|
|
uint64_t crp_sid;
|
|
int crp_ilen;
|
|
int crp_olen;
|
|
int crp_etype;
|
|
int crp_flags;
|
|
caddr_t crp_buf;
|
|
caddr_t crp_opaque;
|
|
struct cryptodesc *crp_desc;
|
|
int (*crp_callback) (struct cryptop *);
|
|
caddr_t crp_mac;
|
|
};
|
|
|
|
struct crparam {
|
|
caddr_t crp_p;
|
|
u_int crp_nbits;
|
|
};
|
|
|
|
#define CRK_MAXPARAM 8
|
|
|
|
struct cryptkop {
|
|
TAILQ_ENTRY(cryptkop) krp_next;
|
|
u_int krp_op; /* ie. CRK_MOD_EXP or other */
|
|
u_int krp_status; /* return status */
|
|
u_short krp_iparams; /* # of input parameters */
|
|
u_short krp_oparams; /* # of output parameters */
|
|
uint32_t krp_hid;
|
|
struct crparam krp_param[CRK_MAXPARAM];
|
|
int (*krp_callback)(struct cryptkop *);
|
|
};
|
|
.Ed
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
is a framework for drivers of cryptographic hardware to register with
|
|
the kernel so
|
|
.Dq consumers
|
|
(other kernel subsystems, and
|
|
users through the
|
|
.Pa /dev/crypto
|
|
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).
|
|
.Pp
|
|
Keying operations are supported as well.
|
|
Unlike the symmetric operators described above,
|
|
these sessionless commands perform mathematical operations using
|
|
input and output parameters.
|
|
.Pp
|
|
Since the consumers may not be associated with a process, drivers may
|
|
not
|
|
.Xr sleep 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,
|
|
.Er 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.
|
|
.Pp
|
|
The
|
|
.Fn crypto_find_driver
|
|
function may be called to return the specific id of the provided name.
|
|
If the specified driver could not be found, the returned id is -1.
|
|
.Pp
|
|
The
|
|
.Fn crypto_newsession
|
|
routine is called by consumers of cryptographic services (such as the
|
|
.Xr ipsec 4
|
|
stack) that wish to establish a new session with the framework.
|
|
The second argument contains all the necessary information for
|
|
the driver to establish the session.
|
|
The third argument is either a specific driver id, or one or both
|
|
of
|
|
.Dv CRYPTOCAP_F_HARDWARE ,
|
|
to select hardware devices,
|
|
or
|
|
.Dv CRYPTOCAP_F_SOFTWARE ,
|
|
to select software devices.
|
|
If both are specified, a hardware device will be returned
|
|
before a software device will be.
|
|
On success, the value pointed to by the first argument will be the
|
|
Session IDentifier (SID).
|
|
The various fields in the
|
|
.Vt cryptoini
|
|
structure are:
|
|
.Bl -tag -width ".Va cri_next"
|
|
.It Va cri_alg
|
|
Contains an algorithm identifier.
|
|
Currently supported algorithms are:
|
|
.Pp
|
|
.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
|
|
.It Dv CRYPTO_AES_128_NIST_GMAC
|
|
.It Dv CRYPTO_AES_192_NIST_GMAC
|
|
.It Dv CRYPTO_AES_256_NIST_GMAC
|
|
.It Dv CRYPTO_AES_CBC
|
|
.It Dv CRYPTO_AES_ICM
|
|
.It Dv CRYPTO_AES_NIST_GCM_16
|
|
.It Dv CRYPTO_AES_NIST_GMAC
|
|
.It Dv CRYPTO_AES_XTS
|
|
.It Dv CRYPTO_ARC4
|
|
.It Dv CRYPTO_BLF_CBC
|
|
.It Dv CRYPTO_CAMELLIA_CBC
|
|
.It Dv CRYPTO_CAST_CBC
|
|
.It Dv CRYPTO_DEFLATE_COMP
|
|
.It Dv CRYPTO_DES_CBC
|
|
.It Dv CRYPTO_3DES_CBC
|
|
.It Dv CRYPTO_MD5
|
|
.It Dv CRYPTO_MD5_HMAC
|
|
.It Dv CRYPTO_MD5_KPDK
|
|
.It Dv CRYPTO_NULL_HMAC
|
|
.It Dv CRYPTO_NULL_CBC
|
|
.It Dv CRYPTO_RIPEMD160_HMAC
|
|
.It Dv CRYPTO_SHA1
|
|
.It Dv CRYPTO_SHA1_HMAC
|
|
.It Dv CRYPTO_SHA1_KPDK
|
|
.It Dv CRYPTO_SHA2_256_HMAC
|
|
.It Dv CRYPTO_SHA2_384_HMAC
|
|
.It Dv CRYPTO_SHA2_512_HMAC
|
|
.It Dv CRYPTO_SKIPJACK_CBC
|
|
.El
|
|
.It Va cri_klen
|
|
Specifies the length of the key in bits, for variable-size key
|
|
algorithms.
|
|
.It Va cri_mlen
|
|
Specifies how many bytes from the calculated hash should be copied back.
|
|
0 means entire hash.
|
|
.It Va cri_key
|
|
Contains the key to be used with the algorithm.
|
|
.It Va cri_iv
|
|
Contains an explicit initialization vector (IV), if it does not prefix
|
|
the data.
|
|
This field is ignored during initialization
|
|
.Pq Nm crypto_newsession .
|
|
If no IV is explicitly passed (see below on details), a random IV is used
|
|
by the device driver processing the request.
|
|
.It Va cri_next
|
|
Contains a pointer to another
|
|
.Vt cryptoini
|
|
structure.
|
|
Multiple such structures may be linked to establish multi-algorithm sessions
|
|
.Xr ( ipsec 4
|
|
is an example consumer of such a feature).
|
|
.El
|
|
.Pp
|
|
The
|
|
.Vt 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).
|
|
.Pp
|
|
.Fn crypto_freesession
|
|
is called with the SID returned by
|
|
.Fn crypto_newsession
|
|
to disestablish the session.
|
|
.Pp
|
|
.Fn crypto_dispatch
|
|
is called to process a request.
|
|
The various fields in the
|
|
.Vt cryptop
|
|
structure are:
|
|
.Bl -tag -width ".Va crp_callback"
|
|
.It Va crp_sid
|
|
Contains the SID.
|
|
.It Va crp_ilen
|
|
Indicates the total length in bytes of the buffer to be processed.
|
|
.It Va crp_olen
|
|
On return, contains the total length of the result.
|
|
For symmetric crypto operations, this will be the same as the input length.
|
|
This will be used if the framework needs to allocate a new
|
|
buffer for the result (or for re-formatting the input).
|
|
.It Va crp_callback
|
|
This routine is invoked upon completion of the request, whether
|
|
successful or not.
|
|
It is invoked through the
|
|
.Fn crypto_done
|
|
routine.
|
|
If the request was not successful, an error code is set in the
|
|
.Va crp_etype
|
|
field.
|
|
It is the responsibility of the callback routine to set the appropriate
|
|
.Xr spl 9
|
|
level.
|
|
.It Va crp_etype
|
|
Contains the error type, if any errors were encountered, or zero if
|
|
the request was successfully processed.
|
|
If the
|
|
.Er EAGAIN
|
|
error code is returned, the SID has changed (and has been recorded in the
|
|
.Va 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).
|
|
.Pp
|
|
Note that this field only makes sense when examined by
|
|
the callback routine specified in
|
|
.Va crp_callback .
|
|
Errors are returned to the invoker of
|
|
.Fn crypto_process
|
|
only when enough information is not present to call the callback
|
|
routine (i.e., if the pointer passed is
|
|
.Dv NULL
|
|
or if no callback routine was specified).
|
|
.It Va crp_flags
|
|
Is a bitmask of flags associated with this request.
|
|
Currently defined flags are:
|
|
.Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC"
|
|
.It Dv CRYPTO_F_IMBUF
|
|
The buffer pointed to by
|
|
.Va crp_buf
|
|
is an mbuf chain.
|
|
.It Dv CRYPTO_F_IOV
|
|
The buffer pointed to by
|
|
.Va crp_buf
|
|
is an
|
|
.Vt uio
|
|
structure.
|
|
.It Dv CRYPTO_F_BATCH
|
|
Batch operation if possible.
|
|
.It Dv CRYPTO_F_CBIMM
|
|
Do callback immediately instead of doing it from a dedicated kernel thread.
|
|
.It Dv CRYPTO_F_DONE
|
|
Operation completed.
|
|
.It Dv CRYPTO_F_CBIFSYNC
|
|
Do callback immediately if operation is synchronous (that the driver
|
|
specified the
|
|
.Dv CRYPTOCAP_F_SYNC
|
|
flag).
|
|
.El
|
|
.It Va crp_buf
|
|
Points to the input buffer.
|
|
On return (when the callback is invoked),
|
|
it contains the result of the request.
|
|
The input buffer may be an mbuf
|
|
chain or a contiguous buffer,
|
|
depending on
|
|
.Va crp_flags .
|
|
.It Va crp_opaque
|
|
This is passed through the crypto framework untouched and is
|
|
intended for the invoking application's use.
|
|
.It Va crp_desc
|
|
This is a linked list of descriptors.
|
|
Each descriptor provides
|
|
information about what type of cryptographic operation should be done
|
|
on the input buffer.
|
|
The various fields are:
|
|
.Bl -tag -width ".Va crd_inject"
|
|
.It Va crd_iv
|
|
When the flag
|
|
.Dv CRD_F_IV_EXPLICIT
|
|
is set, this field contains the IV.
|
|
.It Va crd_key
|
|
When the
|
|
.Dv CRD_F_KEY_EXPLICIT
|
|
flag is set, the
|
|
.Va crd_key
|
|
points to a buffer with encryption or authentication key.
|
|
.It Va crd_alg
|
|
An algorithm to use.
|
|
Must be the same as the one given at newsession time.
|
|
.It Va crd_klen
|
|
The
|
|
.Va crd_key
|
|
key length.
|
|
.It Va crd_skip
|
|
The offset in the input buffer where processing should start.
|
|
.It Va crd_len
|
|
How many bytes, after
|
|
.Va crd_skip ,
|
|
should be processed.
|
|
.It Va crd_inject
|
|
The
|
|
.Va crd_inject
|
|
field specifies an offset in bytes from the beginning of the buffer.
|
|
For encryption algorithms, this may be where the IV will be inserted
|
|
when encrypting or where the IV may be found for
|
|
decryption (subject to
|
|
.Va crd_flags ) .
|
|
For MAC algorithms, this is where the result of the keyed hash will be
|
|
inserted.
|
|
.It Va crd_flags
|
|
The following flags are defined:
|
|
.Bl -tag -width 3n
|
|
.It Dv CRD_F_ENCRYPT
|
|
For encryption algorithms, this bit is set when encryption is required
|
|
(when not set, decryption is performed).
|
|
.It Dv CRD_F_IV_PRESENT
|
|
.\" This flag name has nothing to do w/ it's behavior, fix the name.
|
|
For encryption, if this bit is not set the IV used to encrypt the packet
|
|
will be written at the location pointed to by
|
|
.Va crd_inject .
|
|
The IV length is assumed to be equal to the blocksize of the
|
|
encryption algorithm.
|
|
For encryption, if this bit is set, nothing is done.
|
|
For decryption, this flag has no meaning.
|
|
Applications that do special
|
|
.Dq "IV cooking" ,
|
|
such as the half-IV mode in
|
|
.Xr ipsec 4 ,
|
|
can use this flag to indicate that the IV should not be written on the packet.
|
|
This flag is typically used in conjunction with the
|
|
.Dv CRD_F_IV_EXPLICIT
|
|
flag.
|
|
.It Dv CRD_F_IV_EXPLICIT
|
|
This bit is set when the IV is explicitly
|
|
provided by the consumer in the
|
|
.Va crd_iv
|
|
field.
|
|
Otherwise, for encryption operations the IV is provided for by
|
|
the driver used to perform the operation, whereas for decryption
|
|
operations the offset of the IV is provided by the
|
|
.Va crd_inject
|
|
field.
|
|
This flag is typically used when the IV is calculated
|
|
.Dq "on the fly"
|
|
by the consumer, and does not precede the data (some
|
|
.Xr ipsec 4
|
|
configurations, and the encrypted swap are two such examples).
|
|
.It Dv CRD_F_KEY_EXPLICIT
|
|
For encryption and authentication (MAC) algorithms, this bit is set when the key
|
|
is explicitly provided by the consumer in the
|
|
.Va crd_key
|
|
field for the given operation.
|
|
Otherwise, the key is taken at newsession time from the
|
|
.Va cri_key
|
|
field.
|
|
As calculating the key schedule may take a while, it is recommended that often
|
|
used keys are given their own session.
|
|
.It Dv CRD_F_COMP
|
|
For compression algorithms, this bit is set when compression is required (when
|
|
not set, decompression is performed).
|
|
.El
|
|
.It Va CRD_INI
|
|
This
|
|
.Vt cryptoini
|
|
structure will not be modified by the framework or the device drivers.
|
|
Since this information accompanies every cryptographic
|
|
operation request, drivers may re-initialize state on-demand
|
|
(typically an expensive operation).
|
|
Furthermore, the cryptographic
|
|
framework may re-route requests as a result of full queues or hardware
|
|
failure, as described above.
|
|
.It Va crd_next
|
|
Point to the next descriptor.
|
|
Linked operations are useful in protocols such as
|
|
.Xr ipsec 4 ,
|
|
where multiple cryptographic transforms may be applied on the same
|
|
block of data.
|
|
.El
|
|
.El
|
|
.Pp
|
|
.Fn crypto_getreq
|
|
allocates a
|
|
.Vt cryptop
|
|
structure with a linked list of as many
|
|
.Vt cryptodesc
|
|
structures as were specified in the argument passed to it.
|
|
.Pp
|
|
.Fn crypto_freereq
|
|
deallocates a structure
|
|
.Vt cryptop
|
|
and any
|
|
.Vt 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
|
|
.Vt cryptop
|
|
structure.
|
|
.Pp
|
|
.Fn crypto_kdispatch
|
|
is called to perform a keying operation.
|
|
The various fields in the
|
|
.Vt cryptkop
|
|
structure are:
|
|
.Bl -tag -width ".Va krp_callback"
|
|
.It Va krp_op
|
|
Operation code, such as
|
|
.Dv CRK_MOD_EXP .
|
|
.It Va krp_status
|
|
Return code.
|
|
This
|
|
.Va errno Ns -style
|
|
variable indicates whether lower level reasons
|
|
for operation failure.
|
|
.It Va krp_iparams
|
|
Number if input parameters to the specified operation.
|
|
Note that each operation has a (typically hardwired) number of such parameters.
|
|
.It Va krp_oparams
|
|
Number if output parameters from the specified operation.
|
|
Note that each operation has a (typically hardwired) number of such parameters.
|
|
.It Va krp_kvp
|
|
An array of kernel memory blocks containing the parameters.
|
|
.It Va krp_hid
|
|
Identifier specifying which low-level driver is being used.
|
|
.It Va krp_callback
|
|
Callback called on completion of a keying operation.
|
|
.El
|
|
.Sh DRIVER-SIDE API
|
|
The
|
|
.Fn crypto_get_driverid ,
|
|
.Fn crypto_register ,
|
|
.Fn crypto_kregister ,
|
|
.Fn crypto_unregister ,
|
|
.Fn crypto_unblock ,
|
|
and
|
|
.Fn crypto_done
|
|
routines are used by drivers that provide support for cryptographic
|
|
primitives to register and unregister with the kernel crypto services
|
|
framework.
|
|
.Pp
|
|
Drivers must first use the
|
|
.Fn crypto_get_driverid
|
|
function to acquire a driver identifier, specifying the
|
|
.Fa flags
|
|
as an argument.
|
|
One of
|
|
.Dv CRYPTOCAP_F_SOFTWARE
|
|
or
|
|
.Dv CRYPTOCAP_F_HARDWARE
|
|
must be specified.
|
|
The
|
|
.Dv CRYPTOCAP_F_SYNC
|
|
may also be specified, and should be specified if the driver does all of
|
|
it's operations synchronously.
|
|
.Pp
|
|
For each algorithm the driver supports, it must then call
|
|
.Fn crypto_register .
|
|
The first two arguments are the driver and algorithm identifiers.
|
|
The next two arguments specify the largest possible operator length (in bits,
|
|
important for public key operations) and flags for this algorithm.
|
|
The last four arguments must be provided in the first call to
|
|
.Fn crypto_register
|
|
and are ignored in all subsequent calls.
|
|
They 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.); and an opaque parameter to pass when calling each of these routines.
|
|
.Pp
|
|
.Fn 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
|
|
crypto cards that are being ejected will invoke this routine for all
|
|
algorithms supported by the card.
|
|
.Fn crypto_unregister_all
|
|
will unregister all algorithms registered by a driver
|
|
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.
|
|
After a call to
|
|
.Fn crypto_unregister_all
|
|
there will be no threads in either the newsession or freesession function
|
|
of the driver.
|
|
.Pp
|
|
The calling convention for the three driver-supplied routines are:
|
|
.Pp
|
|
.Bl -item -compact
|
|
.It
|
|
.Ft int
|
|
.Fn \*[lp]*newsession\*[rp] "device_t" "uint32_t *" "struct cryptoini *" ;
|
|
.It
|
|
.Ft int
|
|
.Fn \*[lp]*freesession\*[rp] "device_t" "uint64_t" ;
|
|
.It
|
|
.Ft int
|
|
.Fn \*[lp]*process\*[rp] "device_t" "struct cryptop *" "int" ;
|
|
.It
|
|
.Ft int
|
|
.Fn \*[lp]*kprocess\*[rp] "device_t" "struct cryptkop *" "int" ;
|
|
.El
|
|
.Pp
|
|
On invocation, the first argument to
|
|
all routines is the
|
|
.Fa device_t
|
|
that was provided to
|
|
.Fn crypto_get_driverid .
|
|
The second argument to
|
|
.Fn newsession
|
|
contains the driver identifier obtained via
|
|
.Fn crypto_get_driverid .
|
|
On successful return, it should contain a driver-specific session
|
|
identifier.
|
|
The third argument is identical to that of
|
|
.Fn crypto_newsession .
|
|
.Pp
|
|
The
|
|
.Fn freesession
|
|
routine takes as arguments the opaque data value and 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.).
|
|
.Pp
|
|
The
|
|
.Fn process
|
|
routine is invoked with a request to perform crypto processing.
|
|
This routine must not block or sleep, but should queue the request and return
|
|
immediately or process the request to completion.
|
|
In case of an unrecoverable error, the error indication must be placed in the
|
|
.Va crp_etype
|
|
field of the
|
|
.Vt cryptop
|
|
structure.
|
|
When the request is completed, or an error is detected, the
|
|
.Fn process
|
|
routine must invoke
|
|
.Fn crypto_done .
|
|
Session migration may be performed, as mentioned previously.
|
|
.Pp
|
|
In case of a temporary resource exhaustion, the
|
|
.Fn process
|
|
routine may return
|
|
.Er ERESTART
|
|
in which case the crypto services will requeue the request, mark the driver
|
|
as
|
|
.Dq blocked ,
|
|
and stop submitting requests for processing.
|
|
The driver is then responsible for notifying the crypto services
|
|
when it is again able to process requests through the
|
|
.Fn crypto_unblock
|
|
routine.
|
|
This simple flow control mechanism should only be used for short-lived
|
|
resource exhaustion as it causes operations to be queued in the crypto
|
|
layer.
|
|
Doing so is preferable to returning an error in such cases as
|
|
it can cause network protocols to degrade performance by treating the
|
|
failure much like a lost packet.
|
|
.Pp
|
|
The
|
|
.Fn kprocess
|
|
routine is invoked with a request to perform crypto key 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 an unrecoverable error, the error indication must be placed in the
|
|
.Va krp_status
|
|
field of the
|
|
.Vt cryptkop
|
|
structure.
|
|
When the request is completed, or an error is detected, the
|
|
.Fn kprocess
|
|
routine should invoked
|
|
.Fn crypto_kdone .
|
|
.Sh RETURN VALUES
|
|
.Fn crypto_register ,
|
|
.Fn crypto_kregister ,
|
|
.Fn crypto_unregister ,
|
|
.Fn crypto_newsession ,
|
|
.Fn crypto_freesession ,
|
|
and
|
|
.Fn crypto_unblock
|
|
return 0 on success, or an error code on failure.
|
|
.Fn crypto_get_driverid
|
|
returns a non-negative value on error, and \-1 on failure.
|
|
.Fn crypto_getreq
|
|
returns a pointer to a
|
|
.Vt cryptop
|
|
structure and
|
|
.Dv NULL
|
|
on failure.
|
|
.Fn crypto_dispatch
|
|
returns
|
|
.Er EINVAL
|
|
if its argument or the callback function was
|
|
.Dv NULL ,
|
|
and 0 otherwise.
|
|
The callback is provided with an error code in case of failure, in the
|
|
.Va crp_etype
|
|
field.
|
|
.Sh FILES
|
|
.Bl -tag -width ".Pa sys/opencrypto/crypto.c"
|
|
.It Pa sys/opencrypto/crypto.c
|
|
most of the framework code
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr crypto 4 ,
|
|
.Xr ipsec 4 ,
|
|
.Xr crypto 7 ,
|
|
.Xr malloc 9 ,
|
|
.Xr sleep 9
|
|
.Sh HISTORY
|
|
The cryptographic framework first appeared in
|
|
.Ox 2.7
|
|
and was written by
|
|
.An Angelos D. Keromytis Aq Mt angelos@openbsd.org .
|
|
.Sh BUGS
|
|
The framework currently assumes that all the algorithms in a
|
|
.Fn crypto_newsession
|
|
operation must be available by the same driver.
|
|
If that is not the case, session initialization will fail.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
Multiple instances of the same algorithm in the same session are not
|
|
supported.
|
|
Note that 3DES is considered one algorithm (and not three
|
|
instances of DES).
|
|
Thus, 3DES and DES could be mixed in the same request.
|