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