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