diff options
Diffstat (limited to 'static/freebsd/man9/crypto_session.9 3.html')
| -rw-r--r-- | static/freebsd/man9/crypto_session.9 3.html | 230 |
1 files changed, 0 insertions, 230 deletions
diff --git a/static/freebsd/man9/crypto_session.9 3.html b/static/freebsd/man9/crypto_session.9 3.html deleted file mode 100644 index dab25818..00000000 --- a/static/freebsd/man9/crypto_session.9 3.html +++ /dev/null @@ -1,230 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">CRYPTO_SESSION(9)</td> - <td class="head-vol">Kernel Developer's Manual</td> - <td class="head-rtitle">CRYPTO_SESSION(9)</td> - </tr> -</table> -<div class="manual-text"> -<section class="Sh"> -<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> -<p class="Pp"><code class="Nm">crypto_session</code> — - <span class="Nd">state used for symmetric cryptographic services</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="In">#include - <<a class="In">opencrypto/cryptodev.h</a>></code></p> -<p class="Pp"><var class="Ft">struct auth_hash *</var> - <br/> - <code class="Fn">crypto_auth_hash</code>(<var class="Fa" style="white-space: nowrap;">const - struct crypto_session_params *csp</var>);</p> -<p class="Pp"><var class="Ft">struct enc_xform *</var> - <br/> - <code class="Fn">crypto_cipher</code>(<var class="Fa" style="white-space: nowrap;">const - struct crypto_session_params *csp</var>);</p> -<p class="Pp"><var class="Ft">const struct crypto_session_params *</var> - <br/> - <code class="Fn">crypto_get_params</code>(<var class="Fa" style="white-space: nowrap;">crypto_session_t - cses</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">crypto_newsession</code>(<var class="Fa">crypto_session_t - *cses</var>, <var class="Fa">const struct crypto_session_params *csp</var>, - <var class="Fa">int crid</var>);</p> -<p class="Pp"><var class="Ft">int</var> - <br/> - <code class="Fn">crypto_freesession</code>(<var class="Fa" style="white-space: nowrap;">crypto_session_t - cses</var>);</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">Symmetric cryptographic operations in the kernel are associated - with cryptographic sessions. Sessions hold state shared across multiple - requests. Active sessions are associated with a single cryptographic - driver.</p> -<p class="Pp">The <var class="Vt">crypto_session_t</var> type represents an - opaque reference to an active session. Session objects are allocated and - managed by the cryptographic framework.</p> -<p class="Pp" id="crypto_newsession">New sessions are created by - <a class="permalink" href="#crypto_newsession"><code class="Fn">crypto_newsession</code></a>(). - <var class="Fa">csp</var> describes various parameters associated with the - new session such as the algorithms to use and any session-wide keys. - <var class="Fa">crid</var> can be used to request either a specific - cryptographic driver or classes of drivers. For the latter case, - <var class="Fa">crid</var> should be set to a mask of the following - values:</p> -<dl class="Bl-tag"> - <dt id="CRYPTOCAP_F_HARDWARE"><a class="permalink" href="#CRYPTOCAP_F_HARDWARE"><code class="Dv">CRYPTOCAP_F_HARDWARE</code></a></dt> - <dd>Request hardware drivers. Hardware drivers do not use the host CPU to - perform operations. Typically, a separate co-processor performs the - operations asynchronously.</dd> - <dt id="CRYPTOCAP_F_SOFTWARE"><a class="permalink" href="#CRYPTOCAP_F_SOFTWARE"><code class="Dv">CRYPTOCAP_F_SOFTWARE</code></a></dt> - <dd>Request software drivers. Software drivers use the host CPU to perform - operations. The kernel includes a simple, yet portable implementation of - each supported algorithm in the <a class="Xr">cryptosoft(4)</a> driver. - Additional software drivers may also be available on architectures which - provide instructions designed to accelerate cryptographic operations.</dd> -</dl> -<p class="Pp">If both hardware and software drivers are requested, hardware - drivers are preferred over software drivers. Accelerated software drivers - are preferred over the baseline software driver. If multiple hardware - drivers are available, the framework will distribute sessions across these - drivers in a round-robin fashion.</p> -<p class="Pp" id="crypto_newsession~2">On success, - <a class="permalink" href="#crypto_newsession~2"><code class="Fn">crypto_newsession</code></a>() - saves a reference to the newly created session in - <var class="Fa">cses</var>.</p> -<p class="Pp" id="crypto_freesession"><a class="permalink" href="#crypto_freesession"><code class="Fn">crypto_freesession</code></a>() - is used to free the resources associated with the session - <var class="Fa">cses</var>.</p> -<p class="Pp" id="crypto_auth_hash"><a class="permalink" href="#crypto_auth_hash"><code class="Fn">crypto_auth_hash</code></a>() - returns a structure describing the baseline software implementation of an - authentication algorithm requested by <var class="Fa">csp</var>. If - <var class="Fa">csp</var> does not specify an authentication algorithm, or - requests an invalid algorithm, <code class="Dv">NULL</code> is returned.</p> -<p class="Pp" id="crypto_cipher"><a class="permalink" href="#crypto_cipher"><code class="Fn">crypto_cipher</code></a>() - returns a structure describing the baseline software implementation of an - encryption algorithm requested by <var class="Fa">csp</var>. If - <var class="Fa">csp</var> does not specify an encryption algorithm, or - requests an invalid algorithm, <code class="Dv">NULL</code> is returned.</p> -<p class="Pp" id="crypto_get_params"><a class="permalink" href="#crypto_get_params"><code class="Fn">crypto_get_params</code></a>() - returns a pointer to the session parameters used by - <var class="Fa">cses</var>.</p> -<section class="Ss"> -<h2 class="Ss" id="Session_Parameters"><a class="permalink" href="#Session_Parameters">Session - Parameters</a></h2> -<p class="Pp">Session parameters are used to describe the cryptographic - operations performed by cryptographic requests. Parameters are stored in an - instance of <var class="Vt">struct crypto_session_params</var>. When - initializing parameters to pass to - <code class="Fn">crypto_newsession</code>(), the entire structure should - first be zeroed. Needed fields should then be set leaving unused fields as - zero. This structure contains the following fields:</p> -<dl class="Bl-tag"> - <dt><var class="Fa">csp_mode</var></dt> - <dd>Type of operation to perform. This field must be set to one of the - following: - <dl class="Bl-tag"> - <dt id="CSP_MODE_COMPRESS"><a class="permalink" href="#CSP_MODE_COMPRESS"><code class="Dv">CSP_MODE_COMPRESS</code></a></dt> - <dd>Compress or decompress request payload. - <p class="Pp">The compression algorithm is specified in - <var class="Fa">csp_cipher_alg</var>.</p> - </dd> - <dt id="CSP_MODE_CIPHER"><a class="permalink" href="#CSP_MODE_CIPHER"><code class="Dv">CSP_MODE_CIPHER</code></a></dt> - <dd>Encrypt or decrypt request payload. - <p class="Pp">The encryption algorithm is specified in - <var class="Fa">csp_cipher_alg</var>.</p> - </dd> - <dt id="CSP_MODE_DIGEST"><a class="permalink" href="#CSP_MODE_DIGEST"><code class="Dv">CSP_MODE_DIGEST</code></a></dt> - <dd>Compute or verify a digest, or hash, of request payload. - <p class="Pp">The authentication algorithm is specified in - <var class="Fa">csp_auth_alg</var>.</p> - </dd> - <dt id="CSP_MODE_AEAD"><a class="permalink" href="#CSP_MODE_AEAD"><code class="Dv">CSP_MODE_AEAD</code></a></dt> - <dd>Authenticated encryption with additional data. Decryption operations - require the digest, or tag, and fail if it does not match. - <p class="Pp">The AEAD algorithm is specified in - <var class="Fa">csp_cipher_alg</var>.</p> - </dd> - <dt id="CSP_MODE_ETA"><a class="permalink" href="#CSP_MODE_ETA"><code class="Dv">CSP_MODE_ETA</code></a></dt> - <dd>Encrypt-then-Authenticate. In this mode, encryption operations encrypt - the payload and then compute an authentication digest over the request - additional authentication data followed by the encrypted payload. - Decryption operations fail without decrypting the data if the provided - digest does not match. - <p class="Pp">The encryption algorithm is specified in - <var class="Fa">csp_cipher_alg</var> and the authentication - algorithm is specified in <var class="Fa">csp_auth_alg</var>.</p> - </dd> - </dl> - </dd> - <dt><var class="Fa">csp_flags</var></dt> - <dd>A mask of optional driver features. Drivers will only attach to a session - if they support all of the requested features. - <dl class="Bl-tag"> - <dt id="CSP_F_SEPARATE_OUTPUT"><a class="permalink" href="#CSP_F_SEPARATE_OUTPUT"><code class="Dv">CSP_F_SEPARATE_OUTPUT</code></a></dt> - <dd>Support requests that use separate input and output buffers. Sessions - with this flag set permit requests with either a single buffer that is - modified in-place, or requests with separate input and output buffers. - Sessions without this flag only permit requests with a single buffer - that is modified in-place.</dd> - <dt id="CSP_F_SEPARATE_AAD"><a class="permalink" href="#CSP_F_SEPARATE_AAD"><code class="Dv">CSP_F_SEPARATE_AAD</code></a></dt> - <dd>Support requests that use a separate buffer for AAD rather than - providing AAD as a region in the input buffer. Sessions with this flag - set permit requests with AAD passed in either in a region of the input - buffer or in a single, virtually-contiguous buffer. Sessions without - this flag only permit requests with AAD passed in as a region in the - input buffer.</dd> - <dt id="CSP_F_ESN"><a class="permalink" href="#CSP_F_ESN"><code class="Dv">CSP_F_ESN</code></a></dt> - <dd>Support requests that use a separate buffer for IPsec ESN (Extended - Sequence Numbers). - <p class="Pp">Sessions with this flag set permit requests with IPsec ESN - passed in special buffer. It is required for IPsec ESN support of - encrypt and authenticate mode where the high-order 32 bits of the - sequence number are appended after the Next Header (RFC 4303).</p> - </dd> - </dl> - </dd> - <dt><var class="Fa">csp_ivlen</var></dt> - <dd>If either the cipher or authentication algorithms require an explicit - initialization vector (IV) or nonce, this specifies the length in bytes. - All requests for a session use the same IV length.</dd> - <dt><var class="Fa">csp_cipher_alg</var></dt> - <dd>Encryption or compression algorithm.</dd> - <dt><var class="Fa">csp_cipher_klen</var></dt> - <dd>Length of encryption or decryption key in bytes. All requests for a - session use the same key length.</dd> - <dt><var class="Fa">csp_cipher_key</var></dt> - <dd>Pointer to encryption or decryption key. If all requests for a session use - request-specific keys, this field should be left as - <code class="Dv">NULL</code>. This pointer and associated key must remain - valid for the duration of the crypto session.</dd> - <dt><var class="Fa">csp_auth_alg</var></dt> - <dd>Authentication algorithm.</dd> - <dt><var class="Fa">csp_auth_klen</var></dt> - <dd>Length of authentication key in bytes. If the authentication algorithm - does not use a key, this field should be left as zero.</dd> - <dt><var class="Fa">csp_auth_key</var></dt> - <dd>Pointer to the authentication key. If all requests for a session use - request-specific keys, this field should be left as - <code class="Dv">NULL</code>. This pointer and associated key must remain - valid for the duration of the crypto session.</dd> - <dt><var class="Fa">csp_auth_mlen</var></dt> - <dd>The length in bytes of the digest. If zero, the full length of the digest - is used. If non-zero, the first <var class="Fa">csp_auth_mlen</var> bytes - of the digest are used.</dd> -</dl> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN - VALUES</a></h1> -<p class="Pp"><code class="Fn">crypto_newsession</code>() returns a non-zero - value if an error occurs or zero on success.</p> -<p class="Pp"><code class="Fn">crypto_auth_hash</code>() and - <code class="Fn">crypto_cipher</code>() return <code class="Dv">NULL</code> - if the request is valid or a pointer to a structure on success.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE - ALSO</a></h1> -<p class="Pp"><a class="Xr">crypto(7)</a>, <a class="Xr">crypto(9)</a>, - <a class="Xr">crypto_request(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> -<p class="Pp">The current implementation of - <code class="Nm">crypto_freesession</code> does not provide a way for the - caller to know that there are no other references to the keys stored in the - session's associated parameters. This function should probably sleep until - any in-flight cryptographic operations associated with the session are - completed.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">June 22, 2020</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |