share/man/man9/crypto_session.9

   1 .\" Copyright (c) 2020, Chelsio Inc
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions are met:
   5 .\"
   6 .\" 1. Redistributions of source code must retain the above copyright notice,
   7 .\"    this list of conditions and the following disclaimer.
   8 .\"
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" 3. Neither the name of the Chelsio Inc nor the names of its
  14 .\"    contributors may be used to endorse or promote products derived from
  15 .\"    this software without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  18 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
  21 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 .\" POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .\" * Other names and brands may be claimed as the property of others.
  30 .\"
  31 .\" $FreeBSD$
  32 .\"
  33 .Dd June 22, 2020
  34 .Dt CRYPTO_SESSION 9
  35 .Os
  36 .Sh NAME
  37 .Nm crypto_session
  38 .Nd state used for symmetric cryptographic services
  39 .Sh SYNOPSIS
  40 .In opencrypto/cryptodev.h
  41 .Ft struct auth_hash *
  42 .Fn crypto_auth_hash "const struct crypto_session_params *csp"
  43 .Ft struct enc_xform *
  44 .Fn crypto_cipher "const struct crypto_session_params *csp"
  45 .Ft const struct crypto_session_params *
  46 .Fn crypto_get_params "crypto_session_t cses"
  47 .Ft int
  48 .Fo crypto_newsession
  49 .Fa "crypto_session_t *cses"
  50 .Fa "const struct crypto_session_params *csp"
  51 .Fa "int crid"
  52 .Fc
  53 .Ft int
  54 .Fn crypto_freesession "crypto_session_t cses"
  55 .Sh DESCRIPTION
  56 Symmetric cryptographic operations in the kernel are associated with
  57 cryptographic sessions.
  58 Sessions hold state shared across multiple requests.
  59 Active sessions are associated with a single cryptographic driver.
  60 .Pp
  61 The
  62 .Vt crypto_session_t
  63 type represents an opaque reference to an active session.
  64 Session objects are allocated and managed by the cryptographic
  65 framework.
  66 .Pp
  67 New sessions are created by
  68 .Fn crypto_newsession .
  69 .Fa csp
  70 describes various parameters associated with the new session such as
  71 the algorithms to use and any session-wide keys.
  72 .Fa crid
  73 can be used to request either a specific cryptographic driver or
  74 classes of drivers.
  75 For the latter case,
  76 .Fa crid
  77 should be set to a mask of the following values:
  78 .Bl -tag -width "CRYPTOCAP_F_HARDWARE"
  79 .It Dv CRYPTOCAP_F_HARDWARE
  80 Request hardware drivers.
  81 Hardware drivers do not use the host CPU to perform operations.
  82 Typically, a separate co-processor performs the operations asynchronously.
  83 .It Dv CRYPTOCAP_F_SOFTWARE
  84 Request software drivers.
  85 Software drivers use the host CPU to perform operations.
  86 The kernel includes a simple, yet portable implementation of each supported
  87 algorithm in the
  88 .Xr cryptosoft 4
  89 driver.
  90 Additional software drivers may also be available on architectures which
  91 provide instructions designed to accelerate cryptographic operations.
  92 .El
  93 .Pp
  94 If both hardware and software drivers are requested,
  95 hardware drivers are preferred over software drivers.
  96 Accelerated software drivers are preferred over the baseline software driver.
  97 If multiple hardware drivers are available,
  98 the framework will distribute sessions across these drivers in a round-robin
  99 fashion.
 100 .Pp
 101 On success,
 102 .Fn crypto_newsession
 103 saves a reference to the newly created session in
 104 .Fa cses .
 105 .Pp
 106 .Fn crypto_freesession
 107 is used to free the resources associated with the session
 108 .Fa cses .
 109 .Pp
 110 .Fn crypto_auth_hash
 111 returns a structure describing the baseline software implementation of an
 112 authentication algorithm requested by
 113 .Fa csp .
 114 If
 115 .Fa csp
 116 does not specify an authentication algorithm,
 117 or requests an invalid algorithm,
 118 .Dv NULL
 119 is returned.
 120 .Pp
 121 .Fn crypto_cipher
 122 returns a structure describing the baseline software implementation of an
 123 encryption algorithm requested by
 124 .Fa csp .
 125 If
 126 .Fa csp
 127 does not specify an encryption algorithm,
 128 or requests an invalid algorithm,
 129 .Dv NULL
 130 is returned.
 131 .Pp
 132 .Fn crypto_get_params
 133 returns a pointer to the session parameters used by
 134 .Fa cses .
 135 .Ss Session Parameters
 136 Session parameters are used to describe the cryptographic operations
 137 performed by cryptographic requests.
 138 Parameters are stored in an instance of
 139 .Vt struct crypto_session_params .
 140 When initializing parameters to pass to
 141 .Fn crypto_newsession ,
 142 the entire structure should first be zeroed.
 143 Needed fields should then be set leaving unused fields as zero.
 144 This structure contains the following fields:
 145 .Bl -tag -width csp_cipher_klen
 146 .It Fa csp_mode
 147 Type of operation to perform.
 148 This field must be set to one of the following:
 149 .Bl -tag -width CSP_MODE_COMPRESS
 150 .It Dv CSP_MODE_COMPRESS
 151 Compress or decompress request payload.
 152 .Pp
 153 The compression algorithm is specified in
 154 .Fa csp_cipher_alg .
 155 .It Dv CSP_MODE_CIPHER
 156 Encrypt or decrypt request payload.
 157 .Pp
 158 The encryption algorithm is specified in
 159 .Fa csp_cipher_alg .
 160 .It Dv CSP_MODE_DIGEST
 161 Compute or verify a digest, or hash, of request payload.
 162 .Pp
 163 The authentication algorithm is specified in
 164 .Fa csp_auth_alg .
 165 .It Dv CSP_MODE_AEAD
 166 Authenticated encryption with additional data.
 167 Decryption operations require the digest, or tag,
 168 and fail if it does not match.
 169 .Pp
 170 The AEAD algorithm is specified in
 171 .Fa csp_cipher_alg .
 172 .It Dv CSP_MODE_ETA
 173 Encrypt-then-Authenticate.
 174 In this mode, encryption operations encrypt the payload and then
 175 compute an authentication digest over the request additional authentication
 176 data followed by the encrypted payload.
 177 Decryption operations fail without decrypting the data if the provided digest
 178 does not match.
 179 .Pp
 180 The encryption algorithm is specified in
 181 .Fa csp_cipher_alg
 182 and the authentication algorithm is specified in
 183 .Fa csp_auth_alg .
 184 .El
 185 .It Fa csp_flags
 186 A mask of optional driver features.
 187 Drivers will only attach to a session if they support all of the
 188 requested features.
 189 .Bl -tag -width CSP_F_SEPARATE_OUTPUT
 190 .It Dv CSP_F_SEPARATE_OUTPUT
 191 Support requests that use separate input and output buffers.
 192 Sessions with this flag set permit requests with either a single buffer
 193 that is modified in-place, or requests with separate input and output
 194 buffers.
 195 Sessions without this flag only permit requests with a single buffer that
 196 is modified in-place.
 197 .It Dv CSP_F_SEPARATE_AAD
 198 Support requests that use a separate buffer for AAD rather than providing
 199 AAD as a region in the input buffer.
 200 Sessions with this flag set permit requests with AAD passed in either in
 201 a region of the input buffer or in a single, virtually-contiguous buffer.
 202 Sessions without this flag only permit requests with AAD passed in as
 203 a region in the input buffer.
 204 .It Dv CSP_F_ESN
 205 Support requests that use a separate buffer for IPsec ESN (Extended Sequence
 206 Numbers).
 207 .Pp
 208 Sessions with this flag set permit requests with IPsec ESN passed in special
 209 buffer.
 210 It is required for IPsec ESN support of encrypt and authenticate mode where
 211 the high-order 32 bits of the sequence number are appended after the Next
 212 Header (RFC 4303).
 213 .El
 214 .It Fa csp_ivlen
 215 If either the cipher or authentication algorithms require an explicit
 216 initialization vector (IV) or nonce,
 217 this specifies the length in bytes.
 218 All requests for a session use the same IV length.
 219 .It Fa csp_cipher_alg
 220 Encryption or compression algorithm.
 221 .It Fa csp_cipher_klen
 222 Length of encryption or decryption key in bytes.
 223 All requests for a session use the same key length.
 224 .It Fa csp_cipher_key
 225 Pointer to encryption or decryption key.
 226 If all requests for a session use request-specific keys,
 227 this field should be left as
 228 .Dv NULL .
 229 This pointer and associated key must remain valid for the duration of the
 230 crypto session.
 231 .It Fa csp_auth_alg
 232 Authentication algorithm.
 233 .It Fa csp_auth_klen
 234 Length of authentication key in bytes.
 235 If the authentication algorithm does not use a key,
 236 this field should be left as zero.
 237 .It Fa csp_auth_key
 238 Pointer to the authentication key.
 239 If all requests for a session use request-specific keys,
 240 this field should be left as
 241 .Dv NULL .
 242 This pointer and associated key must remain valid for the duration of the
 243 crypto session.
 244 .It Fa csp_auth_mlen
 245 The length in bytes of the digest.
 246 If zero, the full length of the digest is used.
 247 If non-zero, the first
 248 .Fa csp_auth_mlen
 249 bytes of the digest are used.
 250 .El
 251 .Sh RETURN VALUES
 252 .Fn crypto_newsession
 253 returns a non-zero value if an error occurs or zero on success.
 254 .Pp
 255 .Fn crypto_auth_hash
 256 and
 257 .Fn crypto_cipher
 258 return
 259 .Dv NULL
 260 if the request is valid or a pointer to a structure on success.
 261 .Sh SEE ALSO
 262 .Xr crypto 7 ,
 263 .Xr crypto 9 ,
 264 .Xr crypto_request 9
 265 .Sh BUGS
 266 The current implementation of
 267 .Nm crypto_freesession
 268 does not provide a way for the caller to know that there are no other
 269 references to the keys stored in the session's associated parameters.
 270 This function should probably sleep until any in-flight cryptographic
 271 operations associated with the session are completed.