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