share/man/man4/crypto.4

   1 .\"     $NetBSD: crypto.4,v 1.24 2014/01/27 21:23:59 pgoyette Exp $
   2 .\"
   3 .\" Copyright (c) 2008 The NetBSD Foundation, Inc.
   4 .\" Copyright (c) 2014 The FreeBSD Foundation
   5 .\" All rights reserved.
   6 .\"
   7 .\" Portions of this documentation were written by John-Mark Gurney
   8 .\" under sponsorship of the FreeBSD Foundation and
   9 .\" Rubicon Communications, LLC (Netgate).
  10 .\"
  11 .\" This code is derived from software contributed to The NetBSD Foundation
  12 .\" by Coyote Point Systems, Inc.
  13 .\"
  14 .\" Redistribution and use in source and binary forms, with or without
  15 .\" modification, are permitted provided that the following conditions
  16 .\" are met:
  17 .\" 1. Redistributions of source code must retain the above copyright
  18 .\"    notice, this list of conditions and the following disclaimer.
  19 .\" 2. Redistributions in binary form must reproduce the above copyright
  20 .\"    notice, this list of conditions and the following disclaimer in the
  21 .\"    documentation and/or other materials provided with the distribution.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  24 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  25 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  26 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  27 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  28 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  29 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  30 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  31 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  32 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  33 .\" POSSIBILITY OF SUCH DAMAGE.
  34 .\"
  35 .\"
  36 .\"
  37 .\" Copyright (c) 2004
  38 .\"     Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved.
  39 .\"
  40 .\" Redistribution and use in source and binary forms, with or without
  41 .\" modification, are permitted provided that the following conditions
  42 .\" are met:
  43 .\" 1. Redistributions of source code must retain the above copyright
  44 .\"    notice, this list of conditions and the following disclaimer.
  45 .\" 2. Redistributions in binary form must reproduce the above copyright
  46 .\"    notice, this list of conditions and the following disclaimer in the
  47 .\"    documentation and/or other materials provided with the distribution.
  48 .\"
  49 .\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND
  50 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  51 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  52 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD
  53 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  54 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  55 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  56 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  57 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  58 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  59 .\" THE POSSIBILITY OF SUCH DAMAGE.
  60 .\"
  61 .\" $FreeBSD$
  62 .\"
  63 .Dd December 12, 2014
  64 .Dt CRYPTO 4
  65 .Os
  66 .Sh NAME
  67 .Nm crypto ,
  68 .Nm cryptodev
  69 .Nd user-mode access to hardware-accelerated cryptography
  70 .Sh SYNOPSIS
  71 .Cd device crypto
  72 .Cd device cryptodev
  73 .Pp
  74 .In sys/ioctl.h
  75 .In sys/time.h
  76 .In crypto/cryptodev.h
  77 .Sh DESCRIPTION
  78 The
  79 .Nm
  80 driver gives user-mode applications access to hardware-accelerated
  81 cryptographic transforms, as implemented by the
  82 .Xr opencrypto 9
  83 in-kernel interface.
  84 .Pp
  85 The
  86 .Pa /dev/crypto
  87 special device provides an
  88 .Xr ioctl 2
  89 based interface.
  90 User-mode applications should open the special device,
  91 then issue
  92 .Xr ioctl 2
  93 calls on the descriptor.
  94 User-mode access to
  95 .Pa /dev/crypto
  96 is controlled by three
  97 .Xr sysctl 8
  98 variables,
  99 .Ic kern.userasymcrypto
 100 and
 101 .Ic kern.cryptodevallowsoft .
 102 See
 103 .Xr sysctl 7
 104 for additional details.
 105 .Pp
 106 The
 107 .Nm
 108 device provides two distinct modes of operation: one mode for
 109 symmetric-keyed cryptographic requests, and a second mode for
 110 both asymmetric-key (public-key/private-key) requests, and for
 111 modular arithmetic (for Diffie-Hellman key exchange and other
 112 cryptographic protocols).
 113 The two modes are described separately below.
 114 .Sh THEORY OF OPERATION
 115 Regardless of whether symmetric-key or asymmetric-key operations are
 116 to be performed, use of the device requires a basic series of steps:
 117 .Bl -enum
 118 .It
 119 Open a file descriptor for the device.
 120 See
 121 .Xr open 2 .
 122 .It
 123 If any symmetric operation will be performed,
 124 create one session, with
 125 .Dv CIOCGSESSION .
 126 Most applications will require at least one symmetric session.
 127 Since cipher and MAC keys are tied to sessions, many
 128 applications will require more.
 129 Asymmetric operations do not use sessions.
 130 .It
 131 Submit requests, synchronously with
 132 .Dv CIOCCRYPT
 133 (symmetric)
 134 or
 135 .Dv CIOCKEY
 136 (asymmetric).
 137 .It
 138 Destroy one session with
 139 .Dv CIOCFSESSION .
 140 .It
 141 Close the device with
 142 .Xr close 2 .
 143 .El
 144 .Sh SYMMETRIC-KEY OPERATION
 145 The symmetric-key operation mode provides a context-based API
 146 to traditional symmetric-key encryption (or privacy) algorithms,
 147 or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms.
 148 The symmetric-key mode also permits fused operation,
 149 where the hardware performs both a privacy algorithm and an integrity-check
 150 algorithm in a single pass over the data: either a fused
 151 encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
 152 .Pp
 153 To use symmetric mode, you must first create a session specifying
 154 the algorithm(s) and key(s) to use; then issue encrypt or decrypt
 155 requests against the session.
 156 .Ss Algorithms
 157 For a list of supported algorithms, see
 158 .Xr crypto 7
 159 and
 160 .Xr crypto 9 .
 161 .Ss IOCTL Request Descriptions
 162 .\"
 163 .Bl -tag -width CIOCGSESSION
 164 .\"
 165 .It Dv CRIOGET Fa int *fd
 166 Clone the fd argument to
 167 .Xr ioctl 2 ,
 168 yielding a new file descriptor for the creation of sessions.
 169 .\"
 170 .It Dv CIOCFINDDEV Fa struct crypt_find_op *fop
 171 .Bd -literal
 172 struct crypt_find_op {
 173     int     crid;       /* driver id + flags */
 174     char    name[32];   /* device/driver name */
 175 };
 176
 177 .Ed
 178 If
 179 .Fa crid
 180 is -1, then find the driver named
 181 .Fa name
 182 and return the id in
 183 .Fa crid .
 184 If
 185 .Fa crid
 186 is not -1, return the name of the driver with
 187 .Fa crid
 188 in
 189 .Fa name .
 190 In either case, if the driver is not found,
 191 .Dv ENOENT
 192 is returned.
 193 .It Dv CIOCGSESSION Fa struct session_op *sessp
 194 .Bd -literal
 195 struct session_op {
 196     u_int32_t cipher;   /* e.g. CRYPTO_DES_CBC */
 197     u_int32_t mac;      /* e.g. CRYPTO_MD5_HMAC */
 198
 199     u_int32_t keylen;   /* cipher key */
 200     void * key;
 201     int mackeylen;      /* mac key */
 202     void * mackey;
 203
 204     u_int32_t ses;      /* returns: ses # */
 205 };
 206
 207 .Ed
 208 Create a new cryptographic session on a file descriptor for the device;
 209 that is, a persistent object specific to the chosen
 210 privacy algorithm, integrity algorithm, and keys specified in
 211 .Fa sessp .
 212 The special value 0 for either privacy or integrity
 213 is reserved to indicate that the indicated operation (privacy or integrity)
 214 is not desired for this session.
 215 .Pp
 216 Multiple sessions may be bound to a single file descriptor.
 217 The session ID returned in
 218 .Fa sessp-\*[Gt]ses
 219 is supplied as a required field in the symmetric-operation structure
 220 .Fa crypt_op
 221 for future encryption or hashing requests.
 222 .\" .Pp
 223 .\" This implementation will never return a session ID of 0 for a successful
 224 .\" creation of a session, which is a
 225 .\" .Nx
 226 .\" extension.
 227 .Pp
 228 For non-zero symmetric-key privacy algorithms, the privacy algorithm
 229 must be specified in
 230 .Fa sessp-\*[Gt]cipher ,
 231 the key length in
 232 .Fa sessp-\*[Gt]keylen ,
 233 and the key value in the octets addressed by
 234 .Fa sessp-\*[Gt]key .
 235 .Pp
 236 For keyed one-way hash algorithms, the one-way hash must be specified
 237 in
 238 .Fa sessp-\*[Gt]mac ,
 239 the key length in
 240 .Fa sessp-\*[Gt]mackey ,
 241 and the key value in the octets addressed by
 242 .Fa sessp-\*[Gt]mackeylen .
 243 .\"
 244 .Pp
 245 Support for a specific combination of fused privacy  and
 246 integrity-check algorithms depends on whether the underlying
 247 hardware supports that combination.
 248 Not all combinations are supported
 249 by all hardware, even if the hardware supports each operation as a
 250 stand-alone non-fused operation.
 251 .It Dv CIOCCRYPT Fa struct crypt_op *cr_op
 252 .Bd -literal
 253 struct crypt_op {
 254     u_int32_t ses;
 255     u_int16_t op;       /* e.g. COP_ENCRYPT */
 256     u_int16_t flags;
 257     u_int len;
 258     caddr_t src, dst;
 259     caddr_t mac;                /* must be large enough for result */
 260     caddr_t iv;
 261 };
 262
 263 .Ed
 264 Request a symmetric-key (or hash) operation.
 265 The file descriptor argument to
 266 .Xr ioctl 2
 267 must have been bound to a valid session.
 268 To encrypt, set
 269 .Fa cr_op-\*[Gt]op
 270 to
 271 .Dv COP_ENCRYPT .
 272 To decrypt, set
 273 .Fa cr_op-\*[Gt]op
 274 to
 275 .Dv COP_DECRYPT .
 276 The field
 277 .Fa cr_op-\*[Gt]len
 278 supplies the length of the input buffer; the fields
 279 .Fa cr_op-\*[Gt]src ,
 280 .Fa cr_op-\*[Gt]dst ,
 281 .Fa cr_op-\*[Gt]mac ,
 282 .Fa cr_op-\*[Gt]iv
 283 supply the addresses of the input buffer, output buffer,
 284 one-way hash, and initialization vector, respectively.
 285 .It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead
 286 .Bd -literal
 287 struct crypt_aead {
 288     u_int32_t ses;
 289     u_int16_t op;       /* e.g. COP_ENCRYPT */
 290     u_int16_t flags;
 291     u_int len;
 292     u_int aadlen;
 293     u_int ivlen;
 294     caddr_t src, dst;
 295     caddr_t aad;
 296     caddr_t tag;                /* must be large enough for result */
 297     caddr_t iv;
 298 };
 299
 300 .Ed
 301 The
 302 .Dv CIOCCRYPTAEAD
 303 is similar to the
 304 .Dv CIOCCRYPT
 305 but provides additional data in
 306 .Fa cr_aead-\*[Gt]aad
 307 to include in the authentication mode.
 308 .It Dv CIOCFSESSION Fa u_int32_t ses_id
 309 Destroys the /dev/crypto session associated with the file-descriptor
 310 argument.
 311 .It Dv CIOCNFSESSION Fa struct crypt_sfop *sfop ;
 312 .Bd -literal
 313 struct crypt_sfop {
 314     size_t count;
 315     u_int32_t *sesid;
 316 };
 317
 318 .Ed
 319 Destroys the
 320 .Fa sfop-\*[Gt]count
 321 sessions specified by the
 322 .Fa sfop
 323 array of session identifiers.
 324 .El
 325 .\"
 326 .Sh ASYMMETRIC-KEY OPERATION
 327 .Ss Asymmetric-key algorithms
 328 Contingent upon hardware support, the following asymmetric
 329 (public-key/private-key; or key-exchange subroutine) operations may
 330 also be available:
 331 .Pp
 332 .Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact
 333 .It Em "Algorithm" Ta "Input parameter" Ta "Output parameter"
 334 .It Em " " Ta "Count" Ta "Count"
 335 .It Dv CRK_MOD_EXP Ta 3 Ta 1
 336 .It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1
 337 .It Dv CRK_DSA_SIGN Ta 5 Ta 2
 338 .It Dv CRK_DSA_VERIFY Ta 7 Ta 0
 339 .It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1
 340 .El
 341 .Pp
 342 See below for discussion of the input and output parameter counts.
 343 .Ss Asymmetric-key commands
 344 .Bl -tag -width CIOCKEY
 345 .It Dv CIOCASYMFEAT Fa int *feature_mask
 346 Returns a bitmask of supported asymmetric-key operations.
 347 Each of the above-listed asymmetric operations is present
 348 if and only if the bit position numbered by the code for that operation
 349 is set.
 350 For example,
 351 .Dv CRK_MOD_EXP
 352 is available if and only if the bit
 353 .Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EXP
 354 is set.
 355 .It Dv CIOCKEY Fa struct crypt_kop *kop
 356 .Bd -literal
 357 struct crypt_kop {
 358     u_int crk_op;               /* e.g. CRK_MOD_EXP */
 359     u_int crk_status;           /* return status */
 360     u_short crk_iparams;        /* # of input params */
 361     u_short crk_oparams;        /* # of output params */
 362     u_int crk_pad1;
 363     struct crparam crk_param[CRK_MAXPARAM];
 364 };
 365
 366 /* Bignum parameter, in packed bytes. */
 367 struct crparam {
 368     void * crp_p;
 369     u_int crp_nbits;
 370 };
 371
 372 .Ed
 373 Performs an asymmetric-key operation from the list above.
 374 The specific operation is supplied in
 375 .Fa kop-\*[Gt]crk_op ;
 376 final status for the operation is returned in
 377 .Fa kop-\*[Gt]crk_status .
 378 The number of input arguments and the number of output arguments
 379 is specified in
 380 .Fa kop-\*[Gt]crk_iparams
 381 and
 382 .Fa kop-\*[Gt]crk_iparams ,
 383 respectively.
 384 The field
 385 .Fa crk_param[]
 386 must be filled in with exactly
 387 .Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams
 388 arguments, each encoded as a
 389 .Fa struct crparam
 390 (address, bitlength) pair.
 391 .Pp
 392 The semantics of these arguments are currently undocumented.
 393 .El
 394 .Sh SEE ALSO
 395 .Xr aesni 4 ,
 396 .Xr hifn 4 ,
 397 .Xr ipsec 4 ,
 398 .Xr padlock 4 ,
 399 .Xr safe 4 ,
 400 .Xr ubsec 4 ,
 401 .Xr crypto 7 ,
 402 .Xr geli 8 ,
 403 .Xr crypto 9
 404 .Sh HISTORY
 405 The
 406 .Nm
 407 driver first appeared in
 408 .Ox 3.0 .
 409 The
 410 .Nm
 411 driver was imported to
 412 .Fx 5.0 .
 413 .Sh BUGS
 414 Error checking and reporting is weak.
 415 .Pp
 416 The values specified for symmetric-key key sizes to
 417 .Dv CIOCGSESSION
 418 must exactly match the values expected by
 419 .Xr opencrypto 9 .
 420 The output buffer and MAC buffers supplied to
 421 .Dv CIOCCRYPT
 422 must follow whether privacy or integrity algorithms were specified for
 423 session: if you request a
 424 .No non- Ns Dv NULL
 425 algorithm, you must supply a suitably-sized buffer.
 426 .Pp
 427 The scheme for passing arguments for asymmetric requests is baroque.
 428 .Pp
 429 The naming inconsistency between
 430 .Dv CRIOGET
 431 and the various
 432 .Dv CIOC Ns \&*
 433 names is an unfortunate historical artifact.