From 2dea5a08baeff0177508fd3a2a16b73ff92930c2 Mon Sep 17 00:00:00 2001 From: Ludvig Michaelsson Date: Mon, 13 Nov 2023 11:06:23 +0100 Subject: [PATCH] libfido2: sync docs with 1.14.0 - new API calls: * fido_assert_authdata_raw_len; * fido_assert_authdata_raw_ptr; * fido_assert_set_winhello_appid. --- .../libfido2/Manuals/fido2-assert.partial | 11 +++-- .../libfido2/Manuals/fido2-cred.partial | 11 +++-- .../fido_assert_authdata_raw_len.partial | 1 + .../fido_assert_authdata_raw_ptr.partial | 1 + .../libfido2/Manuals/fido_assert_new.partial | 26 ++++++++--- .../Manuals/fido_assert_set_authdata.partial | 43 +++++++++++++++++-- .../fido_assert_set_winhello_appid.partial | 1 + 7 files changed, 79 insertions(+), 15 deletions(-) create mode 120000 content/projects/libfido2/Manuals/fido_assert_authdata_raw_len.partial create mode 120000 content/projects/libfido2/Manuals/fido_assert_authdata_raw_ptr.partial create mode 120000 content/projects/libfido2/Manuals/fido_assert_set_winhello_appid.partial diff --git a/content/projects/libfido2/Manuals/fido2-assert.partial b/content/projects/libfido2/Manuals/fido2-assert.partial index 78cdf6418..a08f25720 100644 --- a/content/projects/libfido2/Manuals/fido2-assert.partial +++ b/content/projects/libfido2/Manuals/fido2-assert.partial @@ -28,7 +28,7 @@ fido2-assert -G - [
-bdhpruv
] + [
-bdhpruvw
] [
-t option
] [
-i @@ -144,6 +144,11 @@ The options are as follows:
If obtaining an assertion, prompt the user for a PIN and request user verification from the authenticator. If verifying an assertion, check whether the user verification bit was signed by the authenticator.
+
+
Tells fido2-assert that the first line + of input when obtaining an assertion shall be interpreted as unhashed + client data. This is required by Windows Hello, which calculates the + client data hash internally.
If a tty is available, @@ -222,7 +227,7 @@ Assuming cred contains a fido2-token(1)
- - + +
November 5, 2019Linux 5.3.12-arch1-1July 3, 2023Debian
diff --git a/content/projects/libfido2/Manuals/fido2-cred.partial b/content/projects/libfido2/Manuals/fido2-cred.partial index ebd196979..6e33710ed 100644 --- a/content/projects/libfido2/Manuals/fido2-cred.partial +++ b/content/projects/libfido2/Manuals/fido2-cred.partial @@ -28,7 +28,7 @@ fido2-cred -M - [
-bdhqruv
] + [
-bdhqruvw
] [
-c cred_protect
] [
-i @@ -139,6 +139,11 @@ The options are as follows:
If making a credential, request user verification. If verifying a credential, check whether the user verification bit was signed by the authenticator.
+
+
Tells fido2-cred that the first line of + input when making a credential shall be interpreted as unhashed client + data. This is required by Windows Hello, which calculates the client data + hash internally.

@@ -224,7 +229,7 @@ Please note that fido2-cred handles Basic not verified.
- - + +
November 5, 2019Linux 5.3.12-arch1-1July 3, 2023Debian
diff --git a/content/projects/libfido2/Manuals/fido_assert_authdata_raw_len.partial b/content/projects/libfido2/Manuals/fido_assert_authdata_raw_len.partial new file mode 120000 index 000000000..a2f125a8b --- /dev/null +++ b/content/projects/libfido2/Manuals/fido_assert_authdata_raw_len.partial @@ -0,0 +1 @@ +fido_assert_new.partial \ No newline at end of file diff --git a/content/projects/libfido2/Manuals/fido_assert_authdata_raw_ptr.partial b/content/projects/libfido2/Manuals/fido_assert_authdata_raw_ptr.partial new file mode 120000 index 000000000..a2f125a8b --- /dev/null +++ b/content/projects/libfido2/Manuals/fido_assert_authdata_raw_ptr.partial @@ -0,0 +1 @@ +fido_assert_new.partial \ No newline at end of file diff --git a/content/projects/libfido2/Manuals/fido_assert_new.partial b/content/projects/libfido2/Manuals/fido_assert_new.partial index 61db9b459..102b783a9 100644 --- a/content/projects/libfido2/Manuals/fido_assert_new.partial +++ b/content/projects/libfido2/Manuals/fido_assert_new.partial @@ -29,6 +29,7 @@ fido_assert_user_icon, fido_assert_user_name, fido_assert_authdata_ptr, + fido_assert_authdata_raw_ptr, fido_assert_blob_ptr, fido_assert_clientdata_hash_ptr, fido_assert_hmac_secret_ptr, @@ -37,6 +38,7 @@ fido_assert_sig_ptr, fido_assert_id_ptr, fido_assert_authdata_len, + fido_assert_authdata_raw_len, fido_assert_blob_len, fido_assert_clientdata_hash_len, fido_assert_hmac_secret_len, @@ -96,6 +98,12 @@
const unsigned char *
+fido_assert_authdata_raw_ptr(const + fido_assert_t *assert, + size_t idx); +
+const unsigned char * +
fido_assert_clientdata_hash_ptr(const fido_assert_t *assert);
@@ -143,6 +151,12 @@
size_t
+fido_assert_authdata_raw_len(const + fido_assert_t *assert, + size_t idx); +
+size_t +
fido_assert_clientdata_hash_len(const fido_assert_t *assert);
@@ -240,15 +254,16 @@ The fido_assert_user_display_name(), resident/discoverable credentials were involved in the assertion.
The fido_assert_authdata_ptr(), + fido_assert_authdata_raw_ptr(), fido_assert_clientdata_hash_ptr(), fido_assert_id_ptr(), fido_assert_user_id_ptr(), fido_assert_sig_ptr(), fido_assert_sigcount(), and fido_assert_flags() functions return - pointers to the CBOR-encoded authenticator data, client data hash, credential - ID, user ID, signature, signature count, and authenticator data flags of - statement idx in + pointers to the CBOR-encoded and raw authenticator data, client data hash, + credential ID, user ID, signature, signature count, and authenticator data + flags of statement idx in assert.
The fido_assert_hmac_secret_ptr() function @@ -268,6 +283,7 @@ The fido_assert_blob_ptr() and Blob Key (largeBlobKey) are CTAP 2.1 extensions.
The fido_assert_authdata_len(), + fido_assert_authdata_raw_len(), fido_assert_clientdata_hash_len(), fido_assert_id_len(), fido_assert_user_id_len(), @@ -314,7 +330,7 @@ The fido_assert_rp_id(), fido_dev_largeblob_get(3) - - + +
April 27, 2022Linux 5.17.4-200.fc35.x86_64June 19, 2023Debian
diff --git a/content/projects/libfido2/Manuals/fido_assert_set_authdata.partial b/content/projects/libfido2/Manuals/fido_assert_set_authdata.partial index 3d784ae44..5876b7b15 100644 --- a/content/projects/libfido2/Manuals/fido_assert_set_authdata.partial +++ b/content/projects/libfido2/Manuals/fido_assert_set_authdata.partial @@ -32,7 +32,8 @@ fido_assert_set_up, fido_assert_set_uv, fido_assert_set_rp, - fido_assert_set_sig — + fido_assert_set_sig, + fido_assert_set_winhello_appid —
set parameters of a FIDO2 assertion

#include @@ -130,6 +131,12 @@ typedef enum { idx, const unsigned char *ptr, size_t len); +
+int +
+fido_assert_set_winhello_appid(fido_assert_t + *assert, const + char *id);

The fido_assert_set_authdata set of functions define the various parameters of a FIDO2 assertion, allowing a @@ -218,6 +225,33 @@ The fido_assert_set_up() and FIDO_OPT_OMIT by default, allowing the authenticator to use its default settings.
+The fido_assert_set_winhello_appid() function + sets the U2F application id (“U2F + AppID”) of assert, where + id is a NUL-terminated UTF-8 string. The + content of id is copied, and no references to + the passed pointer are kept. The + fido_assert_set_winhello_appid() function + is a no-op unless assert is passed to + fido_dev_get_assert(3) + with a device dev on which + fido_dev_is_winhello(3) + holds true. In this case, libfido2 will instruct + Windows Hello to try the assertion twice, first with the + id passed to + fido_assert_set_rp(), and a second time + with the id passed to + fido_assert_set_winhello_appid(). If the + second assertion succeeds, + fido_assert_rp_id(3) + will point to the U2F AppID once + fido_dev_get_assert(3) + completes. This mechanism exists in Windows Hello to ensure U2F backwards + compatibility without the application inadvertently prompting the user twice. + Note that fido_assert_set_winhello_appid() + is not needed on platforms offering CTAP primitives, since the authenticator + can be silently probed for the existence of U2F credentials. +
Use of the fido_assert_set_authdata set of functions may happen in two distinct situations: when asking a FIDO2 device to produce a series of assertion statements, prior to @@ -244,10 +278,11 @@ The fido_assert_set_authdata functions return ALSO fido_assert_allow_cred(3), fido_assert_verify(3), - fido_dev_get_assert(3) + fido_dev_get_assert(3), + fido_dev_is_winhello(3) - - + +
April 27, 2022Linux 5.17.4-200.fc35.x86_64April 8, 2023Debian
diff --git a/content/projects/libfido2/Manuals/fido_assert_set_winhello_appid.partial b/content/projects/libfido2/Manuals/fido_assert_set_winhello_appid.partial new file mode 120000 index 000000000..0a24253fc --- /dev/null +++ b/content/projects/libfido2/Manuals/fido_assert_set_winhello_appid.partial @@ -0,0 +1 @@ +fido_assert_set_authdata.partial \ No newline at end of file