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 May 25, 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.El 198.It Fa csp_ivlen 199If either the cipher or authentication algorithms require an explicit 200initialization vector (IV) or nonce, 201this specifies the length in bytes. 202All requests for a session use the same IV length. 203.It Fa csp_cipher_alg 204Encryption or compression algorithm. 205.It Fa csp_cipher_klen 206Length of encryption or decryption key in bytes. 207All requests for a session use the same key length. 208.It Fa csp_cipher_key 209Pointer to encryption or decryption key. 210If all requests for a session use request-specific keys, 211this field should be left as 212.Dv NULL . 213This pointer and associated key must remain valid for the duration of the 214crypto session. 215.It Fa csp_auth_alg 216Authentication algorithm. 217.It Fa csp_auth_klen 218Length of authentication key in bytes. 219If the authentication algorithm does not use a key, 220this field should be left as zero. 221.It Fa csp_auth_key 222Pointer to the authentication key. 223If all requests for a session use request-specific keys, 224this field should be left as 225.Dv NULL . 226This pointer and associated key must remain valid for the duration of the 227crypto session. 228.It Fa csp_auth_mlen 229The length in bytes of the digest. 230If zero, the full length of the digest is used. 231If non-zero, the first 232.Fa csp_auth_mlen 233bytes of the digest are used. 234.El 235.Sh RETURN VALUES 236.Fn crypto_newsession 237returns a non-zero value if an error occurs or zero on success. 238.Pp 239.Fn crypto_auth_hash 240and 241.Fn crypto_cipher 242return 243.Dv NULL 244if the request is valid or a pointer to a structure on success. 245.Sh SEE ALSO 246.Xr crypto 7 , 247.Xr crypto 9 , 248.Xr crypto_request 9 249.Sh BUGS 250The current implementation of 251.Nm crypto_freesession 252does not provide a way for the caller to know that there are no other 253references to the keys stored in the session's associated parameters. 254This function should probably sleep until any in-flight cryptographic 255operations associated with the session are completed. 256