|
Server : Apache/2.4.62 System : FreeBSD fbsdweb2.web.rcn.net 14.1-RELEASE FreeBSD 14.1-RELEASE releng/14.1-n267679-10e31f0946d8 GENERIC amd64 User : www ( 80) PHP Version : 8.3.8 Disable Function : NONE Directory : /usr/local/share/doc/libfido2/html/ |
Upload File : |
<!DOCTYPE html>
<html>
<!-- This is an automatically generated file. Do not edit.
Copyright (c) 2018-2022 Yubico AB. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in
the documentation and/or other materials provided with the
distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
SPDX-License-Identifier: BSD-2-Clause
-->
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1.0"/>
<link rel="stylesheet" href="style.css" type="text/css" media="all"/>
<title>FIDO_CRED_SET_AUTHDATA(3)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">FIDO_CRED_SET_AUTHDATA(3)</td>
<td class="head-vol">FreeBSD Library Functions Manual</td>
<td class="head-rtitle">FIDO_CRED_SET_AUTHDATA(3)</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">fido_cred_set_authdata</code>,
<code class="Nm">fido_cred_set_authdata_raw</code>,
<code class="Nm">fido_cred_set_attstmt</code>,
<code class="Nm">fido_cred_set_attobj</code>,
<code class="Nm">fido_cred_set_x509</code>,
<code class="Nm">fido_cred_set_sig</code>,
<code class="Nm">fido_cred_set_id</code>,
<code class="Nm">fido_cred_set_clientdata</code>,
<code class="Nm">fido_cred_set_clientdata_hash</code>,
<code class="Nm">fido_cred_set_rp</code>,
<code class="Nm">fido_cred_set_user</code>,
<code class="Nm">fido_cred_set_extensions</code>,
<code class="Nm">fido_cred_set_blob</code>,
<code class="Nm">fido_cred_set_pin_minlen</code>,
<code class="Nm">fido_cred_set_prot</code>,
<code class="Nm">fido_cred_set_rk</code>,
<code class="Nm">fido_cred_set_uv</code>,
<code class="Nm">fido_cred_set_fmt</code>,
<code class="Nm">fido_cred_set_type</code> — <span class="Nd">set
parameters of a FIDO2 credential</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">fido.h</a>></code></p>
<div class="Bd Pp Li">
<pre>typedef enum {
FIDO_OPT_OMIT = 0, /* use authenticator's default */
FIDO_OPT_FALSE, /* explicitly set option to false */
FIDO_OPT_TRUE, /* explicitly set option to true */
} fido_opt_t;</pre>
</div>
<br/>
<var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_authdata</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned char
*ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t len</var>);
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_authdata_raw</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_attstmt</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_attobj</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_x509</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_sig</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_id</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_clientdata</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_clientdata_hash</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_rp</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const char
*id</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_user</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *user_id</var>, <var class="Fa" style="white-space: nowrap;">size_t
user_id_len</var>, <var class="Fa" style="white-space: nowrap;">const char
*name</var>, <var class="Fa" style="white-space: nowrap;">const char
*display_name</var>, <var class="Fa" style="white-space: nowrap;">const char
*icon</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_extensions</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">int
flags</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_blob</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_pin_minlen</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">size_t
len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_prot</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">int
prot</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_rk</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">fido_opt_t
rk</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_uv</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">fido_opt_t
uv</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_fmt</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">const char
*ptr</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_cred_set_type</code>(<var class="Fa" style="white-space: nowrap;">fido_cred_t
*cred</var>, <var class="Fa" style="white-space: nowrap;">int
cose_alg</var>);</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">fido_cred_set_authdata</code> set of
functions define the various parameters of a FIDO2 credential, allowing a
<var class="Fa">fido_cred_t</var> type to be prepared for a subsequent call
to <a class="Xr" href="fido_dev_make_cred.html">fido_dev_make_cred(3)</a> or
<a class="Xr" href="fido_cred_verify.html">fido_cred_verify(3)</a>. For the
complete specification of a FIDO2 credential and the format of its
constituent parts, please refer to the Web Authentication (webauthn)
standard.</p>
<p class="Pp" id="fido_cred_set_authdata">The
<a class="permalink" href="#fido_cred_set_authdata"><code class="Fn">fido_cred_set_authdata</code></a>(),
<code class="Fn">fido_cred_set_attstmt</code>(),
<code class="Fn">fido_cred_set_attobj</code>(),
<a class="permalink" href="#fido_cred_set_x509"><code class="Fn" id="fido_cred_set_x509">fido_cred_set_x509</code></a>(),
<a class="permalink" href="#fido_cred_set_sig"><code class="Fn" id="fido_cred_set_sig">fido_cred_set_sig</code></a>(),
<code class="Fn">fido_cred_set_id</code>(), and
<code class="Fn">fido_cred_set_clientdata_hash</code>() functions set the
authenticator data, attestation statement, attestation object, attestation
certificate, attestation signature, id, and client data hash parts of
<var class="Fa">cred</var> to <var class="Fa">ptr</var>, where
<var class="Fa">ptr</var> points to <var class="Fa">len</var> bytes. A copy
of <var class="Fa">ptr</var> is made, and no references to the passed
pointer are kept.</p>
<p class="Pp" id="fido_cred_set_authdata~2">The authenticator data passed to
<a class="permalink" href="#fido_cred_set_authdata~2"><code class="Fn">fido_cred_set_authdata</code></a>()
must be a CBOR-encoded byte string, as obtained from
<a class="permalink" href="#fido_cred_authdata_ptr"><code class="Fn" id="fido_cred_authdata_ptr">fido_cred_authdata_ptr</code></a>().
Alternatively, a raw binary blob may be passed to
<a class="permalink" href="#fido_cred_set_authdata_raw"><code class="Fn" id="fido_cred_set_authdata_raw">fido_cred_set_authdata_raw</code></a>().
An application calling <code class="Fn">fido_cred_set_authdata</code>() does
not need to call
<a class="permalink" href="#fido_cred_set_id"><code class="Fn" id="fido_cred_set_id">fido_cred_set_id</code></a>().
The latter is meant to be used in contexts where the credential's
authenticator data is not available.</p>
<p class="Pp" id="fido_cred_set_attstmt">The attestation statement passed to
<a class="permalink" href="#fido_cred_set_attstmt"><code class="Fn">fido_cred_set_attstmt</code></a>()
must be a CBOR-encoded map, as obtained from
<a class="permalink" href="#fido_cred_attstmt_ptr"><code class="Fn" id="fido_cred_attstmt_ptr">fido_cred_attstmt_ptr</code></a>().
An application calling <code class="Fn">fido_cred_set_attstmt</code>() does
not need to call
<a class="permalink" href="#fido_cred_set_x509~2"><code class="Fn" id="fido_cred_set_x509~2">fido_cred_set_x509</code></a>()
or
<a class="permalink" href="#fido_cred_set_sig~2"><code class="Fn" id="fido_cred_set_sig~2">fido_cred_set_sig</code></a>().
The latter two are meant to be used in contexts where the credential's
complete attestation statement is not available or required.</p>
<p class="Pp" id="fido_cred_set_attobj">The attestation object passed to
<a class="permalink" href="#fido_cred_set_attobj"><code class="Fn">fido_cred_set_attobj</code></a>()
must be a CBOR-encoded map containing “authData”,
“fmt”, and “attStmt”. An application calling
<code class="Fn">fido_cred_set_attobj</code>() does not need to call
<code class="Fn">fido_cred_set_fmt</code>(),
<code class="Fn">fido_cred_set_attstmt</code>(),
<code class="Fn">fido_cred_set_authdata</code>(), or
<code class="Fn">fido_cred_set_authdata_raw</code>().
<code class="Fn">fido_cred_set_attobj</code>() may be useful in applications
interfacing with the WebAuthn API, removing the need to first parse the
attestation object to verify the credential.</p>
<p class="Pp" id="fido_cred_set_clientdata">The
<a class="permalink" href="#fido_cred_set_clientdata"><code class="Fn">fido_cred_set_clientdata</code></a>()
function allows an application to set the client data hash of
<var class="Fa">cred</var> by specifying the credential's unhashed client
data. This is required by Windows Hello, which calculates the client data
hash internally. For compatibility with Windows Hello, applications should
use <code class="Fn">fido_cred_set_clientdata</code>() instead of
<a class="permalink" href="#fido_cred_set_clientdata_hash"><code class="Fn" id="fido_cred_set_clientdata_hash">fido_cred_set_clientdata_hash</code></a>().</p>
<p class="Pp" id="fido_cred_set_rp">The
<a class="permalink" href="#fido_cred_set_rp"><code class="Fn">fido_cred_set_rp</code></a>()
function sets the relying party <var class="Fa">id</var> and
<var class="Fa">name</var> parameters of <var class="Fa">cred</var>, where
<var class="Fa">id</var> and <var class="Fa">name</var> are NUL-terminated
UTF-8 strings. The contents of <var class="Fa">id</var> and
<var class="Fa">name</var> are copied, and no references to the passed
pointers are kept.</p>
<p class="Pp" id="fido_cred_set_user">The
<a class="permalink" href="#fido_cred_set_user"><code class="Fn">fido_cred_set_user</code></a>()
function sets the user attributes of <var class="Fa">cred</var>, where
<var class="Fa">user_id</var> points to <var class="Fa">user_id_len</var>
bytes and <var class="Fa">name</var>, <var class="Fa">display_name</var>,
and <var class="Fa">icon</var> are NUL-terminated UTF-8 strings. The
contents of <var class="Fa">user_id</var>, <var class="Fa">name</var>,
<var class="Fa">display_name</var>, and <var class="Fa">icon</var> are
copied, and no references to the passed pointers are kept. Previously set
user attributes are flushed. The <var class="Fa">user_id</var>,
<var class="Fa">name</var>, <var class="Fa">display_name</var>, and
<var class="Fa">icon</var> parameters may be NULL.</p>
<p class="Pp" id="fido_cred_set_extensions">The
<a class="permalink" href="#fido_cred_set_extensions"><code class="Fn">fido_cred_set_extensions</code></a>()
function sets the extensions of <var class="Fa">cred</var> to the bitmask
<var class="Fa">flags</var>. At the moment, only the
<code class="Dv">FIDO_EXT_CRED_BLOB</code>,
<code class="Dv">FIDO_EXT_CRED_PROTECT</code>,
<code class="Dv">FIDO_EXT_HMAC_SECRET</code>,
<code class="Dv">FIDO_EXT_MINPINLEN</code>, and
<code class="Dv">FIDO_EXT_LARGEBLOB_KEY</code> extensions are supported. If
<var class="Fa">flags</var> is zero, the extensions of
<var class="Fa">cred</var> are cleared.</p>
<p class="Pp" id="fido_cred_set_blob">The
<a class="permalink" href="#fido_cred_set_blob"><code class="Fn">fido_cred_set_blob</code></a>()
function sets the “credBlob” to be stored with
<var class="Fa">cred</var> to the data pointed to by
<var class="Fa">ptr</var>, which must be <var class="Fa">len</var> bytes
long.</p>
<p class="Pp" id="fido_cred_set_pin_minlen">The
<a class="permalink" href="#fido_cred_set_pin_minlen"><code class="Fn">fido_cred_set_pin_minlen</code></a>()
function enables the CTAP 2.1 <code class="Dv">FIDO_EXT_MINPINLEN</code>
extension on <var class="Fa">cred</var> and sets the expected minimum PIN
length of <var class="Fa">cred</var> to <var class="Fa">len</var>, where
<var class="Fa">len</var> is greater than zero. If <var class="Fa">len</var>
is zero, the <code class="Dv">FIDO_EXT_MINPINLEN</code> extension is
disabled on <var class="Fa">cred</var>.</p>
<p class="Pp" id="fido_cred_set_prot">The
<a class="permalink" href="#fido_cred_set_prot"><code class="Fn">fido_cred_set_prot</code></a>()
function enables the CTAP 2.1 <code class="Dv">FIDO_EXT_CRED_PROTECT</code>
extension on <var class="Fa">cred</var> and sets the protection of
<var class="Fa">cred</var> to the scalar <var class="Fa">prot</var>. At the
moment, only the <code class="Dv">FIDO_CRED_PROT_UV_OPTIONAL</code>,
<code class="Dv">FIDO_CRED_PROT_UV_OPTIONAL_WITH_ID</code>, and
<code class="Dv">FIDO_CRED_PROT_UV_REQUIRED</code> protections are
supported. If <var class="Fa">prot</var> is zero, the protection of
<var class="Fa">cred</var> is cleared.</p>
<p class="Pp" id="fido_cred_set_rk">The
<a class="permalink" href="#fido_cred_set_rk"><code class="Fn">fido_cred_set_rk</code></a>()
and
<a class="permalink" href="#fido_cred_set_uv"><code class="Fn" id="fido_cred_set_uv">fido_cred_set_uv</code></a>()
functions set the
<a class="permalink" href="#rk"><i class="Em" id="rk">rk</i></a>
(resident/discoverable key) and
<a class="permalink" href="#uv"><i class="Em" id="uv">uv</i></a> (user
verification) attributes of <var class="Fa">cred</var>. Both are
<code class="Dv">FIDO_OPT_OMIT</code> by default, allowing the authenticator
to use its default settings.</p>
<p class="Pp" id="fido_cred_set_fmt">The
<a class="permalink" href="#fido_cred_set_fmt"><code class="Fn">fido_cred_set_fmt</code></a>()
function sets the attestation statement format identifier of
<var class="Fa">cred</var> to <var class="Fa">fmt</var>, where
<var class="Fa">fmt</var> must be <var class="Vt">packed</var> (the format
used in FIDO2), <var class="Vt">fido-u2f</var> (the format used in U2F),
<var class="Vt">tpm</var> (the format used by TPM-based authenticators), or
<var class="Vt">none</var>. A copy of <var class="Fa">fmt</var> is made, and
no references to the passed pointer are kept. Note that not all
authenticators support FIDO2 and therefore may only be able to generate
<var class="Vt">fido-u2f</var> attestation statements.</p>
<p class="Pp" id="fido_cred_set_type">The
<a class="permalink" href="#fido_cred_set_type"><code class="Fn">fido_cred_set_type</code></a>()
function sets the type of <var class="Fa">cred to</var>
<var class="Fa">cose_alg</var>, where <var class="Fa">cose_alg</var> is
<code class="Dv">COSE_ES256</code>, <code class="Dv">COSE_ES384</code>,
<code class="Dv">COSE_RS256</code>, or <code class="Dv">COSE_EDDSA</code>.
The type of a credential may only be set once. Note that not all
authenticators support COSE_RS256, COSE_ES384, or COSE_EDDSA.</p>
<p class="Pp">Use of the <code class="Nm">fido_cred_set_authdata</code> set of
functions may happen in two distinct situations: when generating a new
credential on a FIDO2 device, prior to
<a class="Xr" href="fido_dev_make_cred.html">fido_dev_make_cred(3)</a> (i.e,
in the context of a FIDO2 client), or when validating a generated credential
using <a class="Xr" href="fido_cred_verify.html">fido_cred_verify(3)</a>
(i.e, in the context of a FIDO2 server).</p>
<p class="Pp" id="libfido2">For a complete description of the generation of a
FIDO2 credential and its verification, please refer to the FIDO2
specification. A concrete utilisation example of the
<code class="Nm">fido_cred_set_authdata</code> set of functions can be found
in the <span class="Pa">cred.c</span> example shipped with
<a class="permalink" href="#libfido2"><i class="Em">libfido2</i></a>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">The error codes returned by the
<code class="Nm">fido_cred_set_authdata</code> set of functions are defined
in <code class="In"><<a class="In">fido/err.h</a>></code>. On success,
<code class="Dv">FIDO_OK</code> is returned.</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" href="fido_cred_exclude.html">fido_cred_exclude(3)</a>,
<a class="Xr" href="fido_cred_verify.html">fido_cred_verify(3)</a>,
<a class="Xr" href="fido_dev_make_cred.html">fido_dev_make_cred(3)</a></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">July 15, 2022</td>
<td class="foot-os">Yubico AB</td>
</tr>
</table>
</body>
</html>