diff options
Diffstat (limited to 'static/freebsd/man4/crypto.4 3.html')
| -rw-r--r-- | static/freebsd/man4/crypto.4 3.html | 275 |
1 files changed, 0 insertions, 275 deletions
diff --git a/static/freebsd/man4/crypto.4 3.html b/static/freebsd/man4/crypto.4 3.html deleted file mode 100644 index 82054007..00000000 --- a/static/freebsd/man4/crypto.4 3.html +++ /dev/null @@ -1,275 +0,0 @@ -<table class="head"> - <tr> - <td class="head-ltitle">CRYPTO(4)</td> - <td class="head-vol">Device Drivers Manual</td> - <td class="head-rtitle">CRYPTO(4)</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</code>, <code class="Nm">cryptodev</code> - — <span class="Nd">user-mode access to hardware-accelerated - cryptography</span></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> -<p class="Pp"><code class="Cd">device crypto</code> - <br/> - <code class="Cd">device cryptodev</code></p> -<p class="Pp"> - <br/> - <code class="In">#include <<a class="In">sys/ioctl.h</a>></code> - <br/> - <code class="In">#include <<a class="In">sys/time.h</a>></code> - <br/> - <code class="In">#include - <<a class="In">crypto/cryptodev.h</a>></code></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> -<p class="Pp">The <code class="Nm">crypto</code> driver gives user-mode - applications access to hardware-accelerated cryptographic transforms as - implemented by the <a class="Xr">crypto(9)</a> in-kernel interface.</p> -<p class="Pp">The <span class="Pa">/dev/crypto</span> special device provides an - <a class="Xr">ioctl(2)</a> based interface. User-mode applications open the - special device and then issue <a class="Xr">ioctl(2)</a> calls on the - descriptor. User-mode access to <span class="Pa">/dev/crypto</span> is - controlled by the <code class="Ic">kern.cryptodevallowsoft</code> - <a class="Xr">sysctl(8)</a> variable. If this variable is zero, then - user-mode sessions are only permitted to use cryptography coprocessors.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="THEORY_OF_OPERATION"><a class="permalink" href="#THEORY_OF_OPERATION">THEORY - OF OPERATION</a></h1> -<p class="Pp">Use of the device requires a basic series of steps:</p> -<ol class="Bl-enum"> - <li>Open the <span class="Pa">/dev/crypto</span> device.</li> - <li>Create a session with <code class="Dv">CIOCGSESSION</code> or - <code class="Dv">CIOCGSESSION2</code>. Applications will require at least - one symmetric session. Since cipher and MAC keys are tied to sessions, - many applications will require more.</li> - <li>Submit requests, synchronously with <code class="Dv">CIOCCRYPT</code> or - <code class="Dv">CIOCCRYPTAEAD</code>.</li> - <li>Optionally destroy a session with - <code class="Dv">CIOCFSESSION</code>.</li> - <li>Close the <span class="Pa">/dev/crypto</span> device. This will - automatically close any remaining sessions associated with the file - descriptor.</li> -</ol> -</section> -<section class="Sh"> -<h1 class="Sh" id="SYMMETRIC-KEY_OPERATION"><a class="permalink" href="#SYMMETRIC-KEY_OPERATION">SYMMETRIC-KEY - OPERATION</a></h1> -<p class="Pp"><code class="Nm">cryptodev</code> provides a context-based API to - traditional symmetric-key encryption (or privacy) algorithms, keyed and - unkeyed one-way hash (HMAC and MAC) algorithms, encrypt-then-authenticate - (ETA) fused operations, and authenticated encryption with additional data - (AEAD) operations. For ETA operations, drivers perform both a privacy - algorithm and an integrity-check algorithm in a single pass over the data: - either a fused encrypt/HMAC-generate operation, or a fused - HMAC-verify/decrypt operation. Similarly, for AEAD operations, drivers - perform either an encrypt/MAC-generate operation or a MAC-verify/decrypt - operation.</p> -<p class="Pp">The algorithm(s) and key(s) to use are specified when a session is - created. Individual requests are able to specify per-request initialization - vectors or nonces.</p> -<section class="Ss"> -<h2 class="Ss" id="Algorithms"><a class="permalink" href="#Algorithms">Algorithms</a></h2> -<p class="Pp">For a list of supported algorithms, see - <a class="Xr">crypto(7)</a>.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="IOCTL_Request_Descriptions"><a class="permalink" href="#IOCTL_Request_Descriptions">IOCTL - Request Descriptions</a></h2> -<dl class="Bl-tag"> - <dt id="CIOCFINDDEV"><a class="permalink" href="#CIOCFINDDEV"><code class="Dv">CIOCFINDDEV</code></a> - <var class="Fa">struct crypt_find_op *fop</var></dt> - <dd> - <div class="Bd Li"> - <pre>struct crypt_find_op { - int crid; /* driver id + flags */ - char name[32]; /* device/driver name */ -}; - - </pre> - </div> - If <var class="Fa">crid</var> is -1, then find the driver named - <var class="Fa">name</var> and return the id in - <var class="Fa">crid</var>. If <var class="Fa">crid</var> is not -1, - return the name of the driver with <var class="Fa">crid</var> in - <var class="Fa">name</var>. In either case, if the driver is not found, - <code class="Dv">ENOENT</code> is returned.</dd> - <dt id="CIOCGSESSION"><a class="permalink" href="#CIOCGSESSION"><code class="Dv">CIOCGSESSION</code></a> - <var class="Fa">struct session_op *sessp</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct session_op { - uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ - uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ - - uint32_t keylen; /* cipher key */ - const void *key; - int mackeylen; /* mac key */ - const void *mackey; - - uint32_t ses; /* returns: ses # */ -}; - - </pre> - </div> - Create a new cryptographic session on a file descriptor for the device; that - is, a persistent object specific to the chosen privacy algorithm, - integrity algorithm, and keys specified in <var class="Fa">sessp</var>. - The special value 0 for either privacy or integrity is reserved to - indicate that the indicated operation (privacy or integrity) is not - desired for this session. ETA sessions specify both privacy and integrity - algorithms. AEAD sessions specify only a privacy algorithm. - <p class="Pp">Multiple sessions may be bound to a single file descriptor. - The session ID returned in <var class="Fa">sessp->ses</var> is - supplied as a required field in the operation structure - <var class="Fa">crypt_op</var> for future encryption or hashing - requests.</p> - <p class="Pp">For non-zero privacy algorithms, the privacy algorithm must be - specified in <var class="Fa">sessp->cipher</var>, the key length in - <var class="Fa">sessp->keylen</var>, and the key value in the octets - addressed by <var class="Fa">sessp->key</var>.</p> - <p class="Pp">For keyed one-way hash algorithms, the one-way hash must be - specified in <var class="Fa">sessp->mac</var>, the key length in - <var class="Fa">sessp->mackey</var>, and the key value in the octets - addressed by <var class="Fa">sessp->mackeylen</var>.</p> - <p class="Pp">Support for a specific combination of fused privacy and - integrity-check algorithms depends on whether the underlying hardware - supports that combination. Not all combinations are supported by all - hardware, even if the hardware supports each operation as a stand-alone - non-fused operation.</p> - </dd> - <dt id="CIOCGSESSION2"><a class="permalink" href="#CIOCGSESSION2"><code class="Dv">CIOCGSESSION2</code></a> - <var class="Fa">struct session2_op *sessp</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct session2_op { - uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ - uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ - - uint32_t keylen; /* cipher key */ - const void *key; - int mackeylen; /* mac key */ - const void *mackey; - - uint32_t ses; /* returns: ses # */ - int crid; /* driver id + flags (rw) */ - int ivlen; /* length of nonce/IV */ - int maclen; /* length of MAC/tag */ - int pad[2]; /* for future expansion */ -}; - - </pre> - </div> - This request is similar to CIOGSESSION but adds additional fields. - <p class="Pp"><var class="Fa">sessp->crid</var> requests either a - specific crypto device or a class of devices (software vs hardware).</p> - <p class="Pp"><var class="Fa">sessp->ivlen</var> specifies the length of - the IV or nonce supplied with each request. If this field is set to - zero, the default IV or nonce length is used.</p> - <p class="Pp"><var class="Fa">sessp->maclen</var> specifies the length of - the MAC or authentication tag supplied or computed by each request. If - this field is set to zero, the full MAC is used.</p> - <p class="Pp">The <var class="Fa">sessp->pad</var> field must be - initialized to zero.</p> - </dd> - <dt id="CIOCCRYPT"><a class="permalink" href="#CIOCCRYPT"><code class="Dv">CIOCCRYPT</code></a> - <var class="Fa">struct crypt_op *cr_op</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct crypt_op { - uint32_t ses; - uint16_t op; /* e.g. COP_ENCRYPT */ - uint16_t flags; - u_int len; - const void *src; - void *dst; - void *mac; /* must be large enough for result */ - const void *iv; -}; - - </pre> - </div> - Request an encryption/decryption (or hash) operation. To encrypt, set - <var class="Fa">cr_op->op</var> to <code class="Dv">COP_ENCRYPT</code>. - To decrypt, set <var class="Fa">cr_op->op</var> to - <code class="Dv">COP_DECRYPT</code>. The field - <var class="Fa">cr_op->len</var> supplies the length of the input - buffer; the fields <var class="Fa">cr_op->src</var>, - <var class="Fa">cr_op->dst</var>, <var class="Fa">cr_op->mac</var>, - <var class="Fa">cr_op->iv</var> supply the addresses of the input - buffer, output buffer, one-way hash, and initialization vector, - respectively. - <p class="Pp">If a session is using either fused encrypt-then-authenticate - or an AEAD algorithm, decryption operations require the associated hash - as an input. If the hash is incorrect, the operation will fail with - <code class="Dv">EBADMSG</code> and the output buffer will remain - unchanged.</p> - </dd> - <dt id="CIOCCRYPTAEAD"><a class="permalink" href="#CIOCCRYPTAEAD"><code class="Dv">CIOCCRYPTAEAD</code></a> - <var class="Fa">struct crypt_aead *cr_aead</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct crypt_aead { - uint32_t ses; - uint16_t op; /* e.g. COP_ENCRYPT */ - uint16_t flags; - u_int len; - u_int aadlen; - u_int ivlen; - const void *src; - void *dst; - const void *aad; /* additional authenticated data */ - void *tag; /* must fit for chosen TAG length */ - const void *iv; -}; - - </pre> - </div> - The <code class="Dv">CIOCCRYPTAEAD</code> is similar to the - <code class="Dv">CIOCCRYPT</code> but provides additional data in - <var class="Fa">cr_aead->aad</var> to include in the authentication - mode.</dd> - <dt id="CIOCFSESSION"><a class="permalink" href="#CIOCFSESSION"><code class="Dv">CIOCFSESSION</code></a> - <var class="Fa">u_int32_t ses_id</var></dt> - <dd>Destroys the session identified by <var class="Fa">ses_id</var>.</dd> -</dl> -</section> -</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">aesni(4)</a>, <a class="Xr">ipsec(4)</a>, - <a class="Xr">padlock(4)</a>, <a class="Xr">safe(4)</a>, - <a class="Xr">crypto(7)</a>, <a class="Xr">geli(8)</a>, - <a class="Xr">crypto(9)</a></p> -</section> -<section class="Sh"> -<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1> -<p class="Pp">The <code class="Nm">crypto</code> driver first appeared in - <span class="Ux">OpenBSD 3.0</span>. The <code class="Nm">crypto</code> - driver was imported to <span class="Ux">FreeBSD 5.0</span>.</p> -</section> -<section class="Sh"> -<h1 class="Sh" id="BUGS"><a class="permalink" href="#BUGS">BUGS</a></h1> -<p class="Pp">Error checking and reporting is weak.</p> -<p class="Pp">The values specified for symmetric-key key sizes to - <code class="Dv">CIOCGSESSION</code> must exactly match the values expected - by <a class="Xr">opencrypto(9)</a>. The output buffer and MAC buffers - supplied to <code class="Dv">CIOCCRYPT</code> must follow whether privacy or - integrity algorithms were specified for session: if you request a - <span class="No">non-</span><code class="Dv">NULL</code> algorithm, you must - supply a suitably-sized buffer.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">October 6, 2021</td> - <td class="foot-os">FreeBSD 15.0</td> - </tr> -</table> |