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.Dd June 22, 2020 32.Dt CRYPTO_SESSION 9 33.Os 34.Sh NAME 35.Nm crypto_session 36.Nd state used for symmetric cryptographic services 37.Sh SYNOPSIS 38.In opencrypto/cryptodev.h 39.Ft struct auth_hash * 40.Fn crypto_auth_hash "const struct crypto_session_params *csp" 41.Ft struct enc_xform * 42.Fn crypto_cipher "const struct crypto_session_params *csp" 43.Ft const struct crypto_session_params * 44.Fn crypto_get_params "crypto_session_t cses" 45.Ft int 46.Fo crypto_newsession 47.Fa "crypto_session_t *cses" 48.Fa "const struct crypto_session_params *csp" 49.Fa "int crid" 50.Fc 51.Ft int 52.Fn crypto_freesession "crypto_session_t cses" 53.Sh DESCRIPTION 54Symmetric cryptographic operations in the kernel are associated with 55cryptographic sessions. 56Sessions hold state shared across multiple requests. 57Active sessions are associated with a single cryptographic driver. 58.Pp 59The 60.Vt crypto_session_t 61type represents an opaque reference to an active session. 62Session objects are allocated and managed by the cryptographic 63framework. 64.Pp 65New sessions are created by 66.Fn crypto_newsession . 67.Fa csp 68describes various parameters associated with the new session such as 69the algorithms to use and any session-wide keys. 70.Fa crid 71can be used to request either a specific cryptographic driver or 72classes of drivers. 73For the latter case, 74.Fa crid 75should be set to a mask of the following values: 76.Bl -tag -width "CRYPTOCAP_F_HARDWARE" 77.It Dv CRYPTOCAP_F_HARDWARE 78Request hardware drivers. 79Hardware drivers do not use the host CPU to perform operations. 80Typically, a separate co-processor performs the operations asynchronously. 81.It Dv CRYPTOCAP_F_SOFTWARE 82Request software drivers. 83Software drivers use the host CPU to perform operations. 84The kernel includes a simple, yet portable implementation of each supported 85algorithm in the 86.Xr cryptosoft 4 87driver. 88Additional software drivers may also be available on architectures which 89provide instructions designed to accelerate cryptographic operations. 90.El 91.Pp 92If both hardware and software drivers are requested, 93hardware drivers are preferred over software drivers. 94Accelerated software drivers are preferred over the baseline software driver. 95If multiple hardware drivers are available, 96the framework will distribute sessions across these drivers in a round-robin 97fashion. 98.Pp 99On success, 100.Fn crypto_newsession 101saves a reference to the newly created session in 102.Fa cses . 103.Pp 104.Fn crypto_freesession 105is used to free the resources associated with the session 106.Fa cses . 107.Pp 108.Fn crypto_auth_hash 109returns a structure describing the baseline software implementation of an 110authentication algorithm requested by 111.Fa csp . 112If 113.Fa csp 114does not specify an authentication algorithm, 115or requests an invalid algorithm, 116.Dv NULL 117is returned. 118.Pp 119.Fn crypto_cipher 120returns a structure describing the baseline software implementation of an 121encryption algorithm requested by 122.Fa csp . 123If 124.Fa csp 125does not specify an encryption algorithm, 126or requests an invalid algorithm, 127.Dv NULL 128is returned. 129.Pp 130.Fn crypto_get_params 131returns a pointer to the session parameters used by 132.Fa cses . 133.Ss Session Parameters 134Session parameters are used to describe the cryptographic operations 135performed by cryptographic requests. 136Parameters are stored in an instance of 137.Vt struct crypto_session_params . 138When initializing parameters to pass to 139.Fn crypto_newsession , 140the entire structure should first be zeroed. 141Needed fields should then be set leaving unused fields as zero. 142This structure contains the following fields: 143.Bl -tag -width csp_cipher_klen 144.It Fa csp_mode 145Type of operation to perform. 146This field must be set to one of the following: 147.Bl -tag -width CSP_MODE_COMPRESS 148.It Dv CSP_MODE_COMPRESS 149Compress or decompress request payload. 150.Pp 151The compression algorithm is specified in 152.Fa csp_cipher_alg . 153.It Dv CSP_MODE_CIPHER 154Encrypt or decrypt request payload. 155.Pp 156The encryption algorithm is specified in 157.Fa csp_cipher_alg . 158.It Dv CSP_MODE_DIGEST 159Compute or verify a digest, or hash, of request payload. 160.Pp 161The authentication algorithm is specified in 162.Fa csp_auth_alg . 163.It Dv CSP_MODE_AEAD 164Authenticated encryption with additional data. 165Decryption operations require the digest, or tag, 166and fail if it does not match. 167.Pp 168The AEAD algorithm is specified in 169.Fa csp_cipher_alg . 170.It Dv CSP_MODE_ETA 171Encrypt-then-Authenticate. 172In this mode, encryption operations encrypt the payload and then 173compute an authentication digest over the request additional authentication 174data followed by the encrypted payload. 175Decryption operations fail without decrypting the data if the provided digest 176does not match. 177.Pp 178The encryption algorithm is specified in 179.Fa csp_cipher_alg 180and the authentication algorithm is specified in 181.Fa csp_auth_alg . 182.El 183.It Fa csp_flags 184A mask of optional driver features. 185Drivers will only attach to a session if they support all of the 186requested features. 187.Bl -tag -width CSP_F_SEPARATE_OUTPUT 188.It Dv CSP_F_SEPARATE_OUTPUT 189Support requests that use separate input and output buffers. 190Sessions with this flag set permit requests with either a single buffer 191that is modified in-place, or requests with separate input and output 192buffers. 193Sessions without this flag only permit requests with a single buffer that 194is modified in-place. 195.It Dv CSP_F_SEPARATE_AAD 196Support requests that use a separate buffer for AAD rather than providing 197AAD as a region in the input buffer. 198Sessions with this flag set permit requests with AAD passed in either in 199a region of the input buffer or in a single, virtually-contiguous buffer. 200Sessions without this flag only permit requests with AAD passed in as 201a region in the input buffer. 202.It Dv CSP_F_ESN 203Support requests that use a separate buffer for IPsec ESN (Extended Sequence 204Numbers). 205.Pp 206Sessions with this flag set permit requests with IPsec ESN passed in special 207buffer. 208It is required for IPsec ESN support of encrypt and authenticate mode where 209the high-order 32 bits of the sequence number are appended after the Next 210Header (RFC 4303). 211.El 212.It Fa csp_ivlen 213If either the cipher or authentication algorithms require an explicit 214initialization vector (IV) or nonce, 215this specifies the length in bytes. 216All requests for a session use the same IV length. 217.It Fa csp_cipher_alg 218Encryption or compression algorithm. 219.It Fa csp_cipher_klen 220Length of encryption or decryption key in bytes. 221All requests for a session use the same key length. 222.It Fa csp_cipher_key 223Pointer to encryption or decryption key. 224If all requests for a session use request-specific keys, 225this field should be left as 226.Dv NULL . 227This pointer and associated key must remain valid for the duration of the 228crypto session. 229.It Fa csp_auth_alg 230Authentication algorithm. 231.It Fa csp_auth_klen 232Length of authentication key in bytes. 233If the authentication algorithm does not use a key, 234this field should be left as zero. 235.It Fa csp_auth_key 236Pointer to the authentication key. 237If all requests for a session use request-specific keys, 238this field should be left as 239.Dv NULL . 240This pointer and associated key must remain valid for the duration of the 241crypto session. 242.It Fa csp_auth_mlen 243The length in bytes of the digest. 244If zero, the full length of the digest is used. 245If non-zero, the first 246.Fa csp_auth_mlen 247bytes of the digest are used. 248.El 249.Sh RETURN VALUES 250.Fn crypto_newsession 251returns a non-zero value if an error occurs or zero on success. 252.Pp 253.Fn crypto_auth_hash 254and 255.Fn crypto_cipher 256return 257.Dv NULL 258if the request is valid or a pointer to a structure on success. 259.Sh SEE ALSO 260.Xr crypto 7 , 261.Xr crypto 9 , 262.Xr crypto_request 9 263.Sh BUGS 264The current implementation of 265.Nm crypto_freesession 266does not provide a way for the caller to know that there are no other 267references to the keys stored in the session's associated parameters. 268This function should probably sleep until any in-flight cryptographic 269operations associated with the session are completed. 270