Copyright (c) 2004
Jonathan Stone <jonathan (at] 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 April 25 23, 2004 .Dt CRYPTO 4 .Os .Sh NAME .Nm "crypto" .Nd user-mode access to hardware-accelerated cryptography .Sh SYNOPSIS .Cd "hifn* at pci? dev ? function ?" .Cd "ubsec* at pci? dev ? function ?"
p .Cd "pseudo-device crypto"
p n sys/ioctl.h n 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. The
a /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. 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 exponentiation (for Diffie-Hellman key exchange). The two modes are described separately below. .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 fudised encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
p 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: l -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent t CRYPTO_DES_CBC t CRYPTO_3DES_CBC t CRYPTO_BLF_CBC t CRYPTO_CAST_CBC t CRYPTO_SKIPJACK_CBC t CRYPTO_AES_CBC t CRYPTO_ARC4 .El
p
.Ss Integrity-check operations
Contingent upon hardware support, some or all of the following
keyed one-way hash algorithms may be available:
l -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent t CRYPTO_RIPEMD160_HMAC t CRYPTO_MD5_KPDK t CRYPTO_SHA1_KPDK t CRYPTO_MD5_HMAC t CRYPTO_SHA1_HMAC t CRYPTO_SHA2_HMAC t CRYPTO_MD5 t CRYPTO_SHA1 .El
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
l -tag -width CIOCFKEY
t Dv CRIOCGET Fa int *fd Clone the fd argument to
.Xr ioctl 4 ,
yielding a new file descriptor which can be used to create
crypto sessions and request crypto operations.
t Dv CRIOCGSESSION Fa struct session_op *sessp Persistently bind a file descriptor returned by a previous
.Dv CRIOCGET
to a session: that is, 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.
p For non-zero symmetric-key privacy algorithms, the privacy algorithm must be specified in .Fa sess->cipher , the key length in .Fa sessp->keylen , and the key value in the octets addressed by .Fa sessp->key .
p
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 .
p
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.
t Dv CIOCCRYPT Fa struct crpyto_op *cr_op Request a symmetric-key (or unkeyed hash) operation.
The file descriptor argument to
.Xr ioctl 4
must have been bound to a valid session.
To encrypt, set
.Fa cr_op->op
to COP_ENCRYPT. To decrypt, set
.Fa cr_op->op
to 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.
t Dv CIOCFSESSION Fa void Destroys the /dev/crypto session associated with the file-descriptor
argument.
.El
.Sh ASYMMETRIC-KEY OPERATION
p .Ss Asymmetric-key algorithms Contingent upon hardware support, the following asymmetric (public-key/private-key; or key-exchange subroutine) operations may also be available: l -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact t Em "Algorithm" Ta "Input parameter" Ta "Output parameter" t Em " " Ta "Count" Ta "Count" t Dv CRK_MOD_EXP Ta 3 Ta 1 t Dv CRK_MOD_EXP_CRT Ta 6 Ta 1 t Dv CRK_DSA_SIGN Ta 5 Ta 2 t Dv CRK_DSA_VERIFY Ta 7 Ta 0 t Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1 .El
p
See below for discussion of the input and output parameter counts.
.Ss Asymmetric-key commands
l -tag -width CIOCFKEY
t Dv CIOCASSYMFEAT Fa int *feature_mask Returns a bitmask of supported asymmetric-key operations.
Each of the above-listed asymmetric operations is present
if and only 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
.Dv (1 << CRK_MOD_EX)
is set.
t Dv CIOCFKEY Fa struct crypt_kop *kop 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.
.El
p
The semantics of these arguments is currently undocumented.
.Sh SEE ALSO
.Xr hifn 4 ,
.Xr ubsec 4 ,
.Xr opencrypto 9 .
.Sh BUGS
p Error checking and reporting is weak. The values specified for symmetric-key key sizes to .Dv CRIOCGSESSION , must exactly match the values expected by .XR opencrypto 9 . The output buffer and MAC buffers supplied to .Dv CRIOCRYPT must follow whether privacy or integrity algorithms were specified for session: if you request a non-NULL algorithm, you must supply a suitably-sized buffer.
p The scheme for passing arguments for asymmetric requests is Baroque. .Sh HISTORY The .Nm driver is derived from a version which appeared .Fx 4.8 , which in turn is based on code which appeared in .Ox 3.2 .
Indexes created Tue Oct 21 16:10:11 GMT 2025