|
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) 2020 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_LARGEBLOB_GET(3)</title>
</head>
<body>
<table class="head">
<tr>
<td class="head-ltitle">FIDO_LARGEBLOB_GET(3)</td>
<td class="head-vol">FreeBSD Library Functions Manual</td>
<td class="head-rtitle">FIDO_LARGEBLOB_GET(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_dev_largeblob_get</code>,
<code class="Nm">fido_dev_largeblob_set</code>,
<code class="Nm">fido_dev_largeblob_remove</code>,
<code class="Nm">fido_dev_largeblob_get_array</code>,
<code class="Nm">fido_dev_largeblob_set_array</code> —
<span class="Nd">FIDO2 large blob API</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>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_dev_largeblob_get</code>(<var class="Fa" style="white-space: nowrap;">fido_dev_t
*dev</var>, <var class="Fa" style="white-space: nowrap;">const unsigned char
*key_ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
key_len</var>, <var class="Fa" style="white-space: nowrap;">unsigned char
**blob_ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
*blob_len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_dev_largeblob_set</code>(<var class="Fa" style="white-space: nowrap;">fido_dev_t
*dev</var>, <var class="Fa" style="white-space: nowrap;">const unsigned char
*key_ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
key_len</var>, <var class="Fa" style="white-space: nowrap;">const unsigned
char *blob_ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
blob_len</var>, <var class="Fa" style="white-space: nowrap;">const char
*pin</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_dev_largeblob_remove</code>(<var class="Fa" style="white-space: nowrap;">fido_dev_t
*dev</var>, <var class="Fa" style="white-space: nowrap;">const unsigned char
*key_ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
key_len</var>, <var class="Fa" style="white-space: nowrap;">const char
*pin</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_dev_largeblob_get_array</code>(<var class="Fa" style="white-space: nowrap;">fido_dev_t
*dev</var>, <var class="Fa" style="white-space: nowrap;">unsigned char
**cbor_ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
*cbor_len</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">fido_dev_largeblob_set_array</code>(<var class="Fa" style="white-space: nowrap;">fido_dev_t
*dev</var>, <var class="Fa" style="white-space: nowrap;">const unsigned char
*cbor_ptr</var>, <var class="Fa" style="white-space: nowrap;">size_t
cbor_len</var>, <var class="Fa" style="white-space: nowrap;">const char
*pin</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The “largeBlobs” API of
<a class="permalink" href="#libfido2"><i class="Em" id="libfido2">libfido2</i></a>
allows binary blobs residing on a CTAP 2.1 authenticator to be read,
written, and inspected. “largeBlobs” is a CTAP 2.1
extension.</p>
<p class="Pp">“largeBlobs” are stored as elements of a CBOR array.
Confidentiality is ensured by encrypting each element with a distinct,
credential-bound 256-bit AES-GCM key. The array is otherwise shared between
different credentials and FIDO2 relying parties.</p>
<p class="Pp" id="libfido2's">Retrieval of a credential's encryption key is
possible during enrollment with
<a class="Xr" href="fido_cred_set_extensions.html">fido_cred_set_extensions(3)</a>
and
<a class="Xr" href="fido_cred_largeblob_key_ptr.html">fido_cred_largeblob_key_ptr(3)</a>,
during assertion with
<a class="Xr" href="fido_assert_set_extensions.html">fido_assert_set_extensions(3)</a>
and
<a class="Xr" href="fido_assert_largeblob_key_ptr.html">fido_assert_largeblob_key_ptr(3)</a>,
or, in the case of a resident credential, via
<a class="permalink" href="#libfido2's"><i class="Em">libfido2's</i></a>
credential management API.</p>
<p class="Pp">The “largeBlobs” CBOR array is opaque to the
authenticator. Management of the array is left at the discretion of FIDO2
clients. For further details on CTAP 2.1's “largeBlobs”
extension, please refer to the CTAP 2.1 spec.</p>
<p class="Pp" id="fido_dev_largeblob_get">The
<a class="permalink" href="#fido_dev_largeblob_get"><code class="Fn">fido_dev_largeblob_get</code></a>()
function retrieves the authenticator's “largeBlobs” CBOR array
and, on success, returns the first blob (iterating from array index zero)
that can be decrypted by <var class="Fa">key_ptr</var>, where
<var class="Fa">key_ptr</var> points to <var class="Fa">key_len</var> bytes.
On success, <code class="Fn">fido_dev_largeblob_get</code>() sets
<var class="Fa">blob_ptr</var> to the body of the decrypted blob, and
<var class="Fa">blob_len</var> to the length of the decrypted blob in bytes.
It is the caller's responsibility to free
<var class="Fa">blob_ptr</var>.</p>
<p class="Pp" id="fido_dev_largeblob_set">The
<a class="permalink" href="#fido_dev_largeblob_set"><code class="Fn">fido_dev_largeblob_set</code></a>()
function uses <var class="Fa">key_ptr</var> to encrypt
<var class="Fa">blob_ptr</var> and inserts the result in the authenticator's
“largeBlobs” CBOR array. Insertion happens at the end of the
array if no existing element can be decrypted by
<var class="Fa">key_ptr</var>, or at the position of the first element
(iterating from array index zero) that can be decrypted by
<var class="Fa">key_ptr</var>. <var class="Fa">key_len</var> holds the
length of <var class="Fa">key_ptr</var> in bytes, and
<var class="Fa">blob_len</var> the length of <var class="Fa">blob_ptr</var>
in bytes. A <var class="Fa">pin</var> or equivalent user-verification
gesture is required.</p>
<p class="Pp" id="fido_dev_largeblob_remove">The
<a class="permalink" href="#fido_dev_largeblob_remove"><code class="Fn">fido_dev_largeblob_remove</code></a>()
function retrieves the authenticator's “largeBlobs” CBOR array
and, on success, drops the first blob (iterating from array index zero) that
can be decrypted by <var class="Fa">key_ptr</var>, where
<var class="Fa">key_ptr</var> points to <var class="Fa">key_len</var> bytes.
A <var class="Fa">pin</var> or equivalent user-verification gesture is
required.</p>
<p class="Pp" id="fido_dev_largeblob_get_array">The
<a class="permalink" href="#fido_dev_largeblob_get_array"><code class="Fn">fido_dev_largeblob_get_array</code></a>()
function retrieves the authenticator's “largeBlobs” CBOR array
and, on success, sets <var class="Fa">cbor_ptr</var> to the body of the CBOR
array, and <var class="Fa">cbor_len</var> to its corresponding length in
bytes. It is the caller's responsibility to free
<var class="Fa">cbor_ptr</var>.</p>
<p class="Pp" id="fido_dev_largeblob_set_array">Finally, the
<a class="permalink" href="#fido_dev_largeblob_set_array"><code class="Fn">fido_dev_largeblob_set_array</code></a>()
function sets the authenticator's “largeBlobs” CBOR array to
the data pointed to by <var class="Fa">cbor_ptr</var>, where
<var class="Fa">cbor_ptr</var> points to <var class="Fa">cbor_len</var>
bytes. A <var class="Fa">pin</var> or equivalent user-verification gesture
is required.</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 functions <code class="Fn">fido_dev_largeblob_set</code>(),
<code class="Fn">fido_dev_largeblob_get</code>(),
<code class="Fn">fido_dev_largeblob_remove</code>(),
<code class="Fn">fido_dev_largeblob_get_array</code>(), and
<code class="Fn">fido_dev_largeblob_set_array</code>() return
<code class="Dv">FIDO_OK</code> on success. On error, an error code defined
in <code class="In"><<a class="In">fido/err.h</a>></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_assert_largeblob_key_len.html">fido_assert_largeblob_key_len(3)</a>,
<a class="Xr" href="fido_assert_largeblob_key_ptr.html">fido_assert_largeblob_key_ptr(3)</a>,
<a class="Xr" href="fido_assert_set_extensions.html">fido_assert_set_extensions(3)</a>,
<a class="Xr" href="fido_cred_largeblob_key_len.html">fido_cred_largeblob_key_len(3)</a>,
<a class="Xr" href="fido_cred_largeblob_key_ptr.html">fido_cred_largeblob_key_ptr(3)</a>,
<a class="Xr" href="fido_cred_set_extensions.html">fido_cred_set_extensions(3)</a>,
<a class="Xr" href="fido_credman_get_dev_rk.html">fido_credman_get_dev_rk(3)</a>,
<a class="Xr" href="fido_credman_get_dev_rp.html">fido_credman_get_dev_rp(3)</a>,
<a class="Xr" href="fido_dev_get_assert.html">fido_dev_get_assert(3)</a>,
<a class="Xr" href="fido_dev_make_cred.html">fido_dev_make_cred(3)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="CAVEATS"><a class="permalink" href="#CAVEATS">CAVEATS</a></h1>
<p class="Pp">The “largeBlobs” extension is not meant to be used
to store sensitive data. When retrieved, a credential's
“largeBlobs” encryption key is transmitted in the clear, and
an authenticator's “largeBlobs” CBOR array can be read without
user interaction or verification.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">October 26, 2020</td>
<td class="foot-os">Yubico AB</td>
</tr>
</table>
</body>
</html>