Date: Mon, 8 Sep 2014 04:49:08 GMT From: John-Mark Gurney <jmg@FreeBSD.org> To: Perforce Change Reviews <perforce@FreeBSD.org> Subject: PERFORCE change 1198640 for review Message-ID: <201409080449.s884n8HJ020167@skunkworks.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://p4web.freebsd.org/@@1198640?ac=10 Change 1198640 by jmg@jmg_carbon2 on 2014/08/13 00:36:09 Bring in NetBSD's man page since it is much more useful than ours.. add the new AEAD ioctl that I added for testing GCM... Affected files ... .. //depot/projects/opencrypto/share/man/man4/crypto.4#2 edit Differences ... ==== //depot/projects/opencrypto/share/man/man4/crypto.4#2 (text+ko) ==== @@ -1,8 +1,15 @@ -.\" $OpenBSD: crypto.4,v 1.4 2002/09/12 07:15:03 deraadt Exp $ +.\" $NetBSD: crypto.4,v 1.24 2014/01/27 21:23:59 pgoyette Exp $ .\" -.\" Copyright (c) 2001 Theo de Raadt +.\" Copyright (c) 2008 The NetBSD Foundation, Inc. +.\" Copyright (c) 2014 The FreeBSD Foundation .\" All rights reserved. .\" +.\" Portions of this documentation were writen by John-Mark Gurney +.\" under sponsorship from the FreeBSD Foundation. +.\" +.\" 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: @@ -11,99 +18,354 @@ .\" 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. -.\" 3. The name of the author may not be used to endorse or promote products -.\" derived from this software without specific prior written permission. .\" -.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 +.\" 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. .\" -.\" $FreeBSD: head/share/man/man4/crypto.4 263110 2014-03-13 16:19:36Z jmg $ +.\" +.\" +.\" 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 September 7, 2010 +.Dd August 12, 2014 .Dt CRYPTO 4 .Os .Sh NAME .Nm crypto , .Nm cryptodev -.Nd hardware crypto access driver +.Nd user-mode access to hardware-accelerated cryptography .Sh SYNOPSIS .Cd device crypto .Cd device cryptodev +.Pp +.In sys/ioctl.h +.In sys/time.h +.In crypto/cryptodev.h .Sh DESCRIPTION The .Nm -driver provides a device-independent framework to support -cryptographic operations in the kernel. +driver gives user-mode applications access to hardware-accelerated +cryptographic transforms, as implemented by the +.Xr opencrypto 9 +in-kernel interface. +.Pp The -.Nm cryptodev -driver provides userland applications access to this support -through the .Pa /dev/crypto -device. -This node primarily operates in an +special device provides an +.Xr ioctl 2 +based interface. +User-mode applications should open the special device, +then issue .Xr ioctl 2 -based model, permitting a variety of applications to query device capabilities, -submit transactions, and get results. +calls on the descriptor. +User-mode access to +.Pa /dev/crypto +is controlled by three +.Xr sysctl 8 +variables, +.Ic kern.userasymcrypto +and +.Ic kern.cryptodevallowsoft . +See +.Xr sysctl 7 +for additional details. .Pp -If -.Ar count -given in the specification, and is greater than 0, a maximum of one +The .Nm -device is created. +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 . +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). +.It +Destroy one session with +.Dv CIOCFSESSION . +.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 Algorithms +For a list of supported algorithms, see +.Xr crypto 9 . +.Ss IOCTL Request Descriptions +.\" +.Bl -tag -width CIOCGSESSION +.\" +.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-\*[Gt]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-\*[Gt]cipher , +the key length in +.Fa sessp-\*[Gt]keylen , +and the key value in the octets addressed by +.Fa sessp-\*[Gt]key . +.Pp +For keyed one-way hash algorithms, the one-way hash must be specified +in +.Fa sessp-\*[Gt]mac , +the key length in +.Fa sessp-\*[Gt]mackey , +and the key value in the octets addressed by +.Fa sessp-\*[Gt]mackeylen . +.\" .Pp -The following +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 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; + caddr_t src, dst; + caddr_t mac; /* must be large enough for result */ + caddr_t iv; +}; + +.Ed +Request a symmetric-key (or hash) operation. +The file descriptor argument to .Xr ioctl 2 -calls apply only to the -.Nm -devices: -.Bl -tag -width ".Dv CIOCGSESSION" -.It Dv CIOCGSESSION -Setup a new crypto session for a new type of operation. -.It Dv CIOCFSESSION -Free a previously established session. -.It Dv CIOCCRYPT -Perform a crypto operation against a previously setup session. +must have been bound to a valid session. +To encrypt, set +.Fa cr_op-\*[Gt]op +to +.Dv COP_ENCRYPT . +To decrypt, set +.Fa cr_op-\*[Gt]op +to +.Dv COP_DECRYPT . +The field +.Fa cr_op-\*[Gt]len +supplies the length of the input buffer; the fields +.Fa cr_op-\*[Gt]src , +.Fa cr_op-\*[Gt]dst , +.Fa cr_op-\*[Gt]mac , +.Fa cr_op-\*[Gt]iv +supply the addresses of the input buffer, output buffer, +one-way hash, and initialization vector, respectively. +.It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead +.Bd -literal +struct crypt_aead { + u_int32_t ses; + u_int16_t op; /* e.g. COP_ENCRYPT */ + u_int16_t flags; + u_int len; + u_int aadlen; + u_int ivlen; + caddr_t src, dst; + caddr_t aad; + caddr_t tag; /* must be large enough for result */ + caddr_t iv; +}; + +.Ed +The +.Dv CIOCCRYPTAEAD +is similar to the +.Dv CIOCCRYPT +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. .El -.Sh FEATURES -Depending on hardware being present, the following symmetric and -asymmetric cryptographic features are potentially available from -.Pa /dev/crypto : +.\" +.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 -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -offset indent -compact -.It Dv CRYPTO_DES_CBC -.It Dv CRYPTO_3DES_CBC -.It Dv CRYPTO_BLF_CBC -.It Dv CRYPTO_CAMELLIA_CBC -.It Dv CRYPTO_CAST_CBC -.It Dv CRYPTO_SKIPJACK_CBC -.It Dv CRYPTO_MD5_HMAC -.It Dv CRYPTO_SHA1_HMAC -.It Dv CRYPTO_RIPEMD160_HMAC -.It Dv CRYPTO_MD5_KPDK -.It Dv CRYPTO_SHA1_KPDK -.It Dv CRYPTO_AES_CBC -.It Dv CRYPTO_ARC4 -.It Dv CRYPTO_MD5 -.It Dv CRYPTO_SHA1 -.It Dv CRK_MOD_EXP -.It Dv CRK_MOD_EXP_CRT -.It Dv CRK_DSA_SIGN -.It Dv CRK_DSA_VERIFY -.It Dv CRK_DH_COMPUTE_KEY +.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_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 -.Sh FILES -.Bl -tag -width ".Pa /dev/crypto" -compact -.It Pa /dev/crypto -crypto access device +.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 \*[Lt]\*[Lt] 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-\*[Gt]crk_op ; +final status for the operation is returned in +.Fa kop-\*[Gt]crk_status . +The number of input arguments and the number of output arguments +is specified in +.Fa kop-\*[Gt]crk_iparams +and +.Fa kop-\*[Gt]crk_iparams , +respectively. +The field +.Fa crk_param[] +must be filled in with exactly +.Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams +arguments, each encoded as a +.Fa struct crparam +(address, bitlength) pair. +.Pp +The semantics of these arguments are currently undocumented. .El .Sh SEE ALSO .Xr aesni 4 , @@ -123,3 +385,24 @@ .Nm driver was imported to .Fx 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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201409080449.s884n8HJ020167>