diff options
Diffstat (limited to 'static/netbsd/man4/crypto.4')
| -rw-r--r-- | static/netbsd/man4/crypto.4 | 663 |
1 files changed, 663 insertions, 0 deletions
diff --git a/static/netbsd/man4/crypto.4 b/static/netbsd/man4/crypto.4 new file mode 100644 index 00000000..bf4cd509 --- /dev/null +++ b/static/netbsd/man4/crypto.4 @@ -0,0 +1,663 @@ +.\" $NetBSD: crypto.4,v 1.26 2017/07/03 21:30:58 wiz Exp $ +.\" +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Coyote Point Systems, Inc. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.\" +.\" +.\" Copyright (c) 2004 +.\" Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF +.\" THE POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd January 27, 2014 +.Dt CRYPTO 4 +.Os +.Sh NAME +.Nm crypto , +.Nm swcrypto +.Nd user-mode access to hardware-accelerated cryptography +.Sh SYNOPSIS +.Cd "hifn* at pci? dev ? function ?" +.Cd "ubsec* at pci? dev ? function ?" +.Pp +.Cd pseudo-device crypto +.Cd pseudo-device swcrypto +.Pp +.In sys/ioctl.h +.In sys/time.h +.In crypto/cryptodev.h +.Sh DESCRIPTION +The +.Nm +driver gives user-mode applications access to hardware-accelerated +cryptographic transforms, as implemented by the +.Xr opencrypto 9 +in-kernel interface. +.Pp +The +.Cm swcrypto +driver is a software-only implementation of the +.Xr opencrypto 9 +interface, and must be included to use the interface without hardware +acceleration. +.Pp +The +.Pa /dev/crypto +special device provides an +.Xr ioctl 2 +based interface. +User-mode applications should open the special device, +then issue +.Xr ioctl 2 +calls on the descriptor. +User-mode access to +.Pa /dev/crypto +is generally controlled by three +.Xr sysctl 8 +variables, +.Ic kern.usercrypto , +.Ic kern.userasymcrypto , +and +.Ic kern.cryptodevallowsoft . +See +.Xr sysctl 7 +for additional details. +.Pp +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 +modular arithmetic (for Diffie-Hellman key exchange and other +cryptographic protocols). +The two modes are described separately below. +.Sh THEORY OF OPERATION +Regardless of whether symmetric-key or asymmetric-key operations are +to be performed, use of the device requires a basic series of steps: +.Pp +.Bl -enum +.It +Open a file descriptor for the device. +See +.Xr open 2 . +.It +If any symmetric operation will be performed, +create one session, with +.Dv CIOCGSESSION , +or multiple sessions, with +.Dv CIOCNGSESSION . +Most applications will require at least one symmetric session. +Since cipher and MAC keys are tied to sessions, many +applications will require more. +Asymmetric operations do not use sessions. +.It +Submit requests, synchronously with +.Dv CIOCCRYPT +(symmetric) +or +.Dv CIOCKEY +(asymmetric) +or asynchronously with +.Dv CIOCNCRYPTM +(symmetric) +or +.Dv CIOCNFKEYM +(asymmetric). +The asynchronous interface allows multiple requests to be submitted in one +call if the user so desires. +.It +If the asynchronous interface is used, wait for results with +.Xr select 2 +or +.Xr poll 2 , +then collect them with +.Dv CIOCNCRYPTRET +(a particular request) +or +.Dv CIOCNCRYPTRETM +(multiple requests). +.It +Destroy one session with +.Dv CIOCFSESSION +or many at once with +.Dv CIOCNFSESSION . +.It +Close the device with +.Xr close 2 . +.El +.Sh SYMMETRIC-KEY OPERATION +The symmetric-key operation mode provides a context-based API +to traditional symmetric-key encryption (or privacy) algorithms, +or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms. +The symmetric-key mode also permits fused operation, +where the hardware performs both a privacy algorithm and an integrity-check +algorithm in a single pass over the data: either a fused +encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. +.Pp +To use symmetric mode, you must first create a session specifying +the algorithm(s) and key(s) to use; then issue encrypt or decrypt +requests against the session. +.Ss Symmetric-key privacy algorithms +Contingent upon device drivers for installed cryptographic hardware +registering with +.Xr opencrypto 9 , +as providers of a given algorithm, some or all of the following +symmetric-key privacy algorithms may be available: +.Pp +.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent +.It CRYPTO_DES_CBC +.It CRYPTO_3DES_CBC +.It CRYPTO_BLF_CBC +.It CRYPTO_CAST_CBC +.It CRYPTO_SKIPJACK_CBC +.It CRYPTO_AES_CBC +.It CRYPTO_ARC4 +.El +.Ss Integrity-check operations +Contingent upon hardware support, some or all of the following +keyed one-way hash algorithms may be available: +.Pp +.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent +.It CRYPTO_RIPEMD160_HMAC +.It CRYPTO_MD5_KPDK +.It CRYPTO_SHA1_KPDK +.It CRYPTO_MD5_HMAC +.It CRYPTO_SHA1_HMAC +.It CRYPTO_SHA2_256_HMAC +.It CRYPTO_SHA2_384_HMAC +.It CRYPTO_SHA2_512_HMAC +.It CRYPTO_MD5 +.It CRYPTO_SHA1 +.El +.Pp +The +.Em CRYPTO_MD5 +and +.Em CRYPTO_SHA1 +algorithms are actually unkeyed, but should be requested +as symmetric-key hash algorithms with a zero-length key. +.Ss IOCTL Request Descriptions +.\" +.Bl -tag -width CIOCKEY +.\" +.It Dv CRIOGET Fa int *fd +This operation is deprecated and will be removed after +.Nx 5.0 . +It clones the fd argument to +.Xr ioctl 2 , +yielding a new file descriptor for the creation of sessions. +Because the device now clones on open, this operation is unnecessary. +.\" +.It Dv CIOCGSESSION Fa struct session_op *sessp +.Bd -literal +struct session_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 */ + void * key; + int mackeylen; /* mac key */ + void * mackey; + + u_int32_t ses; /* returns: ses # */ +}; + +.Ed +Create a new cryptographic session on a file descriptor for the device; +that is, a persistent object specific to the chosen +privacy algorithm, integrity algorithm, and keys specified in +.Fa sessp . +The special value 0 for either privacy or integrity +is reserved to indicate that the indicated operation (privacy or integrity) +is not desired for this session. +.Pp +Multiple sessions may be bound to a single file descriptor. +The session ID returned in +.Fa sessp->ses +is supplied as a required field in the symmetric-operation structure +.Fa crypt_op +for future encryption or hashing requests. +.Pp +This implementation will never return a session ID of 0 for a successful +creation of a session, which is a +.Nx +extension. +.Pp +For non-zero symmetric-key privacy algorithms, the privacy algorithm +must be specified in +.Fa sessp->cipher , +the key length in +.Fa sessp->keylen , +and the key value in the octets addressed by +.Fa sessp->key . +.Pp +For keyed one-way hash algorithms, the one-way hash must be specified +in +.Fa sessp->mac , +the key length in +.Fa sessp->mackey , +and the key value in the octets addressed by +.Fa sessp->mackeylen . +.\" +.Pp +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 CIOCNGSESSION Fa struct crypt_sgop *sgop +.Bd -literal +struct crypt_sgop { + size_t count; /* how many */ + struct session_n_op * sessions; /* where to get them */ +}; + +struct session_n_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 */ + void * key; + u_int32_t mackeylen; /* mac key */ + void * mackey; + + u_int32_t ses; /* returns: session # */ + int status; +}; + +.Ed +Create one or more sessions. +Takes a counted array of +.Fa session_n_op +structures in +.Fa sgop . +For each requested session (array element n), the session number is returned in +.Fa sgop->sessions[n].ses +and the status for that session creation in +.Fa sgop->sessions[n].status . +.\" +.It Dv CIOCCRYPT Fa struct crypt_op *cr_op +.Bd -literal +struct crypt_op { + u_int32_t ses; + u_int16_t op; /* e.g. COP_ENCRYPT */ + u_int16_t flags; + u_int len; + void * src, *dst; + void * mac; /* must be large enough for result */ + void * iv; +}; + +.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->op +to +.Dv COP_ENCRYPT . +To decrypt, set +.Fa cr_op->op +to +.Dv COP_DECRYPT . +The field +.Fa cr_op->len +supplies the length of the input buffer; the fields +.Fa cr_op->src , +.Fa cr_op->dst , +.Fa cr_op->mac , +.Fa cr_op->iv +supply the addresses of the input buffer, output buffer, +one-way hash, and initialization vector, respectively. +.It Dv CIOCNCRYPTM Fa struct crypt_mop *cr_mop +.Bd -literal +struct crypt_mop { + size_t count; /* how many */ + struct crypt_n_op * reqs; /* where to get them */ +}; + +struct crypt_n_op { + u_int32_t ses; + u_int16_t op; /* e.g. COP_ENCRYPT */ + u_int16_t flags; + u_int len; + + u_int32_t reqid; /* request id */ + int status; /* accepted or not */ + + void *opaque; /* opaque pointer ret to user */ + u_int32_t keylen; /* cipher key - optional */ + void * key; + u_int32_t mackeylen; /* mac key - optional */ + void * mackey; + + void * src, * dst; + void * mac; + void * iv; +}; + +.Ed +This is the asynchronous version of CIOCCRYPT, which allows multiple +symmetric-key (or hash) operations to be started (see CIOCRYPT +above for the details for each operation). +.Pp +The +.Fa cr_mop->count +field specifies the number of operations provided in the +cr_mop->reqs array. +.Pp +Each operation is assigned a unique request id returned in the +.Fa cr_mop->reqs[n].reqid +field. +.Pp +Each operation can accept an opaque value from the user to be passed back +to the user when the operation completes +(e.g., to track context for the request). +The opaque field is +.Fa cr_mop->reqs[n].opaque . +.Pp +If a problem occurs with starting any of the operations then that +operation's +.Fa cr_mop->reqs[n].status +field is filled with the error code. +The failure of an operation does not +prevent the other operations from being started. +.Pp +The +.Xr select 2 +or +.Xr poll 2 +functions must be used on the device file descriptor to detect that +some operation has completed; results are then retrieved with +.Dv CIOCNCRYPTRETM . +.Pp +The +.Fa key +and +.Fa mackey +fields of the +operation structure are currently unused. +They are intended for use to +immediately rekey an existing session before processing a new request. +.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->count +sessions specified by the +.Fa sfop +array of session identifiers. +.El +.\" +.Sh ASYMMETRIC-KEY OPERATION +.Ss Asymmetric-key algorithms +Contingent upon hardware support, the following asymmetric +(public-key/private-key; or key-exchange subroutine) operations may +also be available: +.Pp +.Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact +.It Em "Algorithm" Ta "Input parameter" Ta "Output parameter" +.It Em " " Ta "Count" Ta "Count" +.It Dv CRK_MOD_EXP Ta 3 Ta 1 +.It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1 +.It Dv CRK_MOD_ADD Ta 3 Ta 1 +.It Dv CRK_MOD_ADDINV Ta 2 Ta 1 +.It Dv CRK_MOD_SUB Ta 3 Ta 1 +.It Dv CRK_MOD_MULT Ta 3 Ta 1 +.It Dv CRK_MOD_MULTINV Ta 2 Ta 1 +.It Dv CRK_MOD Ta 2 Ta 1 +.It Dv CRK_DSA_SIGN Ta 5 Ta 2 +.It Dv CRK_DSA_VERIFY Ta 7 Ta 0 +.It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1 +.El +.Pp +See below for discussion of the input and output parameter counts. +.Ss Asymmetric-key commands +.Bl -tag -width CIOCKEY +.It Dv CIOCASYMFEAT Fa int *feature_mask +Returns a bitmask of supported asymmetric-key operations. +Each of the above-listed asymmetric operations is present +if and only if the bit position numbered by the code for that operation +is set. +For example, +.Dv CRK_MOD_EXP +is available if and only if the bit +.Pq 1 << Dv CRK_MOD_EXP +is set. +.It Dv CIOCKEY Fa struct crypt_kop *kop +.Bd -literal +struct crypt_kop { + u_int crk_op; /* e.g. CRK_MOD_EXP */ + u_int crk_status; /* return status */ + u_short crk_iparams; /* # of input params */ + u_short crk_oparams; /* # of output params */ + u_int crk_pad1; + struct crparam crk_param[CRK_MAXPARAM]; +}; + +/* Bignum parameter, in packed bytes. */ +struct crparam { + void * crp_p; + u_int crp_nbits; +}; + +.Ed +Performs an asymmetric-key operation from the list above. +The specific operation is supplied in +.Fa kop->crk_op ; +final status for the operation is returned in +.Fa kop->crk_status . +The number of input arguments and the number of output arguments +is specified in +.Fa kop->crk_iparams +and +.Fa kop->crk_iparams , +respectively. +The field +.Fa crk_param[] +must be filled in with exactly +.Fa kop->crk_iparams + kop->crk_oparams +arguments, each encoded as a +.Fa struct crparam +(address, bitlength) pair. +.Pp +The semantics of these arguments are currently undocumented. +.It Dv CIOCNFKEYM Fa struct crypt_mkop *mkop +.Bd -literal +struct crypt_mkop { + size_t count; /* how many */ + struct crypt_n_op * reqs; /* where to get them */ +}; + +struct crypt_n_kop { + u_int crk_op; /* e.g. CRK_MOD_EXP */ + u_int crk_status; /* accepted or not */ + u_short crk_iparams; /* # of input params */ + u_short crk_oparams; /* # of output params */ + u_int32_t crk_reqid; /* request id */ + struct crparam crk_param[CRK_MAXPARAM]; + void *crk_opaque; /* opaque pointer ret to user */ +}; + +.Ed +This is the asynchronous version of +.Dv CIOCKEY , +which starts one or more key operations. +See +.Dv CIOCNCRYPTM +above and +.Dv CIOCNCRYPTRETM +below +for descriptions of the +.Fa mkop>count , +.Fa mkop>reqs , +.Fa mkop>reqs[n].crk_reqid , +.Fa mkop>reqs[n].crk_status , +and +.Fa mkop>reqs[n].crk_opaque +fields of the argument structure, and result retrieval. +.El +.Ss Asynchronous status commands +When requests are submitted with the +.Dv CIOCNCRYPTM +or +.Dv CIOCNFKEYM +commands, result retrieval is asynchronous +(the submit ioctls return immediately). +Use the +.Xr select 2 +or +.Xr poll 2 +functions to determine when the file descriptor has completed operations ready +to be retrieved. +.Bl -tag -width CIOCKEY +.It Dv CIOCNCRYPTRET Fa struct crypt_result *cres +.Bd -literal +struct crypt_result { + u_int32_t reqid; /* request ID */ + u_int32_t status; /* 0 if successful */ + void * opaque; /* pointer from user */ +}; + +.Ed +Check for the status of the request specified by +.Fa cres->reqid . +This requires a linear search through all completed requests and should +be used with extreme care if the number of requests pending on this +file descriptor may be large. +.Pp +The +.Fa cres->status +field is set as follows: +.Bl -tag -width EINPROGRESS +.It 0 +The request has completed, and its results have been copied out to +the original +.Fa crypt_n_op or +.Fa crypt_n_kop +structure used to start the request. +The copyout occurs during this ioctl, +so the calling process must be the process that started the request. +.It EINPROGRESS +The request has not yet completed. +.It EINVAL +The request was not found. +.El +.Pp +Other values indicate a problem during the processing of the request. +.It Dv CIOCNCRYPTRETM Fa struct cryptret_t *cret +.Bd -literal +struct cryptret { + size_t count; /* space for how many */ + struct crypt_result * results; /* where to put them */ +}; + +.Ed +Retrieve a number of completed requests. +This ioctl accepts a count and +an array (each array element is a +.Fa crypt_result_t +structure as used by +.Dv CIOCNCRYPTRET +above) and fills the array with up to +.Fa cret->count +results of completed requests. +.Pp +This ioctl fills in the +.Fa cret->results[n].reqid field , +so that the request which has completed +may be identified by the application. +Note that the results may include +requests submitted both as symmetric and asymmetric operations. +.El +.Sh SEE ALSO +.Xr hifn 4 , +.Xr ubsec 4 , +.Xr opencrypto 9 +.Sh HISTORY +The +.Nm +driver is derived from a version which appeared in +.Fx 4.8 , +which in turn is based on code which appeared in +.Ox 3.2 . +.Pp +The "new API" for asynchronous operation with multiple basic operations +per system call (the "N" ioctl variants) was contributed by Coyote Point +Systems, Inc. and first appeared in +.Nx 5.0 . +.Sh BUGS +Error checking and reporting is weak. +.Pp +The values specified for symmetric-key key sizes to +.Dv CIOCGSESSION +must exactly match the values expected by +.Xr opencrypto 9 . +The output buffer and MAC buffers supplied to +.Dv CIOCCRYPT +must follow whether privacy or integrity algorithms were specified for +session: if you request a +.No non- Ns Dv NULL +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 +.Dv CIOC Ns \&* +names is an unfortunate historical artifact. |