svn commit: r356871 - in stable/12/share/man: man4 man9
John Baldwin
jhb at FreeBSD.org
Sat Jan 18 23:30:43 UTC 2020
Author: jhb
Date: Sat Jan 18 23:30:42 2020
New Revision: 356871
URL: https://svnweb.freebsd.org/changeset/base/356871
Log:
MFC 355866,355871: Update the crypto(4) and crypto(9) manpages.
355866:
Update the crypto(4) and crypto(9) manpages.
There are probably bits that are still wrong, but this fixes some
things at least:
- Add named arguments to the functions in crypto(9).
- Add missing algorithms.
- Don't mention arguments that don't exist in crypto_register.
- Add CIOGSESSION2.
- Remove CIOCNFSESSION.
- Clarify some stale language that assumed an fd had only one sesson.
- Note that you have to use CRIOGET and add a note in BUGS lamenting
that one has to use CRIOGET.
- Various other cleanups.
355871:
Bump Dd for changes in r355866.
Sponsored by: Chelsio Communications
Modified:
stable/12/share/man/man4/crypto.4
stable/12/share/man/man9/crypto.9
Directory Properties:
stable/12/ (props changed)
Modified: stable/12/share/man/man4/crypto.4
==============================================================================
--- stable/12/share/man/man4/crypto.4 Sat Jan 18 23:26:15 2020 (r356870)
+++ stable/12/share/man/man4/crypto.4 Sat Jan 18 23:30:42 2020 (r356871)
@@ -60,7 +60,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd September 21, 2017
+.Dd December 17, 2019
.Dt CRYPTO 4
.Os
.Sh NAME
@@ -78,7 +78,7 @@
The
.Nm
driver gives user-mode applications access to hardware-accelerated
-cryptographic transforms, as implemented by the
+cryptographic transforms as implemented by the
.Xr crypto 9
in-kernel interface.
.Pp
@@ -87,15 +87,15 @@ The
special device provides an
.Xr ioctl 2
based interface.
-User-mode applications should open the special device,
+User-mode applications open the special device and
then issue
.Xr ioctl 2
calls on the descriptor.
User-mode access to
.Pa /dev/crypto
-is controlled by three
+is controlled by two
.Xr sysctl 8
-variables,
+variables:
.Ic kern.userasymcrypto
and
.Ic kern.cryptodevallowsoft .
@@ -103,8 +103,8 @@ and
The
.Nm
device provides two distinct modes of operation: one mode for
-symmetric-keyed cryptographic requests, and a second mode for
-both asymmetric-key (public-key/private-key) requests, and for
+symmetric-keyed cryptographic requests and digests, and a second mode for
+both asymmetric-key (public-key/private-key) requests and
modular arithmetic (for Diffie-Hellman key exchange and other
cryptographic protocols).
The two modes are described separately below.
@@ -113,12 +113,22 @@ Regardless of whether symmetric-key or asymmetric-key
to be performed, use of the device requires a basic series of steps:
.Bl -enum
.It
-Open a file descriptor for the device.
-See
-.Xr open 2 .
+Open the
+.Pa /dev/crypto
+device.
.It
-If any symmetric operation will be performed,
-create one session, with
+Create a new cryptography file descriptor via
+.Dv CRIOGET
+to use for all subsequent
+.Xr ioctl 2
+commands.
+.It
+Close the
+.Pa /dev/crypto
+device.
+.It
+If any symmetric-keyed cryptographic or digest operations will be performed,
+create a session with
.Dv CIOCGSESSION .
Most applications will require at least one symmetric session.
Since cipher and MAC keys are tied to sessions, many
@@ -134,11 +144,13 @@ or
.Dv CIOCKEY
(asymmetric).
.It
-Destroy one session with
+Optionally destroy a session with
.Dv CIOCFSESSION .
.It
-Close the device with
+Close the cryptography file descriptor with
.Xr close 2 .
+This will automatically close any remaining sessions associated with the
+file desriptor.
.El
.Sh SYMMETRIC-KEY OPERATION
The symmetric-key operation mode provides a context-based API
@@ -196,9 +208,9 @@ struct session_op {
u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */
u_int32_t keylen; /* cipher key */
- void * key;
+ const void *key;
int mackeylen; /* mac key */
- void * mackey;
+ const void *mackey;
u_int32_t ses; /* returns: ses # */
};
@@ -241,12 +253,36 @@ and the key value in the octets addressed by
.Fa sessp-\*[Gt]mackeylen .
.\"
.Pp
-Support for a specific combination of fused privacy and
+Support for a specific combination of fused privacy and
integrity-check algorithms depends on whether the underlying
hardware supports that combination.
Not all combinations are supported
by all hardware, even if the hardware supports each operation as a
stand-alone non-fused operation.
+.It Dv CIOCGSESSION2 Fa struct session2_op *sessp
+.Bd -literal
+struct session2_op {
+ u_int32_t cipher; /* e.g. CRYPTO_DES_CBC */
+ u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */
+
+ u_int32_t keylen; /* cipher key */
+ const void *key;
+ int mackeylen; /* mac key */
+ const void *mackey;
+
+ u_int32_t ses; /* returns: ses # */
+ int crid; /* driver id + flags (rw) */
+ int pad[4]; /* for future expansion */
+};
+
+.Ed
+This request is similar to CIOGSESSION except that
+.Fa sessp-\*[Gt]crid
+requests either a specific crypto device or a class of devices (software vs
+hardware).
+The
+.Fa sessp-\*[Gt]pad
+field must be initialized to zero.
.It Dv CIOCCRYPT Fa struct crypt_op *cr_op
.Bd -literal
struct crypt_op {
@@ -261,9 +297,6 @@ struct crypt_op {
.Ed
Request a symmetric-key (or hash) operation.
-The file descriptor argument to
-.Xr ioctl 2
-must have been bound to a valid session.
To encrypt, set
.Fa cr_op-\*[Gt]op
to
@@ -315,21 +348,8 @@ but provides additional data in
.Fa cr_aead-\*[Gt]aad
to include in the authentication mode.
.It Dv CIOCFSESSION Fa u_int32_t ses_id
-Destroys the /dev/crypto session associated with the file-descriptor
-argument.
-.It Dv CIOCNFSESSION Fa struct crypt_sfop *sfop ;
-.Bd -literal
-struct crypt_sfop {
- size_t count;
- u_int32_t *sesid;
-};
-
-.Ed
-Destroys the
-.Fa sfop-\*[Gt]count
-sessions specified by the
-.Fa sfop
-array of session identifiers.
+Destroys the session identified by
+.Fa ses_id .
.El
.\"
.Sh ASYMMETRIC-KEY OPERATION
@@ -435,8 +455,10 @@ algorithm, you must supply a suitably-sized buffer.
.Pp
The scheme for passing arguments for asymmetric requests is baroque.
.Pp
-The naming inconsistency between
.Dv CRIOGET
-and the various
+should not exist.
+It should be possible to use the
.Dv CIOC Ns \&*
-names is an unfortunate historical artifact.
+commands directly on a
+.Pa /dev/crypto
+file descriptor.
Modified: stable/12/share/man/man9/crypto.9
==============================================================================
--- stable/12/share/man/man9/crypto.9 Sat Jan 18 23:26:15 2020 (r356870)
+++ stable/12/share/man/man9/crypto.9 Sat Jan 18 23:30:42 2020 (r356871)
@@ -17,7 +17,7 @@
.\"
.\" $FreeBSD$
.\"
-.Dd July 17, 2018
+.Dd December 17, 2019
.Dt CRYPTO 9
.Os
.Sh NAME
@@ -26,35 +26,35 @@
.Sh SYNOPSIS
.In opencrypto/cryptodev.h
.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
-.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
-.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
-.Fn crypto_unregister uint32_t int
+.Fn crypto_unregister "uint32_t driverid" "int alg"
.Ft int
-.Fn crypto_unregister_all uint32_t
+.Fn crypto_unregister_all "uint32_t driverid"
.Ft void
-.Fn crypto_done "struct cryptop *"
+.Fn crypto_done "struct cryptop *crp"
.Ft void
-.Fn crypto_kdone "struct cryptkop *"
+.Fn crypto_kdone "struct cryptkop *krp"
.Ft int
-.Fn crypto_find_driver "const char *"
+.Fn crypto_find_driver "const char *match"
.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
-.Fn crypto_freesession crypto_session_t
+.Fn crypto_freesession "crypto_session_t cses"
.Ft int
-.Fn crypto_dispatch "struct cryptop *"
+.Fn crypto_dispatch "struct cryptop *crp"
.Ft int
-.Fn crypto_kdispatch "struct cryptkop *"
+.Fn crypto_kdispatch "struct cryptkop *krp"
.Ft int
-.Fn crypto_unblock uint32_t int
+.Fn crypto_unblock "uint32_t driverid" "int what"
.Ft "struct cryptop *"
-.Fn crypto_getreq int
+.Fn crypto_getreq "int num"
.Ft void
-.Fn crypto_freereq void
+.Fn crypto_freereq "struct cryptop *crp"
.Bd -literal
#define CRYPTO_SYMQ 0x1
#define CRYPTO_ASYMQ 0x2
@@ -160,33 +160,48 @@ For session initialization and teardown no callback me
.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.
+returns the driver id of the device whose name matches
+.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
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
+.Fa cri
+argument points to a
+.Vt cryptoini
+structure containing 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
+The
+.Fa crid
+argument is either a specific driver id or a bitmask of flags.
+The flags are
.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 opaque
-session handle.
-The various fields in the
+If both are specified, hardware devices are preferred over software
+devices.
+On success, the opaque session handle of the new session will be stored in
+.Fa *cses .
+The
.Vt cryptoini
-structure are:
+structure pointed to by
+.Fa cri
+contains these fields:
.Bl -tag -width ".Va cri_next"
.It Va cri_alg
-Contains an algorithm identifier.
+An algorithm identifier.
Currently supported algorithms are:
.Pp
.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact
@@ -194,14 +209,19 @@ Currently supported algorithms are:
.It Dv CRYPTO_AES_192_NIST_GMAC
.It Dv CRYPTO_AES_256_NIST_GMAC
.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_NIST_GCM_16
.It Dv CRYPTO_AES_NIST_GMAC
.It Dv CRYPTO_AES_XTS
.It Dv CRYPTO_ARC4
+.It Dv CRYPTO_BLAKE2B
+.It Dv CRYPTO_BLAKE2S
.It Dv CRYPTO_BLF_CBC
.It Dv CRYPTO_CAMELLIA_CBC
.It Dv CRYPTO_CAST_CBC
+.It Dv CRYPTO_CHACHA20
.It Dv CRYPTO_DEFLATE_COMP
.It Dv CRYPTO_DES_CBC
.It Dv CRYPTO_3DES_CBC
@@ -210,43 +230,52 @@ Currently supported algorithms are:
.It Dv CRYPTO_MD5_KPDK
.It Dv CRYPTO_NULL_HMAC
.It Dv CRYPTO_NULL_CBC
+.It Dv CRYPTO_POLY1305
+.It Dv CRYPTO_RIPEMD160
.It Dv CRYPTO_RIPEMD160_HMAC
.It Dv CRYPTO_SHA1
.It Dv CRYPTO_SHA1_HMAC
.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_384
.It Dv CRYPTO_SHA2_384_HMAC
+.It Dv CRYPTO_SHA2_512
.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.
+For variable-size key algorithms, the length of the key in bits.
.It Va cri_mlen
-Specifies how many bytes from the calculated hash should be copied back.
-0 means entire hash.
+If non-zero, truncate the calculated hash to this many bytes.
.It Va cri_key
-Contains the key to be used with the algorithm.
+The key to be used.
.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.
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
+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).
+This is used to establish dual-algorithm sessions, such as combining a
+cipher with a MAC.
.El
.Pp
The
.Vt cryptoini
-structure and its contents will not be modified by the framework (or
-the drivers used).
+structure and its contents will not be modified or referenced by the
+framework or any cryptographic drivers.
+The memory associated with
+.Fa cri
+can be released once
+.Fn crypto_newsession
+returns.
.Pp
.Fn crypto_freesession
is called with the session handle returned by
@@ -260,28 +289,22 @@ The various fields in the
structure are:
.Bl -tag -width ".Va crp_callback"
.It Va crp_session
-Contains the session handle.
+The session handle.
.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
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
+Callback routine invoked when a request is completed via
+.Fn crypto_done .
+The callback routine should inspect the
.Va crp_etype
-field.
-It is the responsibility of the callback routine to set the appropriate
-.Xr spl 9
-level.
+to determine if the request was successfully completed.
.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.
If the
.Er EAGAIN
@@ -296,8 +319,7 @@ 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
+This field is only valid in the context of the callback routine specified by
.Va crp_callback .
Errors are returned to the invoker of
.Fn crypto_process
@@ -306,19 +328,17 @@ 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.
+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.
+The buffer is an mbuf chain pointed to by
+.Va crp_mbuf .
.It Dv CRYPTO_F_IOV
-The buffer pointed to by
-.Va crp_buf
-is an
+The buffer is a
.Vt uio
-structure.
+structure pointed to by
+.Va crp_uio .
.It Dv CRYPTO_F_BATCH
Batch operation if possible.
.It Dv CRYPTO_F_CBIMM
@@ -344,18 +364,31 @@ Only relevant if the
flag is set and if the operation is synchronous.
.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
+Data buffer unless
+.Dv CRYPTO_F_IMBUF
+or
+.Dv CRYPTO_F_IOV
+is set in
.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
-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.
.It Va crp_desc
-This is a linked list of descriptors.
+A linked list of descriptors.
Each descriptor provides
information about what type of cryptographic operation should be done
on the input buffer.
@@ -429,9 +462,7 @@ operations the offset of the IV is provided by the
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).
+by the consumer, and does not precede the data.
.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
@@ -468,9 +499,10 @@ block of data.
.Fn crypto_getreq
allocates a
.Vt cryptop
-structure with a linked list of as many
+structure with a linked list of
+.Fa num
.Vt cryptodesc
-structures as were specified in the argument passed to it.
+structures.
.Pp
.Fn crypto_freereq
deallocates a structure
@@ -500,10 +532,10 @@ This
variable indicates whether lower level reasons
for operation failure.
.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.
.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.
.It Va krp_kvp
An array of kernel memory blocks containing the parameters.
@@ -540,7 +572,7 @@ The
.Dv CRYPTOCAP_F_SYNC
may also be specified, and should be specified if the driver does all of
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
passed to the driver's
.Fn newsession
@@ -551,14 +583,6 @@ For each algorithm the driver supports, it must then c
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.
More information about the svn-src-all
mailing list