path: root/static/netbsd/man4/crypto.4 3.html

<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>
    &#x2014; <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 &lt;<a class="In">sys/ioctl.h</a>&gt;</code>
  <br/>
  <code class="In">#include &lt;<a class="In">sys/time.h</a>&gt;</code>
  <br/>
  <code class="In">#include
  &lt;<a class="In">crypto/cryptodev.h</a>&gt;</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;">&#x00A0;</dd>
  <dt>CRYPTO_3DES_CBC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_BLF_CBC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_CAST_CBC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_SKIPJACK_CBC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_AES_CBC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_ARC4</dt>
  <dd style="width: auto;">&#x00A0;</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;">&#x00A0;</dd>
  <dt>CRYPTO_MD5_KPDK</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_SHA1_KPDK</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_MD5_HMAC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_SHA1_HMAC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_SHA2_256_HMAC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_SHA2_384_HMAC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_SHA2_512_HMAC</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_MD5</dt>
  <dd style="width: auto;">&#x00A0;</dd>
  <dt>CRYPTO_SHA1</dt>
  <dd style="width: auto;">&#x00A0;</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-&gt;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-&gt;cipher</var>,
        the key length in <var class="Fa">sessp-&gt;keylen</var>, and the key
        value in the octets addressed by
      <var class="Fa">sessp-&gt;key</var>.</p>
    <p class="Pp">For keyed one-way hash algorithms, the one-way hash must be
        specified in <var class="Fa">sessp-&gt;mac</var>, the key length in
        <var class="Fa">sessp-&gt;mackey</var>, and the key value in the octets
        addressed by <var class="Fa">sessp-&gt;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-&gt;sessions[n].ses</var> and the status for that
      session creation in
    <var class="Fa">sgop-&gt;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-&gt;op</var> to
      <code class="Dv">COP_ENCRYPT</code>. To decrypt, set
      <var class="Fa">cr_op-&gt;op</var> to <code class="Dv">COP_DECRYPT</code>.
      The field <var class="Fa">cr_op-&gt;len</var> supplies the length of the
      input buffer; the fields <var class="Fa">cr_op-&gt;src</var>,
      <var class="Fa">cr_op-&gt;dst</var>, <var class="Fa">cr_op-&gt;mac</var>,
      <var class="Fa">cr_op-&gt;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-&gt;count</var> field specifies the
        number of operations provided in the cr_mop-&gt;reqs array.</p>
    <p class="Pp">Each operation is assigned a unique request id returned in the
        <var class="Fa">cr_mop-&gt;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-&gt;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-&gt;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-&gt;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
      &lt;&lt; <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-&gt;crk_op</var>; final
      status for the operation is returned in
      <var class="Fa">kop-&gt;crk_status</var>. The number of input arguments
      and the number of output arguments is specified in
      <var class="Fa">kop-&gt;crk_iparams</var> and
      <var class="Fa">kop-&gt;crk_iparams</var>, respectively. The field
      <var class="Fa">crk_param[]</var> must be filled in with exactly
      <var class="Fa">kop-&gt;crk_iparams + kop-&gt;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&gt;count</var>,
      <var class="Fa">mkop&gt;reqs</var>,
      <var class="Fa">mkop&gt;reqs[n].crk_reqid</var>,
      <var class="Fa">mkop&gt;reqs[n].crk_status</var>, and
      <var class="Fa">mkop&gt;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-&gt;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-&gt;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-&gt;count</var> results of
      completed requests.
    <p class="Pp">This ioctl fills in the
        <var class="Fa">cret-&gt;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 &quot;new API&quot; for asynchronous operation with multiple
    basic operations per system call (the &quot;N&quot; 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>