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 April 12, 2021
  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 the
  97 .Ic kern.cryptodevallowsoft
  98 .Xr sysctl 8
  99 variable.
 100 If this variable is zero,
 101 then user-mode sessions are only permitted to use cryptography coprocessors.
 102 .Sh THEORY OF OPERATION
 103 Use of the device requires a basic series of steps:
 104 .Bl -enum
 105 .It
 106 Open the
 107 .Pa /dev/crypto
 108 device.
 109 .It
 110 Create a session with
 111 .Dv CIOCGSESSION
 112 or
 113 .Dv CIOCGSESSION2 .
 114 Applications will require at least one symmetric session.
 115 Since cipher and MAC keys are tied to sessions, many
 116 applications will require more.
 117 .It
 118 Submit requests, synchronously with
 119 .Dv CIOCCRYPT
 120 or
 121 .Dv CIOCCRYPTAEAD .
 122 .It
 123 Optionally destroy a session with
 124 .Dv CIOCFSESSION .
 125 .It
 126 Close the
 127 .Pa /dev/crypto
 128 device.
 129 This will automatically close any remaining sessions associated with the
 130 file desriptor.
 131 .El
 132 .Sh SYMMETRIC-KEY OPERATION
 133 .Nm cryptodev
 134 provides a context-based API
 135 to traditional symmetric-key encryption (or privacy) algorithms,
 136 keyed and unkeyed one-way hash (HMAC and MAC) algorithms,
 137 encrypt-then-authenticate (ETA) fused operations,
 138 and authenticated encryption with additional data (AEAD) operations.
 139 For ETA operations,
 140 drivers perform both a privacy algorithm and an integrity-check
 141 algorithm in a single pass over the data: either a fused
 142 encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
 143 Similarly, for AEAD operations,
 144 drivers perform either an encrypt/MAC-generate operation
 145 or a MAC-verify/decrypt operation.
 146 .Pp
 147 The algorithm(s) and key(s) to use are specified when a session is
 148 created.
 149 Individual requests are able to specify per-request initialization vectors
 150 or nonces.
 151 .Ss Algorithms
 152 For a list of supported algorithms, see
 153 .Xr crypto 7 .
 154 .Ss IOCTL Request Descriptions
 155 .\"
 156 .Bl -tag -width CIOCGSESSION
 157 .\"
 158 .It Dv CIOCFINDDEV Fa struct crypt_find_op *fop
 159 .Bd -literal
 160 struct crypt_find_op {
 161     int     crid;       /* driver id + flags */
 162     char    name[32];   /* device/driver name */
 163 };
 164
 165 .Ed
 166 If
 167 .Fa crid
 168 is -1, then find the driver named
 169 .Fa name
 170 and return the id in
 171 .Fa crid .
 172 If
 173 .Fa crid
 174 is not -1, return the name of the driver with
 175 .Fa crid
 176 in
 177 .Fa name .
 178 In either case, if the driver is not found,
 179 .Dv ENOENT
 180 is returned.
 181 .It Dv CIOCGSESSION Fa struct session_op *sessp
 182 .Bd -literal
 183 struct session_op {
 184     uint32_t cipher;    /* e.g. CRYPTO_AES_CBC */
 185     uint32_t mac;       /* e.g. CRYPTO_SHA2_256_HMAC */
 186
 187     uint32_t keylen;    /* cipher key */
 188     const void *key;
 189     int mackeylen;      /* mac key */
 190     const void *mackey;
 191
 192     uint32_t ses;       /* returns: ses # */
 193 };
 194
 195 .Ed
 196 Create a new cryptographic session on a file descriptor for the device;
 197 that is, a persistent object specific to the chosen
 198 privacy algorithm, integrity algorithm, and keys specified in
 199 .Fa sessp .
 200 The special value 0 for either privacy or integrity
 201 is reserved to indicate that the indicated operation (privacy or integrity)
 202 is not desired for this session.
 203 ETA sessions specify both privacy and integrity algorithms.
 204 AEAD sessions specify only a privacy algorithm.
 205 .Pp
 206 Multiple sessions may be bound to a single file descriptor.
 207 The session ID returned in
 208 .Fa sessp-\*[Gt]ses
 209 is supplied as a required field in the operation structure
 210 .Fa crypt_op
 211 for future encryption or hashing requests.
 212 .\" .Pp
 213 .\" This implementation will never return a session ID of 0 for a successful
 214 .\" creation of a session, which is a
 215 .\" .Nx
 216 .\" extension.
 217 .Pp
 218 For non-zero privacy algorithms, the privacy algorithm
 219 must be specified in
 220 .Fa sessp-\*[Gt]cipher ,
 221 the key length in
 222 .Fa sessp-\*[Gt]keylen ,
 223 and the key value in the octets addressed by
 224 .Fa sessp-\*[Gt]key .
 225 .Pp
 226 For keyed one-way hash algorithms, the one-way hash must be specified
 227 in
 228 .Fa sessp-\*[Gt]mac ,
 229 the key length in
 230 .Fa sessp-\*[Gt]mackey ,
 231 and the key value in the octets addressed by
 232 .Fa sessp-\*[Gt]mackeylen .
 233 .\"
 234 .Pp
 235 Support for a specific combination of fused privacy and
 236 integrity-check algorithms depends on whether the underlying
 237 hardware supports that combination.
 238 Not all combinations are supported
 239 by all hardware, even if the hardware supports each operation as a
 240 stand-alone non-fused operation.
 241 .It Dv CIOCGSESSION2 Fa struct session2_op *sessp
 242 .Bd -literal
 243 struct session2_op {
 244     uint32_t cipher;    /* e.g. CRYPTO_AES_CBC */
 245     uint32_t mac;       /* e.g. CRYPTO_SHA2_256_HMAC */
 246
 247     uint32_t keylen;    /* cipher key */
 248     const void *key;
 249     int mackeylen;      /* mac key */
 250     const void *mackey;
 251
 252     uint32_t ses;       /* returns: ses # */
 253     int crid;           /* driver id + flags (rw) */
 254     int pad[4];         /* for future expansion */
 255 };
 256
 257 .Ed
 258 This request is similar to CIOGSESSION except that
 259 .Fa sessp-\*[Gt]crid
 260 requests either a specific crypto device or a class of devices (software vs
 261 hardware).
 262 The
 263 .Fa sessp-\*[Gt]pad
 264 field must be initialized to zero.
 265 .It Dv CIOCCRYPT Fa struct crypt_op *cr_op
 266 .Bd -literal
 267 struct crypt_op {
 268     uint32_t ses;
 269     uint16_t op;        /* e.g. COP_ENCRYPT */
 270     uint16_t flags;
 271     u_int len;
 272     const void *src;
 273     void *dst;
 274     void *mac;          /* must be large enough for result */
 275     const void *iv;
 276 };
 277
 278 .Ed
 279 Request an encryption/decryption (or hash) operation.
 280 To encrypt, set
 281 .Fa cr_op-\*[Gt]op
 282 to
 283 .Dv COP_ENCRYPT .
 284 To decrypt, set
 285 .Fa cr_op-\*[Gt]op
 286 to
 287 .Dv COP_DECRYPT .
 288 The field
 289 .Fa cr_op-\*[Gt]len
 290 supplies the length of the input buffer; the fields
 291 .Fa cr_op-\*[Gt]src ,
 292 .Fa cr_op-\*[Gt]dst ,
 293 .Fa cr_op-\*[Gt]mac ,
 294 .Fa cr_op-\*[Gt]iv
 295 supply the addresses of the input buffer, output buffer,
 296 one-way hash, and initialization vector, respectively.
 297 .Pp
 298 If a session is using either fused encrypt-then-authenticate or
 299 an AEAD algorithm,
 300 decryption operations require the associated hash as an input.
 301 If the hash is incorrect, the
 302 operation will fail with
 303 .Dv EBADMSG
 304 and the output buffer will remain unchanged.
 305 .It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead
 306 .Bd -literal
 307 struct crypt_aead {
 308     uint32_t ses;
 309     uint16_t op;        /* e.g. COP_ENCRYPT */
 310     uint16_t flags;
 311     u_int len;
 312     u_int aadlen;
 313     u_int ivlen;
 314     const void *src;
 315     void *dst;
 316     const void *aad;    /* additional authenticated data */
 317     void *tag;          /* must fit for chosen TAG length */
 318     const void *iv;
 319 };
 320
 321 .Ed
 322 The
 323 .Dv CIOCCRYPTAEAD
 324 is similar to the
 325 .Dv CIOCCRYPT
 326 but provides additional data in
 327 .Fa cr_aead-\*[Gt]aad
 328 to include in the authentication mode.
 329 .It Dv CIOCFSESSION Fa u_int32_t ses_id
 330 Destroys the session identified by
 331 .Fa ses_id .
 332 .El
 333 .Sh SEE ALSO
 334 .Xr aesni 4 ,
 335 .Xr hifn 4 ,
 336 .Xr ipsec 4 ,
 337 .Xr padlock 4 ,
 338 .Xr safe 4 ,
 339 .Xr crypto 7 ,
 340 .Xr geli 8 ,
 341 .Xr crypto 9
 342 .Sh HISTORY
 343 The
 344 .Nm
 345 driver first appeared in
 346 .Ox 3.0 .
 347 The
 348 .Nm
 349 driver was imported to
 350 .Fx 5.0 .
 351 .Sh BUGS
 352 Error checking and reporting is weak.
 353 .Pp
 354 The values specified for symmetric-key key sizes to
 355 .Dv CIOCGSESSION
 356 must exactly match the values expected by
 357 .Xr opencrypto 9 .
 358 The output buffer and MAC buffers supplied to
 359 .Dv CIOCCRYPT
 360 must follow whether privacy or integrity algorithms were specified for
 361 session: if you request a
 362 .No non- Ns Dv NULL
 363 algorithm, you must supply a suitably-sized buffer.