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-2021 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 .\" Portions of this documentation were written by Ararat River
  12 .\" Consulting, LLC under sponsorship of the FreeBSD Foundation.
  13 .\"
  14 .\" This code is derived from software contributed to The NetBSD Foundation
  15 .\" by Coyote Point Systems, Inc.
  16 .\"
  17 .\" Redistribution and use in source and binary forms, with or without
  18 .\" modification, are permitted provided that the following conditions
  19 .\" are met:
  20 .\" 1. Redistributions of source code must retain the above copyright
  21 .\"    notice, this list of conditions and the following disclaimer.
  22 .\" 2. Redistributions in binary form must reproduce the above copyright
  23 .\"    notice, this list of conditions and the following disclaimer in the
  24 .\"    documentation and/or other materials provided with the distribution.
  25 .\"
  26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  29 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  36 .\" POSSIBILITY OF SUCH DAMAGE.
  37 .\"
  38 .\"
  39 .\"
  40 .\" Copyright (c) 2004
  41 .\"     Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved.
  42 .\"
  43 .\" Redistribution and use in source and binary forms, with or without
  44 .\" modification, are permitted provided that the following conditions
  45 .\" are met:
  46 .\" 1. Redistributions of source code must retain the above copyright
  47 .\"    notice, this list of conditions and the following disclaimer.
  48 .\" 2. Redistributions in binary form must reproduce the above copyright
  49 .\"    notice, this list of conditions and the following disclaimer in the
  50 .\"    documentation and/or other materials provided with the distribution.
  51 .\"
  52 .\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND
  53 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  54 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  55 .\" ARE DISCLAIMED.  IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD
  56 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  57 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  58 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  59 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  60 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  61 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
  62 .\" THE POSSIBILITY OF SUCH DAMAGE.
  63 .\"
  64 .\" $FreeBSD$
  65 .\"
  66 .Dd October 6, 2021
  67 .Dt CRYPTO 4
  68 .Os
  69 .Sh NAME
  70 .Nm crypto ,
  71 .Nm cryptodev
  72 .Nd user-mode access to hardware-accelerated cryptography
  73 .Sh SYNOPSIS
  74 .Cd device crypto
  75 .Cd device cryptodev
  76 .Pp
  77 .In sys/ioctl.h
  78 .In sys/time.h
  79 .In crypto/cryptodev.h
  80 .Sh DESCRIPTION
  81 The
  82 .Nm
  83 driver gives user-mode applications access to hardware-accelerated
  84 cryptographic transforms as implemented by the
  85 .Xr crypto 9
  86 in-kernel interface.
  87 .Pp
  88 The
  89 .Pa /dev/crypto
  90 special device provides an
  91 .Xr ioctl 2
  92 based interface.
  93 User-mode applications open the special device and
  94 then issue
  95 .Xr ioctl 2
  96 calls on the descriptor.
  97 User-mode access to
  98 .Pa /dev/crypto
  99 is controlled by the
 100 .Ic kern.cryptodevallowsoft
 101 .Xr sysctl 8
 102 variable.
 103 If this variable is zero,
 104 then user-mode sessions are only permitted to use cryptography coprocessors.
 105 .Sh THEORY OF OPERATION
 106 Use of the device requires a basic series of steps:
 107 .Bl -enum
 108 .It
 109 Open the
 110 .Pa /dev/crypto
 111 device.
 112 .It
 113 Create a session with
 114 .Dv CIOCGSESSION
 115 or
 116 .Dv CIOCGSESSION2 .
 117 Applications will require at least one symmetric session.
 118 Since cipher and MAC keys are tied to sessions, many
 119 applications will require more.
 120 .It
 121 Submit requests, synchronously with
 122 .Dv CIOCCRYPT
 123 or
 124 .Dv CIOCCRYPTAEAD .
 125 .It
 126 Optionally destroy a session with
 127 .Dv CIOCFSESSION .
 128 .It
 129 Close the
 130 .Pa /dev/crypto
 131 device.
 132 This will automatically close any remaining sessions associated with the
 133 file desriptor.
 134 .El
 135 .Sh SYMMETRIC-KEY OPERATION
 136 .Nm cryptodev
 137 provides a context-based API
 138 to traditional symmetric-key encryption (or privacy) algorithms,
 139 keyed and unkeyed one-way hash (HMAC and MAC) algorithms,
 140 encrypt-then-authenticate (ETA) fused operations,
 141 and authenticated encryption with additional data (AEAD) operations.
 142 For ETA operations,
 143 drivers perform both a privacy algorithm and an integrity-check
 144 algorithm in a single pass over the data: either a fused
 145 encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
 146 Similarly, for AEAD operations,
 147 drivers perform either an encrypt/MAC-generate operation
 148 or a MAC-verify/decrypt operation.
 149 .Pp
 150 The algorithm(s) and key(s) to use are specified when a session is
 151 created.
 152 Individual requests are able to specify per-request initialization vectors
 153 or nonces.
 154 .Ss Algorithms
 155 For a list of supported algorithms, see
 156 .Xr crypto 7 .
 157 .Ss IOCTL Request Descriptions
 158 .\"
 159 .Bl -tag -width CIOCGSESSION
 160 .\"
 161 .It Dv CIOCFINDDEV Fa struct crypt_find_op *fop
 162 .Bd -literal
 163 struct crypt_find_op {
 164     int     crid;       /* driver id + flags */
 165     char    name[32];   /* device/driver name */
 166 };
 167
 168 .Ed
 169 If
 170 .Fa crid
 171 is -1, then find the driver named
 172 .Fa name
 173 and return the id in
 174 .Fa crid .
 175 If
 176 .Fa crid
 177 is not -1, return the name of the driver with
 178 .Fa crid
 179 in
 180 .Fa name .
 181 In either case, if the driver is not found,
 182 .Dv ENOENT
 183 is returned.
 184 .It Dv CIOCGSESSION Fa struct session_op *sessp
 185 .Bd -literal
 186 struct session_op {
 187     uint32_t cipher;    /* e.g. CRYPTO_AES_CBC */
 188     uint32_t mac;       /* e.g. CRYPTO_SHA2_256_HMAC */
 189
 190     uint32_t keylen;    /* cipher key */
 191     const void *key;
 192     int mackeylen;      /* mac key */
 193     const void *mackey;
 194
 195     uint32_t ses;       /* returns: ses # */
 196 };
 197
 198 .Ed
 199 Create a new cryptographic session on a file descriptor for the device;
 200 that is, a persistent object specific to the chosen
 201 privacy algorithm, integrity algorithm, and keys specified in
 202 .Fa sessp .
 203 The special value 0 for either privacy or integrity
 204 is reserved to indicate that the indicated operation (privacy or integrity)
 205 is not desired for this session.
 206 ETA sessions specify both privacy and integrity algorithms.
 207 AEAD sessions specify only a privacy algorithm.
 208 .Pp
 209 Multiple sessions may be bound to a single file descriptor.
 210 The session ID returned in
 211 .Fa sessp-\*[Gt]ses
 212 is supplied as a required field in the operation structure
 213 .Fa crypt_op
 214 for future encryption or hashing requests.
 215 .\" .Pp
 216 .\" This implementation will never return a session ID of 0 for a successful
 217 .\" creation of a session, which is a
 218 .\" .Nx
 219 .\" extension.
 220 .Pp
 221 For non-zero privacy algorithms, the privacy algorithm
 222 must be specified in
 223 .Fa sessp-\*[Gt]cipher ,
 224 the key length in
 225 .Fa sessp-\*[Gt]keylen ,
 226 and the key value in the octets addressed by
 227 .Fa sessp-\*[Gt]key .
 228 .Pp
 229 For keyed one-way hash algorithms, the one-way hash must be specified
 230 in
 231 .Fa sessp-\*[Gt]mac ,
 232 the key length in
 233 .Fa sessp-\*[Gt]mackey ,
 234 and the key value in the octets addressed by
 235 .Fa sessp-\*[Gt]mackeylen .
 236 .\"
 237 .Pp
 238 Support for a specific combination of fused privacy and
 239 integrity-check algorithms depends on whether the underlying
 240 hardware supports that combination.
 241 Not all combinations are supported
 242 by all hardware, even if the hardware supports each operation as a
 243 stand-alone non-fused operation.
 244 .It Dv CIOCGSESSION2 Fa struct session2_op *sessp
 245 .Bd -literal
 246 struct session2_op {
 247     uint32_t cipher;    /* e.g. CRYPTO_AES_CBC */
 248     uint32_t mac;       /* e.g. CRYPTO_SHA2_256_HMAC */
 249
 250     uint32_t keylen;    /* cipher key */
 251     const void *key;
 252     int mackeylen;      /* mac key */
 253     const void *mackey;
 254
 255     uint32_t ses;       /* returns: ses # */
 256     int crid;           /* driver id + flags (rw) */
 257     int ivlen;          /* length of nonce/IV */
 258     int maclen;         /* length of MAC/tag */
 259     int pad[2];         /* for future expansion */
 260 };
 261
 262 .Ed
 263 This request is similar to CIOGSESSION but adds additional fields.
 264 .Pp
 265 .Fa sessp-\*[Gt]crid
 266 requests either a specific crypto device or a class of devices (software vs
 267 hardware).
 268 .Pp
 269 .Fa sessp-\*[Gt]ivlen
 270 specifies the length of the IV or nonce supplied with each request.
 271 If this field is set to zero, the default IV or nonce length is used.
 272 .Pp
 273 .Fa sessp-\*[Gt]maclen
 274 specifies the length of the MAC or authentication tag supplied or computed by
 275 each request.
 276 If this field is set to zero, the full MAC is used.
 277 .Pp
 278 The
 279 .Fa sessp-\*[Gt]pad
 280 field must be initialized to zero.
 281 .It Dv CIOCCRYPT Fa struct crypt_op *cr_op
 282 .Bd -literal
 283 struct crypt_op {
 284     uint32_t ses;
 285     uint16_t op;        /* e.g. COP_ENCRYPT */
 286     uint16_t flags;
 287     u_int len;
 288     const void *src;
 289     void *dst;
 290     void *mac;          /* must be large enough for result */
 291     const void *iv;
 292 };
 293
 294 .Ed
 295 Request an encryption/decryption (or hash) operation.
 296 To encrypt, set
 297 .Fa cr_op-\*[Gt]op
 298 to
 299 .Dv COP_ENCRYPT .
 300 To decrypt, set
 301 .Fa cr_op-\*[Gt]op
 302 to
 303 .Dv COP_DECRYPT .
 304 The field
 305 .Fa cr_op-\*[Gt]len
 306 supplies the length of the input buffer; the fields
 307 .Fa cr_op-\*[Gt]src ,
 308 .Fa cr_op-\*[Gt]dst ,
 309 .Fa cr_op-\*[Gt]mac ,
 310 .Fa cr_op-\*[Gt]iv
 311 supply the addresses of the input buffer, output buffer,
 312 one-way hash, and initialization vector, respectively.
 313 .Pp
 314 If a session is using either fused encrypt-then-authenticate or
 315 an AEAD algorithm,
 316 decryption operations require the associated hash as an input.
 317 If the hash is incorrect, the
 318 operation will fail with
 319 .Dv EBADMSG
 320 and the output buffer will remain unchanged.
 321 .It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead
 322 .Bd -literal
 323 struct crypt_aead {
 324     uint32_t ses;
 325     uint16_t op;        /* e.g. COP_ENCRYPT */
 326     uint16_t flags;
 327     u_int len;
 328     u_int aadlen;
 329     u_int ivlen;
 330     const void *src;
 331     void *dst;
 332     const void *aad;    /* additional authenticated data */
 333     void *tag;          /* must fit for chosen TAG length */
 334     const void *iv;
 335 };
 336
 337 .Ed
 338 The
 339 .Dv CIOCCRYPTAEAD
 340 is similar to the
 341 .Dv CIOCCRYPT
 342 but provides additional data in
 343 .Fa cr_aead-\*[Gt]aad
 344 to include in the authentication mode.
 345 .It Dv CIOCFSESSION Fa u_int32_t ses_id
 346 Destroys the session identified by
 347 .Fa ses_id .
 348 .El
 349 .Sh SEE ALSO
 350 .Xr aesni 4 ,
 351 .Xr hifn 4 ,
 352 .Xr ipsec 4 ,
 353 .Xr padlock 4 ,
 354 .Xr safe 4 ,
 355 .Xr crypto 7 ,
 356 .Xr geli 8 ,
 357 .Xr crypto 9
 358 .Sh HISTORY
 359 The
 360 .Nm
 361 driver first appeared in
 362 .Ox 3.0 .
 363 The
 364 .Nm
 365 driver was imported to
 366 .Fx 5.0 .
 367 .Sh BUGS
 368 Error checking and reporting is weak.
 369 .Pp
 370 The values specified for symmetric-key key sizes to
 371 .Dv CIOCGSESSION
 372 must exactly match the values expected by
 373 .Xr opencrypto 9 .
 374 The output buffer and MAC buffers supplied to
 375 .Dv CIOCCRYPT
 376 must follow whether privacy or integrity algorithms were specified for
 377 session: if you request a
 378 .No non- Ns Dv NULL
 379 algorithm, you must supply a suitably-sized buffer.