Page MenuHomeFreeBSD
Differential D22784 Diff 65761 head/share/man/man9/crypto.9

Changeset View

Standalone View

View Options

head/share/man/man9/crypto.9

Show All 20 Lines
.Dt CRYPTO 9 .Dt CRYPTO 9
.Os .Os
.Sh NAME .Sh NAME
.Nm crypto .Nm crypto
.Nd API for cryptographic services in the kernel .Nd API for cryptographic services in the kernel
.Sh SYNOPSIS .Sh SYNOPSIS
.In opencrypto/cryptodev.h .In opencrypto/cryptodev.h
.Ft int32_t .Ft int32_t
.Fn crypto_get_driverid device_t size_t int .Fn crypto_get_driverid "device_t dev" "size_t session_size" "int flags"
.Ft 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 *" .Fn crypto_register "uint32_t driverid" "int alg" "uint16_t maxoplen" "uint32_t flags"
.Ft int .Ft int
.Fn crypto_kregister uint32_t int uint32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *" .Fn crypto_kregister "uint32_t driverid" "int kalg" "uint32_t flags"
.Ft int .Ft int
.Fn crypto_unregister uint32_t int .Fn crypto_unregister "uint32_t driverid" "int alg"
.Ft int .Ft int
.Fn crypto_unregister_all uint32_t .Fn crypto_unregister_all "uint32_t driverid"
.Ft void .Ft void
.Fn crypto_done "struct cryptop *" .Fn crypto_done "struct cryptop *crp"
.Ft void .Ft void
.Fn crypto_kdone "struct cryptkop *" .Fn crypto_kdone "struct cryptkop *krp"
.Ft int .Ft int
.Fn crypto_find_driver "const char *" .Fn crypto_find_driver "const char *match"
.Ft int .Ft int
.Fn crypto_newsession "crypto_session_t *" "struct cryptoini *" int .Fn crypto_newsession "crypto_session_t *cses" "struct cryptoini *cri" "int crid"
.Ft int .Ft int
.Fn crypto_freesession crypto_session_t .Fn crypto_freesession "crypto_session_t cses"
.Ft int .Ft int
.Fn crypto_dispatch "struct cryptop *" .Fn crypto_dispatch "struct cryptop *crp"
.Ft int .Ft int
.Fn crypto_kdispatch "struct cryptkop *" .Fn crypto_kdispatch "struct cryptkop *krp"
.Ft int .Ft int
.Fn crypto_unblock uint32_t int .Fn crypto_unblock "uint32_t driverid" "int what"
.Ft "struct cryptop *" .Ft "struct cryptop *"
.Fn crypto_getreq int .Fn crypto_getreq "int num"
.Ft void .Ft void
.Fn crypto_freereq void .Fn crypto_freereq "struct cryptop *crp"
.Bd -literal .Bd -literal
#define CRYPTO_SYMQ 0x1 #define CRYPTO_SYMQ 0x1
#define CRYPTO_ASYMQ 0x2 #define CRYPTO_ASYMQ 0x2
#define EALG_MAX_BLOCK_LEN 16 #define EALG_MAX_BLOCK_LEN 16
struct cryptoini { struct cryptoini {
int cri_alg; int cri_alg;
▲ Show 20 Lines • Show All 89 Lines • ▼ Show 20 Lines
request may be re-submitted immediately with the new session. request may be re-submitted immediately with the new session.
Errors are only returned to the invoking function if not Errors are only returned to the invoking function if not
enough information to call the callback is available (meaning, there enough information to call the callback is available (meaning, there
was a fatal error in verifying the arguments). was a fatal error in verifying the arguments).
For session initialization and teardown no callback mechanism is used. For session initialization and teardown no callback mechanism is used.
.Pp .Pp
The The
.Fn crypto_find_driver .Fn crypto_find_driver
function may be called to return the specific id of the provided name. returns the driver id of the device whose name matches
If the specified driver could not be found, the returned id is -1. .Fa match .
.Fa match
can either be the exact name of a device including the unit
or the driver name without a unit.
In the latter case,
the id of the first device with the matching driver name is returned.
If no matching device is found,
the value -1 is returned.
.Pp .Pp
The The
.Fn crypto_newsession .Fn crypto_newsession
routine is called by consumers of cryptographic services (such as the routine is called by consumers of cryptographic services (such as the
.Xr ipsec 4 .Xr ipsec 4
stack) that wish to establish a new session with the framework. stack) that wish to establish a new session with the framework.
The second argument contains all the necessary information for The
.Fa cri
argument points to a
.Vt cryptoini
structure containing all the necessary information for
the driver to establish the session. the driver to establish the session.
The third argument is either a specific driver id, or one or both The
of .Fa crid
argument is either a specific driver id or a bitmask of flags.
The flags are
.Dv CRYPTOCAP_F_HARDWARE , .Dv CRYPTOCAP_F_HARDWARE ,
to select hardware devices, to select hardware devices,
or or
.Dv CRYPTOCAP_F_SOFTWARE , .Dv CRYPTOCAP_F_SOFTWARE ,
to select software devices. to select software devices.
If both are specified, a hardware device will be returned If both are specified, hardware devices are preferred over software
before a software device will be. devices.
On success, the value pointed to by the first argument will be the opaque On success, the opaque session handle of the new session will be stored in
session handle. .Fa *cses .
The various fields in the The
.Vt cryptoini .Vt cryptoini
structure are: structure pointed to by
.Fa cri
contains these fields:
.Bl -tag -width ".Va cri_next" .Bl -tag -width ".Va cri_next"
.It Va cri_alg .It Va cri_alg
Contains an algorithm identifier. An algorithm identifier.
Currently supported algorithms are: Currently supported algorithms are:
.Pp .Pp
.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact .Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
.It Dv CRYPTO_AES_128_NIST_GMAC .It Dv CRYPTO_AES_128_NIST_GMAC
.It Dv CRYPTO_AES_192_NIST_GMAC .It Dv CRYPTO_AES_192_NIST_GMAC
.It Dv CRYPTO_AES_256_NIST_GMAC .It Dv CRYPTO_AES_256_NIST_GMAC
.It Dv CRYPTO_AES_CBC .It Dv CRYPTO_AES_CBC
.It Dv CRYPTO_AES_CCM_16
.It Dv CRYPTO_AES_CCM_CBC_MAC
.It Dv CRYPTO_AES_ICM .It Dv CRYPTO_AES_ICM
.It Dv CRYPTO_AES_NIST_GCM_16 .It Dv CRYPTO_AES_NIST_GCM_16
.It Dv CRYPTO_AES_NIST_GMAC .It Dv CRYPTO_AES_NIST_GMAC
.It Dv CRYPTO_AES_XTS .It Dv CRYPTO_AES_XTS
.It Dv CRYPTO_ARC4 .It Dv CRYPTO_ARC4
.It Dv CRYPTO_BLAKE2B
.It Dv CRYPTO_BLAKE2S
.It Dv CRYPTO_BLF_CBC .It Dv CRYPTO_BLF_CBC
.It Dv CRYPTO_CAMELLIA_CBC .It Dv CRYPTO_CAMELLIA_CBC
.It Dv CRYPTO_CAST_CBC .It Dv CRYPTO_CAST_CBC
.It Dv CRYPTO_CHACHA20
.It Dv CRYPTO_DEFLATE_COMP .It Dv CRYPTO_DEFLATE_COMP
.It Dv CRYPTO_DES_CBC .It Dv CRYPTO_DES_CBC
.It Dv CRYPTO_3DES_CBC .It Dv CRYPTO_3DES_CBC
.It Dv CRYPTO_MD5 .It Dv CRYPTO_MD5
.It Dv CRYPTO_MD5_HMAC .It Dv CRYPTO_MD5_HMAC
.It Dv CRYPTO_MD5_KPDK .It Dv CRYPTO_MD5_KPDK
.It Dv CRYPTO_NULL_HMAC .It Dv CRYPTO_NULL_HMAC
.It Dv CRYPTO_NULL_CBC .It Dv CRYPTO_NULL_CBC
.It Dv CRYPTO_POLY1305
.It Dv CRYPTO_RIPEMD160
.It Dv CRYPTO_RIPEMD160_HMAC .It Dv CRYPTO_RIPEMD160_HMAC
.It Dv CRYPTO_SHA1 .It Dv CRYPTO_SHA1
.It Dv CRYPTO_SHA1_HMAC .It Dv CRYPTO_SHA1_HMAC
.It Dv CRYPTO_SHA1_KPDK .It Dv CRYPTO_SHA1_KPDK
.It Dv CRYPTO_SHA2_224
.It Dv CRYPTO_SHA2_224_HMAC
.It Dv CRYPTO_SHA2_256
.It Dv CRYPTO_SHA2_256_HMAC .It Dv CRYPTO_SHA2_256_HMAC
.It Dv CRYPTO_SHA2_384
.It Dv CRYPTO_SHA2_384_HMAC .It Dv CRYPTO_SHA2_384_HMAC
.It Dv CRYPTO_SHA2_512
.It Dv CRYPTO_SHA2_512_HMAC .It Dv CRYPTO_SHA2_512_HMAC
.It Dv CRYPTO_SKIPJACK_CBC .It Dv CRYPTO_SKIPJACK_CBC
.El .El
.It Va cri_klen .It Va cri_klen
Specifies the length of the key in bits, for variable-size key For variable-size key algorithms, the length of the key in bits.
algorithms.
.It Va cri_mlen .It Va cri_mlen
Specifies how many bytes from the calculated hash should be copied back. If non-zero, truncate the calculated hash to this many bytes.
0 means entire hash.
.It Va cri_key .It Va cri_key
Contains the key to be used with the algorithm. The key to be used.
.It Va cri_iv .It Va cri_iv
Contains an explicit initialization vector (IV), if it does not prefix An explicit initialization vector if it does not prefix
the data. the data.
This field is ignored during initialization This field is ignored during initialization
.Pq Nm crypto_newsession . .Pq Nm crypto_newsession .
If no IV is explicitly passed (see below on details), a random IV is used If no IV is explicitly passed (see below on details), a random IV is used
by the device driver processing the request. by the device driver processing the request.
.It Va cri_next .It Va cri_next
Contains a pointer to another Pointer to another
.Vt cryptoini .Vt cryptoini
structure. structure.
Multiple such structures may be linked to establish multi-algorithm sessions This is used to establish dual-algorithm sessions, such as combining a
.Xr ( ipsec 4 cipher with a MAC.
is an example consumer of such a feature).
.El .El
.Pp .Pp
The The
.Vt cryptoini .Vt cryptoini
structure and its contents will not be modified by the framework (or structure and its contents will not be modified or referenced by the
the drivers used). framework or any cryptographic drivers.
The memory associated with
.Fa cri
can be released once
.Fn crypto_newsession
returns.
.Pp .Pp
.Fn crypto_freesession .Fn crypto_freesession
is called with the session handle returned by is called with the session handle returned by
.Fn crypto_newsession .Fn crypto_newsession
to free the session. to free the session.
.Pp .Pp
.Fn crypto_dispatch .Fn crypto_dispatch
is called to process a request. is called to process a request.
The various fields in the The various fields in the
.Vt cryptop .Vt cryptop
structure are: structure are:
.Bl -tag -width ".Va crp_callback" .Bl -tag -width ".Va crp_callback"
.It Va crp_session .It Va crp_session
Contains the session handle. The session handle.
.It Va crp_ilen .It Va crp_ilen
Indicates the total length in bytes of the buffer to be processed. The total length in bytes of the buffer to be processed.
.It Va crp_olen .It Va crp_olen
On return, contains the total length of the result. On return, contains the total length of the result.
For symmetric crypto operations, this will be the same as the input length. 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 This will be used if the framework needs to allocate a new
buffer for the result (or for re-formatting the input). buffer for the result (or for re-formatting the input).
.It Va crp_callback .It Va crp_callback
This routine is invoked upon completion of the request, whether Callback routine invoked when a request is completed via
successful or not. .Fn crypto_done .
It is invoked through the The callback routine should inspect the
.Fn crypto_done
routine.
If the request was not successful, an error code is set in the
.Va crp_etype .Va crp_etype
field. to determine if the request was successfully completed.
It is the responsibility of the callback routine to set the appropriate
.Xr spl 9
level.
.It Va crp_etype .It Va crp_etype
Contains the error type, if any errors were encountered, or zero if The error type, if any errors were encountered, or zero if
the request was successfully processed. the request was successfully processed.
If the If the
.Er EAGAIN .Er EAGAIN
error code is returned, the session handle has changed (and has been recorded error code is returned, the session handle has changed (and has been recorded
in the in the
.Va crp_session .Va crp_session
field). field).
The consumer should record the new session handle and use it in all subsequent The consumer should record the new session handle and use it in all subsequent
requests. requests.
In this case, the request may be re-submitted immediately. In this case, the request may be re-submitted immediately.
This mechanism is used by the framework to perform This mechanism is used by the framework to perform
session migration (move a session from one driver to another, because session migration (move a session from one driver to another, because
of availability, performance, or other considerations). of availability, performance, or other considerations).
.Pp .Pp
Note that this field only makes sense when examined by This field is only valid in the context of the callback routine specified by
the callback routine specified in
.Va crp_callback . .Va crp_callback .
Errors are returned to the invoker of Errors are returned to the invoker of
.Fn crypto_process .Fn crypto_process
only when enough information is not present to call the callback only when enough information is not present to call the callback
routine (i.e., if the pointer passed is routine (i.e., if the pointer passed is
.Dv NULL .Dv NULL
or if no callback routine was specified). or if no callback routine was specified).
.It Va crp_flags .It Va crp_flags
Is a bitmask of flags associated with this request. A bitmask of flags associated with this request.
Currently defined flags are: Currently defined flags are:
.Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC" .Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC"
.It Dv CRYPTO_F_IMBUF .It Dv CRYPTO_F_IMBUF
The buffer pointed to by The buffer is an mbuf chain pointed to by
.Va crp_buf .Va crp_mbuf .
is an mbuf chain.
.It Dv CRYPTO_F_IOV .It Dv CRYPTO_F_IOV
The buffer pointed to by The buffer is a
.Va crp_buf
is an
.Vt uio .Vt uio
structure. structure pointed to by
.Va crp_uio .
.It Dv CRYPTO_F_BATCH .It Dv CRYPTO_F_BATCH
Batch operation if possible. Batch operation if possible.
.It Dv CRYPTO_F_CBIMM .It Dv CRYPTO_F_CBIMM
Do callback immediately instead of doing it from a dedicated kernel thread. Do callback immediately instead of doing it from a dedicated kernel thread.
.It Dv CRYPTO_F_DONE .It Dv CRYPTO_F_DONE
Operation completed. Operation completed.
.It Dv CRYPTO_F_CBIFSYNC .It Dv CRYPTO_F_CBIFSYNC
Do callback immediately if operation is synchronous (that the driver Do callback immediately if operation is synchronous (that the driver
Show All 9 Lines
on different processors. on different processors.
.It Dv CRYPTO_F_ASYNC_KEEPORDER .It Dv CRYPTO_F_ASYNC_KEEPORDER
Dispatch callbacks in the same order they are posted. Dispatch callbacks in the same order they are posted.
Only relevant if the Only relevant if the
.Dv CRYPTO_F_ASYNC .Dv CRYPTO_F_ASYNC
flag is set and if the operation is synchronous. flag is set and if the operation is synchronous.
.El .El
.It Va crp_buf .It Va crp_buf
Points to the input buffer. Data buffer unless
On return (when the callback is invoked), .Dv CRYPTO_F_IMBUF
it contains the result of the request. or
The input buffer may be an mbuf .Dv CRYPTO_F_IOV
chain or a contiguous buffer, is set in
depending on
.Va crp_flags . .Va crp_flags .
The length in bytes is set in
.Va crp_ilen .
.It Va crp_mbuf
Data buffer mbuf chain when
.Dv CRYPTO_F_IMBUF
is set in
.Va crp_flags .
.It Va crp_uio
.Vt struct uio
data buffer when
.Dv CRYPTO_F_IOV
is set in
.Va crp_flags .
.It Va crp_opaque .It Va crp_opaque
This is passed through the crypto framework untouched and is Cookie passed through the crypto framework untouched.
It is
intended for the invoking application's use. intended for the invoking application's use.
.It Va crp_desc .It Va crp_desc
This is a linked list of descriptors. A linked list of descriptors.
Each descriptor provides Each descriptor provides
information about what type of cryptographic operation should be done information about what type of cryptographic operation should be done
on the input buffer. on the input buffer.
The various fields are: The various fields are:
.Bl -tag -width ".Va crd_inject" .Bl -tag -width ".Va crd_inject"
.It Va crd_iv .It Va crd_iv
When the flag When the flag
.Dv CRD_F_IV_EXPLICIT .Dv CRD_F_IV_EXPLICIT
▲ Show 20 Lines • Show All 57 Lines • ▼ Show 20 Lines
field. field.
Otherwise, for encryption operations the IV is provided for by Otherwise, for encryption operations the IV is provided for by
the driver used to perform the operation, whereas for decryption the driver used to perform the operation, whereas for decryption
operations the offset of the IV is provided by the operations the offset of the IV is provided by the
.Va crd_inject .Va crd_inject
field. field.
This flag is typically used when the IV is calculated This flag is typically used when the IV is calculated
.Dq "on the fly" .Dq "on the fly"
by the consumer, and does not precede the data (some by the consumer, and does not precede the data.
.Xr ipsec 4
configurations, and the encrypted swap are two such examples).
.It Dv CRD_F_KEY_EXPLICIT .It Dv CRD_F_KEY_EXPLICIT
For encryption and authentication (MAC) algorithms, this bit is set when the key For encryption and authentication (MAC) algorithms, this bit is set when the key
is explicitly provided by the consumer in the is explicitly provided by the consumer in the
.Va crd_key .Va crd_key
field for the given operation. field for the given operation.
Otherwise, the key is taken at newsession time from the Otherwise, the key is taken at newsession time from the
.Va cri_key .Va cri_key
field. field.
Show All 20 Lines
where multiple cryptographic transforms may be applied on the same where multiple cryptographic transforms may be applied on the same
block of data. block of data.
.El .El
.El .El
.Pp .Pp
.Fn crypto_getreq .Fn crypto_getreq
allocates a allocates a
.Vt cryptop .Vt cryptop
structure with a linked list of as many structure with a linked list of
.Fa num
.Vt cryptodesc .Vt cryptodesc
structures as were specified in the argument passed to it. structures.
.Pp .Pp
.Fn crypto_freereq .Fn crypto_freereq
deallocates a structure deallocates a structure
.Vt cryptop .Vt cryptop
and any and any
.Vt cryptodesc .Vt cryptodesc
structures linked to it. structures linked to it.
Note that it is the responsibility of the Note that it is the responsibility of the
Show All 13 Lines
.Dv CRK_MOD_EXP . .Dv CRK_MOD_EXP .
.It Va krp_status .It Va krp_status
Return code. Return code.
This This
.Va errno Ns -style .Va errno Ns -style
variable indicates whether lower level reasons variable indicates whether lower level reasons
for operation failure. for operation failure.
.It Va krp_iparams .It Va krp_iparams
Number if input parameters to the specified operation. Number of input parameters to the specified operation.
Note that each operation has a (typically hardwired) number of such parameters. Note that each operation has a (typically hardwired) number of such parameters.
.It Va krp_oparams .It Va krp_oparams
Number if output parameters from the specified operation. Number of output parameters from the specified operation.
Note that each operation has a (typically hardwired) number of such parameters. Note that each operation has a (typically hardwired) number of such parameters.
.It Va krp_kvp .It Va krp_kvp
An array of kernel memory blocks containing the parameters. An array of kernel memory blocks containing the parameters.
.It Va krp_hid .It Va krp_hid
Identifier specifying which low-level driver is being used. Identifier specifying which low-level driver is being used.
.It Va krp_callback .It Va krp_callback
Callback called on completion of a keying operation. Callback called on completion of a keying operation.
.El .El
Show All 20 Lines
.Dv CRYPTOCAP_F_SOFTWARE .Dv CRYPTOCAP_F_SOFTWARE
or or
.Dv CRYPTOCAP_F_HARDWARE .Dv CRYPTOCAP_F_HARDWARE
must be specified. must be specified.
The The
.Dv CRYPTOCAP_F_SYNC .Dv CRYPTOCAP_F_SYNC
may also be specified, and should be specified if the driver does all of may also be specified, and should be specified if the driver does all of
it's operations synchronously. it's operations synchronously.
Drivers must pass the size of their session struct as the second argument. Drivers must pass the size of their session structure as the second argument.
An appropriately sized memory will be allocated by the framework, zeroed, and An appropriately sized memory will be allocated by the framework, zeroed, and
passed to the driver's passed to the driver's
.Fn newsession .Fn newsession
method. method.
.Pp .Pp
For each algorithm the driver supports, it must then call For each algorithm the driver supports, it must then call
.Fn crypto_register . .Fn crypto_register .
The first two arguments are the driver and algorithm identifiers. The first two arguments are the driver and algorithm identifiers.
The next two arguments specify the largest possible operator length (in bits, The next two arguments specify the largest possible operator length (in bits,
important for public key operations) and flags for this algorithm. 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 .Pp
.Fn crypto_unregister .Fn crypto_unregister
is called by drivers that wish to withdraw support for an algorithm. is called by drivers that wish to withdraw support for an algorithm.
The two arguments are the driver and algorithm identifiers, respectively. The two arguments are the driver and algorithm identifiers, respectively.
Typically, drivers for Typically, drivers for
PCMCIA PCMCIA
crypto cards that are being ejected will invoke this routine for all crypto cards that are being ejected will invoke this routine for all
algorithms supported by the card. algorithms supported by the card.
▲ Show 20 Lines • Show All 163 Lines • Show Last 20 Lines