diff options
Diffstat (limited to 'static/netbsd/man4/crypto.4 3.html')
| -rw-r--r-- | static/netbsd/man4/crypto.4 3.html | 616 |
1 files changed, 0 insertions, 616 deletions
diff --git a/static/netbsd/man4/crypto.4 3.html b/static/netbsd/man4/crypto.4 3.html deleted file mode 100644 index 8dc2c029..00000000 --- a/static/netbsd/man4/crypto.4 3.html +++ /dev/null @@ -1,616 +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">swcrypto</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">hifn* at pci? dev ? function ?</code> - <br/> - <code class="Cd">ubsec* at pci? dev ? function ?</code></p> -<p class="Pp"> - <br/> - <code class="Cd">pseudo-device crypto</code> - <br/> - <code class="Cd">pseudo-device swcrypto</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">opencrypto(9)</a> in-kernel interface.</p> -<p class="Pp">The <code class="Cm">swcrypto</code> driver is a software-only - implementation of the <a class="Xr">opencrypto(9)</a> interface, and must be - included to use the interface without hardware acceleration.</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 should - open the special device, then issue <a class="Xr">ioctl(2)</a> calls on the - descriptor. User-mode access to <span class="Pa">/dev/crypto</span> is - generally controlled by three <a class="Xr">sysctl(8)</a> variables, - <code class="Ic">kern.usercrypto</code>, - <code class="Ic">kern.userasymcrypto</code>, and - <code class="Ic">kern.cryptodevallowsoft</code>. See - <a class="Xr">sysctl(7)</a> for additional details.</p> -<p class="Pp">The <code class="Nm">crypto</code> device provides two distinct - modes of operation: one mode for symmetric-keyed cryptographic requests, and - a second mode for both asymmetric-key (public-key/private-key) requests, and - for modular arithmetic (for Diffie-Hellman key exchange and other - cryptographic protocols). The two modes are described separately below.</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">Regardless of whether symmetric-key or asymmetric-key operations - are to be performed, use of the device requires a basic series of steps:</p> -<ol class="Bl-enum"> - <li>Open a file descriptor for the device. See <a class="Xr">open(2)</a>.</li> - <li>If any symmetric operation will be performed, create one session, with - <code class="Dv">CIOCGSESSION</code>, or multiple sessions, with - <code class="Dv">CIOCNGSESSION</code>. Most applications will require at - least one symmetric session. Since cipher and MAC keys are tied to - sessions, many applications will require more. Asymmetric operations do - not use sessions.</li> - <li>Submit requests, synchronously with <code class="Dv">CIOCCRYPT</code> - (symmetric) or <code class="Dv">CIOCKEY</code> (asymmetric) or - asynchronously with <code class="Dv">CIOCNCRYPTM</code> (symmetric) or - <code class="Dv">CIOCNFKEYM</code> (asymmetric). The asynchronous - interface allows multiple requests to be submitted in one call if the user - so desires.</li> - <li>If the asynchronous interface is used, wait for results with - <a class="Xr">select(2)</a> or <a class="Xr">poll(2)</a>, then collect - them with <code class="Dv">CIOCNCRYPTRET</code> (a particular request) or - <code class="Dv">CIOCNCRYPTRETM</code> (multiple requests).</li> - <li>Destroy one session with <code class="Dv">CIOCFSESSION</code> or many at - once with <code class="Dv">CIOCNFSESSION</code>.</li> - <li>Close the device with <a class="Xr">close(2)</a>.</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">The symmetric-key operation mode provides a context-based API to - traditional symmetric-key encryption (or privacy) algorithms, or to keyed - and unkeyed one-way hash (HMAC and MAC) algorithms. The symmetric-key mode - also permits fused operation, where the hardware performs 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.</p> -<p class="Pp">To use symmetric mode, you must first create a session specifying - the algorithm(s) and key(s) to use; then issue encrypt or decrypt requests - against the session.</p> -<section class="Ss"> -<h2 class="Ss" id="Symmetric-key_privacy_algorithms"><a class="permalink" href="#Symmetric-key_privacy_algorithms">Symmetric-key - privacy algorithms</a></h2> -<p class="Pp">Contingent upon device drivers for installed cryptographic - hardware registering with <a class="Xr">opencrypto(9)</a>, as providers of a - given algorithm, some or all of the following symmetric-key privacy - algorithms may be available:</p> -<p class="Pp"></p> -<div class="Bd-indent"> -<dl class="Bl-tag Bl-compact"> - <dt>CRYPTO_DES_CBC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_3DES_CBC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_BLF_CBC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_CAST_CBC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_SKIPJACK_CBC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_AES_CBC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_ARC4</dt> - <dd style="width: auto;"> </dd> -</dl> -</div> -</section> -<section class="Ss"> -<h2 class="Ss" id="Integrity-check_operations"><a class="permalink" href="#Integrity-check_operations">Integrity-check - operations</a></h2> -<p class="Pp">Contingent upon hardware support, some or all of the following - keyed one-way hash algorithms may be available:</p> -<p class="Pp"></p> -<div class="Bd-indent"> -<dl class="Bl-tag Bl-compact"> - <dt>CRYPTO_RIPEMD160_HMAC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_MD5_KPDK</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_SHA1_KPDK</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_MD5_HMAC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_SHA1_HMAC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_SHA2_256_HMAC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_SHA2_384_HMAC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_SHA2_512_HMAC</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_MD5</dt> - <dd style="width: auto;"> </dd> - <dt>CRYPTO_SHA1</dt> - <dd style="width: auto;"> </dd> -</dl> -</div> -<p class="Pp" id="CRYPTO_MD5">The - <a class="permalink" href="#CRYPTO_MD5"><i class="Em">CRYPTO_MD5</i></a> and - <a class="permalink" href="#CRYPTO_SHA1"><i class="Em" id="CRYPTO_SHA1">CRYPTO_SHA1</i></a> - algorithms are actually unkeyed, but should be requested as symmetric-key - hash algorithms with a zero-length key.</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="CRIOGET"><a class="permalink" href="#CRIOGET"><code class="Dv">CRIOGET</code></a> - <var class="Fa">int *fd</var></dt> - <dd>This operation is deprecated and will be removed after - <span class="Ux">NetBSD 5.0</span>. It clones the fd argument to - <a class="Xr">ioctl(2)</a>, yielding a new file descriptor for the - creation of sessions. Because the device now clones on open, this - operation is unnecessary.</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 { - u_int32_t cipher; /* e.g. CRYPTO_DES_CBC */ - u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */ - - u_int32_t keylen; /* cipher key */ - void * key; - int mackeylen; /* mac key */ - void * mackey; - - u_int32_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. - <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 symmetric-operation structure - <var class="Fa">crypt_op</var> for future encryption or hashing - requests.</p> - <p class="Pp">This implementation will never return a session ID of 0 for a - successful creation of a session, which is a - <span class="Ux">NetBSD</span> extension.</p> - <p class="Pp">For non-zero symmetric-key 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="CIOCNGSESSION"><a class="permalink" href="#CIOCNGSESSION"><code class="Dv">CIOCNGSESSION</code></a> - <var class="Fa">struct crypt_sgop *sgop</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct crypt_sgop { - size_t count; /* how many */ - struct session_n_op * sessions; /* where to get them */ -}; - -struct session_n_op { - u_int32_t cipher; /* e.g. CRYPTO_DES_CBC */ - u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */ - - u_int32_t keylen; /* cipher key */ - void * key; - u_int32_t mackeylen; /* mac key */ - void * mackey; - - u_int32_t ses; /* returns: session # */ - int status; -}; - - </pre> - </div> - Create one or more sessions. Takes a counted array of - <var class="Fa">session_n_op</var> structures in - <var class="Fa">sgop</var>. For each requested session (array element n), - the session number is returned in - <var class="Fa">sgop->sessions[n].ses</var> and the status for that - session creation in - <var class="Fa">sgop->sessions[n].status</var>.</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 { - u_int32_t ses; - u_int16_t op; /* e.g. COP_ENCRYPT */ - u_int16_t flags; - u_int len; - void * src, *dst; - void * mac; /* must be large enough for result */ - void * iv; -}; - - </pre> - </div> - Request a symmetric-key (or hash) operation. The file descriptor argument to - <a class="Xr">ioctl(2)</a> must have been bound to a valid session. 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.</dd> - <dt id="CIOCNCRYPTM"><a class="permalink" href="#CIOCNCRYPTM"><code class="Dv">CIOCNCRYPTM</code></a> - <var class="Fa">struct crypt_mop *cr_mop</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct crypt_mop { - size_t count; /* how many */ - struct crypt_n_op * reqs; /* where to get them */ -}; - -struct crypt_n_op { - u_int32_t ses; - u_int16_t op; /* e.g. COP_ENCRYPT */ - u_int16_t flags; - u_int len; - - u_int32_t reqid; /* request id */ - int status; /* accepted or not */ - - void *opaque; /* opaque pointer ret to user */ - u_int32_t keylen; /* cipher key - optional */ - void * key; - u_int32_t mackeylen; /* mac key - optional */ - void * mackey; - - void * src, * dst; - void * mac; - void * iv; -}; - - </pre> - </div> - This is the asynchronous version of CIOCCRYPT, which allows multiple - symmetric-key (or hash) operations to be started (see CIOCRYPT above for - the details for each operation). - <p class="Pp">The <var class="Fa">cr_mop->count</var> field specifies the - number of operations provided in the cr_mop->reqs array.</p> - <p class="Pp">Each operation is assigned a unique request id returned in the - <var class="Fa">cr_mop->reqs[n].reqid</var> field.</p> - <p class="Pp">Each operation can accept an opaque value from the user to be - passed back to the user when the operation completes (e.g., to track - context for the request). The opaque field is - <var class="Fa">cr_mop->reqs[n].opaque</var>.</p> - <p class="Pp">If a problem occurs with starting any of the operations then - that operation's <var class="Fa">cr_mop->reqs[n].status</var> field - is filled with the error code. The failure of an operation does not - prevent the other operations from being started.</p> - <p class="Pp">The <a class="Xr">select(2)</a> or <a class="Xr">poll(2)</a> - functions must be used on the device file descriptor to detect that some - operation has completed; results are then retrieved with - <code class="Dv">CIOCNCRYPTRETM</code>.</p> - <p class="Pp">The <var class="Fa">key</var> and <var class="Fa">mackey</var> - fields of the operation structure are currently unused. They are - intended for use to immediately rekey an existing session before - processing a new request.</p> - </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 /dev/crypto session associated with the file-descriptor - argument.</dd> - <dt id="CIOCNFSESSION"><a class="permalink" href="#CIOCNFSESSION"><code class="Dv">CIOCNFSESSION</code></a> - <var class="Fa">struct crypt_sfop *sfop</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct crypt_sfop { - size_t count; - u_int32_t *sesid; -}; - - </pre> - </div> - Destroys the <var class="Fa">sfop->count</var> sessions specified by the - <var class="Fa">sfop</var> array of session identifiers.</dd> -</dl> -</section> -</section> -<section class="Sh"> -<h1 class="Sh" id="ASYMMETRIC-KEY_OPERATION"><a class="permalink" href="#ASYMMETRIC-KEY_OPERATION">ASYMMETRIC-KEY - OPERATION</a></h1> -<section class="Ss"> -<h2 class="Ss" id="Asymmetric-key_algorithms"><a class="permalink" href="#Asymmetric-key_algorithms">Asymmetric-key - algorithms</a></h2> -<p class="Pp">Contingent upon hardware support, the following asymmetric - (public-key/private-key; or key-exchange subroutine) operations may also be - available:</p> -<p class="Pp"></p> -<table class="Bl-column Bd-indent Bl-compact"> - <tr id="Algorithm"> - <td><a class="permalink" href="#Algorithm"><i class="Em">Algorithm</i></a></td> - <td>Input parameter</td> - <td>Output parameter</td> - </tr> - <tr> - <td><i class="Em"> </i></td> - <td>Count</td> - <td>Count</td> - </tr> - <tr id="CRK_MOD_EXP"> - <td><a class="permalink" href="#CRK_MOD_EXP"><code class="Dv">CRK_MOD_EXP</code></a></td> - <td>3</td> - <td>1</td> - </tr> - <tr id="CRK_MOD_EXP_CRT"> - <td><a class="permalink" href="#CRK_MOD_EXP_CRT"><code class="Dv">CRK_MOD_EXP_CRT</code></a></td> - <td>6</td> - <td>1</td> - </tr> - <tr id="CRK_MOD_ADD"> - <td><a class="permalink" href="#CRK_MOD_ADD"><code class="Dv">CRK_MOD_ADD</code></a></td> - <td>3</td> - <td>1</td> - </tr> - <tr id="CRK_MOD_ADDINV"> - <td><a class="permalink" href="#CRK_MOD_ADDINV"><code class="Dv">CRK_MOD_ADDINV</code></a></td> - <td>2</td> - <td>1</td> - </tr> - <tr id="CRK_MOD_SUB"> - <td><a class="permalink" href="#CRK_MOD_SUB"><code class="Dv">CRK_MOD_SUB</code></a></td> - <td>3</td> - <td>1</td> - </tr> - <tr id="CRK_MOD_MULT"> - <td><a class="permalink" href="#CRK_MOD_MULT"><code class="Dv">CRK_MOD_MULT</code></a></td> - <td>3</td> - <td>1</td> - </tr> - <tr id="CRK_MOD_MULTINV"> - <td><a class="permalink" href="#CRK_MOD_MULTINV"><code class="Dv">CRK_MOD_MULTINV</code></a></td> - <td>2</td> - <td>1</td> - </tr> - <tr id="CRK_MOD"> - <td><a class="permalink" href="#CRK_MOD"><code class="Dv">CRK_MOD</code></a></td> - <td>2</td> - <td>1</td> - </tr> - <tr id="CRK_DSA_SIGN"> - <td><a class="permalink" href="#CRK_DSA_SIGN"><code class="Dv">CRK_DSA_SIGN</code></a></td> - <td>5</td> - <td>2</td> - </tr> - <tr id="CRK_DSA_VERIFY"> - <td><a class="permalink" href="#CRK_DSA_VERIFY"><code class="Dv">CRK_DSA_VERIFY</code></a></td> - <td>7</td> - <td>0</td> - </tr> - <tr id="CRK_DH_COMPUTE_KEY"> - <td><a class="permalink" href="#CRK_DH_COMPUTE_KEY"><code class="Dv">CRK_DH_COMPUTE_KEY</code></a></td> - <td>3</td> - <td>1</td> - </tr> -</table> -<p class="Pp">See below for discussion of the input and output parameter - counts.</p> -</section> -<section class="Ss"> -<h2 class="Ss" id="Asymmetric-key_commands"><a class="permalink" href="#Asymmetric-key_commands">Asymmetric-key - commands</a></h2> -<dl class="Bl-tag"> - <dt id="CIOCASYMFEAT"><a class="permalink" href="#CIOCASYMFEAT"><code class="Dv">CIOCASYMFEAT</code></a> - <var class="Fa">int *feature_mask</var></dt> - <dd>Returns a bitmask of supported asymmetric-key operations. Each of the - above-listed asymmetric operations is present if and only if the bit - position numbered by the code for that operation is set. For example, - <code class="Dv">CRK_MOD_EXP</code> is available if and only if the bit (1 - << <code class="Dv">CRK_MOD_EXP</code>) is set.</dd> - <dt id="CIOCKEY"><a class="permalink" href="#CIOCKEY"><code class="Dv">CIOCKEY</code></a> - <var class="Fa">struct crypt_kop *kop</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct crypt_kop { - u_int crk_op; /* e.g. CRK_MOD_EXP */ - u_int crk_status; /* return status */ - u_short crk_iparams; /* # of input params */ - u_short crk_oparams; /* # of output params */ - u_int crk_pad1; - struct crparam crk_param[CRK_MAXPARAM]; -}; - -/* Bignum parameter, in packed bytes. */ -struct crparam { - void * crp_p; - u_int crp_nbits; -}; - - </pre> - </div> - Performs an asymmetric-key operation from the list above. The specific - operation is supplied in <var class="Fa">kop->crk_op</var>; final - status for the operation is returned in - <var class="Fa">kop->crk_status</var>. The number of input arguments - and the number of output arguments is specified in - <var class="Fa">kop->crk_iparams</var> and - <var class="Fa">kop->crk_iparams</var>, respectively. The field - <var class="Fa">crk_param[]</var> must be filled in with exactly - <var class="Fa">kop->crk_iparams + kop->crk_oparams</var> arguments, - each encoded as a <var class="Fa">struct crparam</var> (address, - bitlength) pair. - <p class="Pp">The semantics of these arguments are currently - undocumented.</p> - </dd> - <dt id="CIOCNFKEYM"><a class="permalink" href="#CIOCNFKEYM"><code class="Dv">CIOCNFKEYM</code></a> - <var class="Fa">struct crypt_mkop *mkop</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct crypt_mkop { - size_t count; /* how many */ - struct crypt_n_op * reqs; /* where to get them */ -}; - -struct crypt_n_kop { - u_int crk_op; /* e.g. CRK_MOD_EXP */ - u_int crk_status; /* accepted or not */ - u_short crk_iparams; /* # of input params */ - u_short crk_oparams; /* # of output params */ - u_int32_t crk_reqid; /* request id */ - struct crparam crk_param[CRK_MAXPARAM]; - void *crk_opaque; /* opaque pointer ret to user */ -}; - - </pre> - </div> - This is the asynchronous version of <code class="Dv">CIOCKEY</code>, which - starts one or more key operations. See <code class="Dv">CIOCNCRYPTM</code> - above and <code class="Dv">CIOCNCRYPTRETM</code> below for descriptions of - the <var class="Fa">mkop>count</var>, - <var class="Fa">mkop>reqs</var>, - <var class="Fa">mkop>reqs[n].crk_reqid</var>, - <var class="Fa">mkop>reqs[n].crk_status</var>, and - <var class="Fa">mkop>reqs[n].crk_opaque</var> fields of the argument - structure, and result retrieval.</dd> -</dl> -</section> -<section class="Ss"> -<h2 class="Ss" id="Asynchronous_status_commands"><a class="permalink" href="#Asynchronous_status_commands">Asynchronous - status commands</a></h2> -<p class="Pp">When requests are submitted with the - <code class="Dv">CIOCNCRYPTM</code> or <code class="Dv">CIOCNFKEYM</code> - commands, result retrieval is asynchronous (the submit ioctls return - immediately). Use the <a class="Xr">select(2)</a> or - <a class="Xr">poll(2)</a> functions to determine when the file descriptor - has completed operations ready to be retrieved.</p> -<dl class="Bl-tag"> - <dt id="CIOCNCRYPTRET"><a class="permalink" href="#CIOCNCRYPTRET"><code class="Dv">CIOCNCRYPTRET</code></a> - <var class="Fa">struct crypt_result *cres</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct crypt_result { - u_int32_t reqid; /* request ID */ - u_int32_t status; /* 0 if successful */ - void * opaque; /* pointer from user */ -}; - - </pre> - </div> - Check for the status of the request specified by - <var class="Fa">cres->reqid</var>. This requires a linear search - through all completed requests and should be used with extreme care if the - number of requests pending on this file descriptor may be large. - <p class="Pp">The <var class="Fa">cres->status</var> field is set as - follows:</p> - <dl class="Bl-tag"> - <dt>0</dt> - <dd>The request has completed, and its results have been copied out to the - original <var class="Fa">crypt_n_op or</var> - <var class="Fa">crypt_n_kop</var> structure used to start the request. - The copyout occurs during this ioctl, so the calling process must be - the process that started the request.</dd> - <dt>EINPROGRESS</dt> - <dd>The request has not yet completed.</dd> - <dt>EINVAL</dt> - <dd>The request was not found.</dd> - </dl> - <p class="Pp">Other values indicate a problem during the processing of the - request.</p> - </dd> - <dt id="CIOCNCRYPTRETM"><a class="permalink" href="#CIOCNCRYPTRETM"><code class="Dv">CIOCNCRYPTRETM</code></a> - <var class="Fa">struct cryptret_t *cret</var></dt> - <dd> - <div class="Bd Pp Li"> - <pre>struct cryptret { - size_t count; /* space for how many */ - struct crypt_result * results; /* where to put them */ -}; - - </pre> - </div> - Retrieve a number of completed requests. This ioctl accepts a count and an - array (each array element is a <var class="Fa">crypt_result_t</var> - structure as used by <code class="Dv">CIOCNCRYPTRET</code> above) and - fills the array with up to <var class="Fa">cret->count</var> results of - completed requests. - <p class="Pp">This ioctl fills in the - <var class="Fa">cret->results[n].reqid field</var>, so that the - request which has completed may be identified by the application. Note - that the results may include requests submitted both as symmetric and - asymmetric operations.</p> - </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">hifn(4)</a>, <a class="Xr">ubsec(4)</a>, - <a class="Xr">opencrypto(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 is derived from a - version which appeared in <span class="Ux">FreeBSD 4.8</span>, which in turn - is based on code which appeared in <span class="Ux">OpenBSD 3.2</span>.</p> -<p class="Pp">The "new API" for asynchronous operation with multiple - basic operations per system call (the "N" ioctl variants) was - contributed by Coyote Point Systems, Inc. and first appeared in - <span class="Ux">NetBSD 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> -<p class="Pp">The scheme for passing arguments for asymmetric requests is - baroque.</p> -<p class="Pp">The naming inconsistency between <code class="Dv">CRIOGET</code> - and the various <code class="Dv">CIOC</code>* names is an unfortunate - historical artifact.</p> -</section> -</div> -<table class="foot"> - <tr> - <td class="foot-date">January 27, 2014</td> - <td class="foot-os">NetBSD 10.1</td> - </tr> -</table> |