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