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