|
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_ASSERT_SET_AUTHDATA(3)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">FIDO_ASSERT_SET_AUTHDATA(3)</td>
<td class="head-vol">FreeBSD Library Functions Manual</td>
<td class="head-rtitle">FIDO_ASSERT_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_assert_set_authdata</code>,
<code class="Nm">fido_assert_set_authdata_raw</code>,
<code class="Nm">fido_assert_set_clientdata</code>,
<code class="Nm">fido_assert_set_clientdata_hash</code>,
<code class="Nm">fido_assert_set_count</code>,
<code class="Nm">fido_assert_set_extensions</code>,
<code class="Nm">fido_assert_set_hmac_salt</code>,
<code class="Nm">fido_assert_set_hmac_secret</code>,
<code class="Nm">fido_assert_set_up</code>,
<code class="Nm">fido_assert_set_uv</code>,
<code class="Nm">fido_assert_set_rp</code>,
<code class="Nm">fido_assert_set_sig</code>,
<code class="Nm">fido_assert_set_winhello_appid</code> —
<span class="Nd">set parameters of a FIDO2 assertion</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_assert_set_authdata</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</var>, <var class="Fa" style="white-space: nowrap;">size_t idx</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_assert_set_authdata_raw</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</var>, <var class="Fa" style="white-space: nowrap;">size_t
idx</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_assert_set_clientdata</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</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_assert_set_clientdata_hash</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</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_assert_set_count</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</var>, <var class="Fa" style="white-space: nowrap;">size_t
n</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_assert_set_extensions</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</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_assert_set_hmac_salt</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</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_assert_set_hmac_secret</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</var>, <var class="Fa" style="white-space: nowrap;">size_t
idx</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_assert_set_up</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</var>, <var class="Fa" style="white-space: nowrap;">fido_opt_t
up</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_assert_set_uv</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</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_assert_set_rp</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</var>, <var class="Fa" style="white-space: nowrap;">const char
*id</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_assert_set_sig</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</var>, <var class="Fa" style="white-space: nowrap;">size_t
idx</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_assert_set_winhello_appid</code>(<var class="Fa" style="white-space: nowrap;">fido_assert_t
*assert</var>, <var class="Fa" style="white-space: nowrap;">const char
*id</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_assert_set_authdata</code> set of
functions define the various parameters of a FIDO2 assertion, allowing a
<var class="Fa">fido_assert_t</var> type to be prepared for a subsequent
call to
<a class="Xr" href="fido_dev_get_assert.html">fido_dev_get_assert(3)</a> or
<a class="Xr" href="fido_assert_verify.html">fido_assert_verify(3)</a>. For
the complete specification of a FIDO2 assertion and the format of its
constituent parts, please refer to the Web Authentication (webauthn)
standard.</p>
<p class="Pp" id="fido_assert_set_count">The
<a class="permalink" href="#fido_assert_set_count"><code class="Fn">fido_assert_set_count</code></a>()
function sets the number of assertion statements in
<var class="Fa">assert</var> to <var class="Fa">n</var>.</p>
<p class="Pp" id="fido_assert_set_authdata">The
<a class="permalink" href="#fido_assert_set_authdata"><code class="Fn">fido_assert_set_authdata</code></a>()
and
<a class="permalink" href="#fido_assert_set_sig"><code class="Fn" id="fido_assert_set_sig">fido_assert_set_sig</code></a>()
functions set the authenticator data and signature parts of the statement
with index <var class="Fa">idx</var> of <var class="Fa">assert</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. Please note that the
first assertion statement of <var class="Fa">assert</var> has an
<var class="Fa">idx</var> of
<a class="permalink" href="#0"><i class="Em" id="0">0</i></a>. The
authenticator data passed to
<code class="Fn">fido_assert_set_authdata</code>() must be a CBOR-encoded
byte string, as obtained from
<a class="permalink" href="#fido_assert_authdata_ptr"><code class="Fn" id="fido_assert_authdata_ptr">fido_assert_authdata_ptr</code></a>().
Alternatively, a raw binary blob may be passed to
<a class="permalink" href="#fido_assert_set_authdata_raw"><code class="Fn" id="fido_assert_set_authdata_raw">fido_assert_set_authdata_raw</code></a>().</p>
<p class="Pp" id="fido_assert_set_clientdata_hash">The
<a class="permalink" href="#fido_assert_set_clientdata_hash"><code class="Fn">fido_assert_set_clientdata_hash</code></a>()
function sets the client data hash of <var class="Fa">assert</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_assert_set_clientdata">The
<a class="permalink" href="#fido_assert_set_clientdata"><code class="Fn">fido_assert_set_clientdata</code></a>()
function allows an application to set the client data hash of
<var class="Fa">assert</var> by specifying the assertion'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_assert_set_clientdata</code>() instead of
<code class="Fn">fido_assert_set_clientdata_hash</code>().</p>
<p class="Pp" id="fido_assert_set_rp">The
<a class="permalink" href="#fido_assert_set_rp"><code class="Fn">fido_assert_set_rp</code></a>()
function sets the relying party <var class="Fa">id</var> of
<var class="Fa">assert</var>, where <var class="Fa">id</var> is a
NUL-terminated UTF-8 string. The content of <var class="Fa">id</var> is
copied, and no references to the passed pointer are kept.</p>
<p class="Pp" id="fido_assert_set_extensions">The
<a class="permalink" href="#fido_assert_set_extensions"><code class="Fn">fido_assert_set_extensions</code></a>()
function sets the extensions of <var class="Fa">assert</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_HMAC_SECRET</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">assert</var> are cleared.</p>
<p class="Pp" id="fido_assert_set_hmac_salt">The
<a class="permalink" href="#fido_assert_set_hmac_salt"><code class="Fn">fido_assert_set_hmac_salt</code></a>()
and
<a class="permalink" href="#fido_assert_set_hmac_secret"><code class="Fn" id="fido_assert_set_hmac_secret">fido_assert_set_hmac_secret</code></a>()
functions set the hmac-salt and hmac-secret parts of
<var class="Fa">assert</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. The HMAC Secret (hmac-secret) Extension is a CTAP 2.0
extension. Note that the resulting hmac-secret varies according to whether
user verification was performed by the authenticator. The
<code class="Fn">fido_assert_set_hmac_secret</code>() function is normally
only useful when writing tests.</p>
<p class="Pp" id="fido_assert_set_up">The
<a class="permalink" href="#fido_assert_set_up"><code class="Fn">fido_assert_set_up</code></a>()
and
<a class="permalink" href="#fido_assert_set_uv"><code class="Fn" id="fido_assert_set_uv">fido_assert_set_uv</code></a>()
functions set the <var class="Fa">up</var> (user presence) and
<var class="Fa">uv</var> (user verification) attributes of
<var class="Fa">assert</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_assert_set_winhello_appid">The
<a class="permalink" href="#fido_assert_set_winhello_appid"><code class="Fn">fido_assert_set_winhello_appid</code></a>()
function sets the U2F application <var class="Fa">id</var> (“U2F
AppID”) of <var class="Fa">assert</var>, where
<var class="Fa">id</var> is a NUL-terminated UTF-8 string. The content of
<var class="Fa">id</var> is copied, and no references to the passed pointer
are kept. The <code class="Fn">fido_assert_set_winhello_appid</code>()
function is a no-op unless <var class="Fa">assert</var> is passed to
<a class="Xr" href="fido_dev_get_assert.html">fido_dev_get_assert(3)</a>
with a device <var class="Fa">dev</var> on which
<a class="Xr" href="fido_dev_is_winhello.html">fido_dev_is_winhello(3)</a>
holds true. In this case, <i class="Em">libfido2</i> will instruct Windows
Hello to try the assertion twice, first with the <var class="Fa">id</var>
passed to <code class="Fn">fido_assert_set_rp</code>(), and a second time
with the <var class="Fa">id</var> passed to
<code class="Fn">fido_assert_set_winhello_appid</code>(). If the second
assertion succeeds,
<a class="Xr" href="fido_assert_rp_id.html">fido_assert_rp_id(3)</a> will
point to the U2F AppID once
<a class="Xr" href="fido_dev_get_assert.html">fido_dev_get_assert(3)</a>
completes. This mechanism exists in Windows Hello to ensure U2F backwards
compatibility without the application inadvertently prompting the user
twice. Note that <code class="Fn">fido_assert_set_winhello_appid</code>() is
not needed on platforms offering CTAP primitives, since the authenticator
can be silently probed for the existence of U2F credentials.</p>
<p class="Pp">Use of the <code class="Nm">fido_assert_set_authdata</code> set of
functions may happen in two distinct situations: when asking a FIDO2 device
to produce a series of assertion statements, prior to
<a class="Xr" href="fido_dev_get_assert.html">fido_dev_get_assert(3)</a>
(i.e, in the context of a FIDO2 client), or when verifying assertion
statements using
<a class="Xr" href="fido_assert_verify.html">fido_assert_verify(3)</a> (i.e,
in the context of a FIDO2 server).</p>
<p class="Pp">For a complete description of the generation of a FIDO2 assertion
and its verification, please refer to the FIDO2 specification. An example of
how to use the <code class="Nm">fido_assert_set_authdata</code> set of
functions can be found in the <span class="Pa">examples/assert.c</span> file
shipped with <i class="Em">libfido2</i>.</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 <code class="Nm">fido_assert_set_authdata</code> functions
return <code class="Dv">FIDO_OK</code> on success. The error codes returned
by the <code class="Nm">fido_assert_set_authdata</code> set of functions are
defined in <code class="In"><<a class="In">fido/err.h</a>></code>.</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_assert_allow_cred.html">fido_assert_allow_cred(3)</a>,
<a class="Xr" href="fido_assert_verify.html">fido_assert_verify(3)</a>,
<a class="Xr" href="fido_dev_get_assert.html">fido_dev_get_assert(3)</a>,
<a class="Xr" href="fido_dev_is_winhello.html">fido_dev_is_winhello(3)</a></p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">April 8, 2023</td>
<td class="foot-os">Yubico AB</td>
</tr>
</table>
</body>
</html>