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 May 11, 2020
  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 crypto 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 open the special device and
  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 two
  97 .Xr sysctl 8
  98 variables:
  99 .Ic kern.userasymcrypto
 100 and
 101 .Ic kern.cryptodevallowsoft .
 102 .Pp
 103 The
 104 .Nm
 105 device provides two distinct modes of operation: one mode for
 106 symmetric-keyed cryptographic requests and digests, and a second mode for
 107 both asymmetric-key (public-key/private-key) requests and
 108 modular arithmetic (for Diffie-Hellman key exchange and other
 109 cryptographic protocols).
 110 The two modes are described separately below.
 111 .Sh THEORY OF OPERATION
 112 Regardless of whether symmetric-key or asymmetric-key operations are
 113 to be performed, use of the device requires a basic series of steps:
 114 .Bl -enum
 115 .It
 116 Open the
 117 .Pa /dev/crypto
 118 device.
 119 .It
 120 Create a new cryptography file descriptor via
 121 .Dv CRIOGET
 122 to use for all subsequent
 123 .Xr ioctl 2
 124 commands.
 125 .It
 126 Close the
 127 .Pa /dev/crypto
 128 device.
 129 .It
 130 If any symmetric-keyed cryptographic or digest operations will be performed,
 131 create a session with
 132 .Dv CIOCGSESSION .
 133 Most applications will require at least one symmetric session.
 134 Since cipher and MAC keys are tied to sessions, many
 135 applications will require more.
 136 Asymmetric operations do not use sessions.
 137 .It
 138 Submit requests, synchronously with
 139 .Dv CIOCCRYPT
 140 (symmetric),
 141 .Dv CIOCCRYPTAEAD
 142 (symmetric),
 143 or
 144 .Dv CIOCKEY
 145 (asymmetric).
 146 .It
 147 Optionally destroy a session with
 148 .Dv CIOCFSESSION .
 149 .It
 150 Close the cryptography file descriptor with
 151 .Xr close 2 .
 152 This will automatically close any remaining sessions associated with the
 153 file desriptor.
 154 .El
 155 .Sh SYMMETRIC-KEY OPERATION
 156 The symmetric-key operation mode provides a context-based API
 157 to traditional symmetric-key encryption (or privacy) algorithms,
 158 or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms.
 159 The symmetric-key mode also permits encrypt-then-authenticate fused operation,
 160 where the hardware performs both a privacy algorithm and an integrity-check
 161 algorithm in a single pass over the data: either a fused
 162 encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
 163 .Pp
 164 To use symmetric mode, you must first create a session specifying
 165 the algorithm(s) and key(s) to use; then issue encrypt or decrypt
 166 requests against the session.
 167 .Ss Algorithms
 168 For a list of supported algorithms, see
 169 .Xr crypto 7
 170 and
 171 .Xr crypto 9 .
 172 .Ss IOCTL Request Descriptions
 173 .\"
 174 .Bl -tag -width CIOCGSESSION
 175 .\"
 176 .It Dv CRIOGET Fa int *fd
 177 Clone the fd argument to
 178 .Xr ioctl 2 ,
 179 yielding a new file descriptor for the creation of sessions.
 180 .\"
 181 .It Dv CIOCFINDDEV Fa struct crypt_find_op *fop
 182 .Bd -literal
 183 struct crypt_find_op {
 184     int     crid;       /* driver id + flags */
 185     char    name[32];   /* device/driver name */
 186 };
 187
 188 .Ed
 189 If
 190 .Fa crid
 191 is -1, then find the driver named
 192 .Fa name
 193 and return the id in
 194 .Fa crid .
 195 If
 196 .Fa crid
 197 is not -1, return the name of the driver with
 198 .Fa crid
 199 in
 200 .Fa name .
 201 In either case, if the driver is not found,
 202 .Dv ENOENT
 203 is returned.
 204 .It Dv CIOCGSESSION Fa struct session_op *sessp
 205 .Bd -literal
 206 struct session_op {
 207     u_int32_t cipher;   /* e.g. CRYPTO_DES_CBC */
 208     u_int32_t mac;      /* e.g. CRYPTO_MD5_HMAC */
 209
 210     u_int32_t keylen;   /* cipher key */
 211     const void *key;
 212     int mackeylen;      /* mac key */
 213     const void *mackey;
 214
 215     u_int32_t ses;      /* returns: ses # */
 216 };
 217
 218 .Ed
 219 Create a new cryptographic session on a file descriptor for the device;
 220 that is, a persistent object specific to the chosen
 221 privacy algorithm, integrity algorithm, and keys specified in
 222 .Fa sessp .
 223 The special value 0 for either privacy or integrity
 224 is reserved to indicate that the indicated operation (privacy or integrity)
 225 is not desired for this session.
 226 .Pp
 227 Multiple sessions may be bound to a single file descriptor.
 228 The session ID returned in
 229 .Fa sessp-\*[Gt]ses
 230 is supplied as a required field in the symmetric-operation structure
 231 .Fa crypt_op
 232 for future encryption or hashing requests.
 233 .\" .Pp
 234 .\" This implementation will never return a session ID of 0 for a successful
 235 .\" creation of a session, which is a
 236 .\" .Nx
 237 .\" extension.
 238 .Pp
 239 For non-zero symmetric-key privacy algorithms, the privacy algorithm
 240 must be specified in
 241 .Fa sessp-\*[Gt]cipher ,
 242 the key length in
 243 .Fa sessp-\*[Gt]keylen ,
 244 and the key value in the octets addressed by
 245 .Fa sessp-\*[Gt]key .
 246 .Pp
 247 For keyed one-way hash algorithms, the one-way hash must be specified
 248 in
 249 .Fa sessp-\*[Gt]mac ,
 250 the key length in
 251 .Fa sessp-\*[Gt]mackey ,
 252 and the key value in the octets addressed by
 253 .Fa sessp-\*[Gt]mackeylen .
 254 .\"
 255 .Pp
 256 Support for a specific combination of fused privacy and
 257 integrity-check algorithms depends on whether the underlying
 258 hardware supports that combination.
 259 Not all combinations are supported
 260 by all hardware, even if the hardware supports each operation as a
 261 stand-alone non-fused operation.
 262 .It Dv CIOCGSESSION2 Fa struct session2_op *sessp
 263 .Bd -literal
 264 struct session2_op {
 265     u_int32_t cipher;   /* e.g. CRYPTO_DES_CBC */
 266     u_int32_t mac;      /* e.g. CRYPTO_MD5_HMAC */
 267
 268     u_int32_t keylen;   /* cipher key */
 269     const void *key;
 270     int mackeylen;      /* mac key */
 271     const void *mackey;
 272
 273     u_int32_t ses;      /* returns: ses # */
 274     int crid;           /* driver id + flags (rw) */
 275     int pad[4];         /* for future expansion */
 276 };
 277
 278 .Ed
 279 This request is similar to CIOGSESSION except that
 280 .Fa sessp-\*[Gt]crid
 281 requests either a specific crypto device or a class of devices (software vs
 282 hardware).
 283 The
 284 .Fa sessp-\*[Gt]pad
 285 field must be initialized to zero.
 286 .It Dv CIOCCRYPT Fa struct crypt_op *cr_op
 287 .Bd -literal
 288 struct crypt_op {
 289     u_int32_t ses;
 290     u_int16_t op;       /* e.g. COP_ENCRYPT */
 291     u_int16_t flags;
 292     u_int len;
 293     caddr_t src, dst;
 294     caddr_t mac;                /* must be large enough for result */
 295     caddr_t iv;
 296 };
 297
 298 .Ed
 299 Request a symmetric-key (or hash) operation.
 300 To encrypt, set
 301 .Fa cr_op-\*[Gt]op
 302 to
 303 .Dv COP_ENCRYPT .
 304 To decrypt, set
 305 .Fa cr_op-\*[Gt]op
 306 to
 307 .Dv COP_DECRYPT .
 308 The field
 309 .Fa cr_op-\*[Gt]len
 310 supplies the length of the input buffer; the fields
 311 .Fa cr_op-\*[Gt]src ,
 312 .Fa cr_op-\*[Gt]dst ,
 313 .Fa cr_op-\*[Gt]mac ,
 314 .Fa cr_op-\*[Gt]iv
 315 supply the addresses of the input buffer, output buffer,
 316 one-way hash, and initialization vector, respectively.
 317 .Pp
 318 If a session is using either fused encrypt-then-authenticate or
 319 an AEAD algorithm,
 320 decryption operations require the associated hash as an input.
 321 If the hash is incorrect, the
 322 operation will fail with
 323 .Dv EBADMSG
 324 and the output buffer will remain unchanged.
 325 .It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead
 326 .Bd -literal
 327 struct crypt_aead {
 328     u_int32_t ses;
 329     u_int16_t op;       /* e.g. COP_ENCRYPT */
 330     u_int16_t flags;
 331     u_int len;
 332     u_int aadlen;
 333     u_int ivlen;
 334     caddr_t src, dst;
 335     caddr_t aad;
 336     caddr_t tag;                /* must be large enough for result */
 337     caddr_t iv;
 338 };
 339
 340 .Ed
 341 The
 342 .Dv CIOCCRYPTAEAD
 343 is similar to the
 344 .Dv CIOCCRYPT
 345 but provides additional data in
 346 .Fa cr_aead-\*[Gt]aad
 347 to include in the authentication mode.
 348 .It Dv CIOCFSESSION Fa u_int32_t ses_id
 349 Destroys the session identified by
 350 .Fa ses_id .
 351 .El
 352 .\"
 353 .Sh ASYMMETRIC-KEY OPERATION
 354 .Ss Asymmetric-key algorithms
 355 Contingent upon hardware support, the following asymmetric
 356 (public-key/private-key; or key-exchange subroutine) operations may
 357 also be available:
 358 .Pp
 359 .Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact
 360 .It Em "Algorithm" Ta "Input parameter" Ta "Output parameter"
 361 .It Em " " Ta "Count" Ta "Count"
 362 .It Dv CRK_MOD_EXP Ta 3 Ta 1
 363 .It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1
 364 .It Dv CRK_DSA_SIGN Ta 5 Ta 2
 365 .It Dv CRK_DSA_VERIFY Ta 7 Ta 0
 366 .It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1
 367 .El
 368 .Pp
 369 See below for discussion of the input and output parameter counts.
 370 .Ss Asymmetric-key commands
 371 .Bl -tag -width CIOCKEY
 372 .It Dv CIOCASYMFEAT Fa int *feature_mask
 373 Returns a bitmask of supported asymmetric-key operations.
 374 Each of the above-listed asymmetric operations is present
 375 if and only if the bit position numbered by the code for that operation
 376 is set.
 377 For example,
 378 .Dv CRK_MOD_EXP
 379 is available if and only if the bit
 380 .Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EXP
 381 is set.
 382 .It Dv CIOCKEY Fa struct crypt_kop *kop
 383 .Bd -literal
 384 struct crypt_kop {
 385     u_int crk_op;               /* e.g. CRK_MOD_EXP */
 386     u_int crk_status;           /* return status */
 387     u_short crk_iparams;        /* # of input params */
 388     u_short crk_oparams;        /* # of output params */
 389     u_int crk_pad1;
 390     struct crparam crk_param[CRK_MAXPARAM];
 391 };
 392
 393 /* Bignum parameter, in packed bytes. */
 394 struct crparam {
 395     void * crp_p;
 396     u_int crp_nbits;
 397 };
 398
 399 .Ed
 400 Performs an asymmetric-key operation from the list above.
 401 The specific operation is supplied in
 402 .Fa kop-\*[Gt]crk_op ;
 403 final status for the operation is returned in
 404 .Fa kop-\*[Gt]crk_status .
 405 The number of input arguments and the number of output arguments
 406 is specified in
 407 .Fa kop-\*[Gt]crk_iparams
 408 and
 409 .Fa kop-\*[Gt]crk_iparams ,
 410 respectively.
 411 The field
 412 .Fa crk_param[]
 413 must be filled in with exactly
 414 .Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams
 415 arguments, each encoded as a
 416 .Fa struct crparam
 417 (address, bitlength) pair.
 418 .Pp
 419 The semantics of these arguments are currently undocumented.
 420 .El
 421 .Sh SEE ALSO
 422 .Xr aesni 4 ,
 423 .Xr hifn 4 ,
 424 .Xr ipsec 4 ,
 425 .Xr padlock 4 ,
 426 .Xr safe 4 ,
 427 .Xr crypto 7 ,
 428 .Xr geli 8 ,
 429 .Xr crypto 9
 430 .Sh HISTORY
 431 The
 432 .Nm
 433 driver first appeared in
 434 .Ox 3.0 .
 435 The
 436 .Nm
 437 driver was imported to
 438 .Fx 5.0 .
 439 .Sh BUGS
 440 Error checking and reporting is weak.
 441 .Pp
 442 The values specified for symmetric-key key sizes to
 443 .Dv CIOCGSESSION
 444 must exactly match the values expected by
 445 .Xr opencrypto 9 .
 446 The output buffer and MAC buffers supplied to
 447 .Dv CIOCCRYPT
 448 must follow whether privacy or integrity algorithms were specified for
 449 session: if you request a
 450 .No non- Ns Dv NULL
 451 algorithm, you must supply a suitably-sized buffer.
 452 .Pp
 453 The scheme for passing arguments for asymmetric requests is baroque.
 454 .Pp
 455 .Dv CRIOGET
 456 should not exist.
 457 It should be possible to use the
 458 .Dv CIOC Ns \&*
 459 commands directly on a
 460 .Pa /dev/crypto
 461 file descriptor.