Adding upstream version 1.14.0.upstream/1.14.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 100 insertions, 0 deletions

diff --git a/examples/README.adoc b/examples/README.adoc
new file mode 100644
index 0000000..6151b70
--- /dev/null
+++ b/examples/README.adoc
@@ -0,0 +1,100 @@
+= Examples
+
+=== Definitions
+
+The following definitions are used in the description below:
+
+- <device>
+
+	The file system path or subsystem-specific identification string of a
+	FIDO device.
+
+- <pin>, [oldpin]
+
+	Strings passed directly in the executed command's argument vector.
+
+- <cred_id>
+
+	The file system path of a file containing a FIDO credential ID in
+	binary representation.
+
+- <pubkey>
+
+	The file system path of a file containing a public key in PEM format.
+
+- <blobkey>
+
+	A credential's associated CTAP 2.1 "largeBlob" symmetric key.
+
+=== Description
+
+The following examples are provided:
+
+- manifest
+
+	Prints a list of configured FIDO devices.
+
+- info <device>
+
+	Prints information about <device>.
+
+- reset <device>
+
+	Performs a factory reset on <device>.
+
+- setpin <pin> [oldpin] <device>
+
+	Configures <pin> as the new PIN of <device>. If [oldpin] is provided,
+	the device's PIN is changed from [oldpin] to <pin>.
+
+- cred [-t es256|es384|rs256|eddsa] [-k pubkey] [-ei cred_id] [-P pin]
+       [-T seconds] [-b blobkey] [-hruv] [-c cred_protect] <device>
+
+	Creates a new credential on <device> and verify that the credential
+	was signed by the authenticator. The device's attestation certificate
+	is not verified. If option -k is specified, the credential's public
+	key is stored in <pubkey>. If option -i is specified, the credential
+	ID is stored in <cred_id>. The -e option may be used to add <cred_id>
+	to the list of excluded credentials. If option -h is specified,
+	the hmac-secret FIDO2 extension is enabled on the generated
+	credential. If option -r is specified, the generated credential
+	will involve a resident key. User verification may be requested
+	through the -v option. If option -u is specified, the credential
+	is generated using U2F (CTAP1) instead of FIDO2 (CTAP2) commands.
+	The -T option may be used to enforce a timeout of <seconds>. If the
+	option -b is specified, the credential's "largeBlob" key is stored in
+	<blobkey>. If the option -c is specified the the generated credential
+	will be bound by the specified protection policy.
+
+- assert [-t es256|es384|rs256|eddsa] [-a cred_id] [-h hmac_secret] [-P pin]
+         [-s hmac_salt] [-T seconds] [-b blobkey] [-puv] <pubkey> <device>
+
+	Asks <device> for a FIDO2 assertion corresponding to [cred_id],
+	which may be omitted for resident keys. The obtained assertion
+	is verified using <pubkey>. The -p option requests that the user
+	be present and checks whether the user presence bit was signed by the
+	authenticator. The -v option requests user verification and checks
+	whether the user verification bit was signed by the authenticator.
+	If option -u is specified, the assertion is generated using
+	U2F (CTAP1) instead of FIDO2 (CTAP2) commands. If option -s is
+	specified, a FIDO2 hmac-secret is requested from the authenticator,
+	and the contents of <hmac_salt> are used as the salt. If option -h
+	is specified, the resulting hmac-secret is stored in <hmac_secret>.
+	The -T option may be used to enforce a timeout of <seconds>. If the
+	option -b specified, the credential's "largeBlob" key is stored in
+	<blobkey>.
+
+- retries <device>
+	Get the number of PIN attempts left on <device> before lockout.
+
+- select
+
+	Enumerates available FIDO devices and, if more than one is present,
+	simultaneously requests touch on all of them, printing information
+	about the device touched.
+
+Debugging is possible through the use of the FIDO_DEBUG environment variable.
+If set, libfido2 will produce a log of its transactions with the authenticator.
+
+Additionally, an example of a WebAuthn client using libfido2 is available at
+https://github.com/martelletto/fido2-webauthn-client.