1 files changed, 98 insertions, 0 deletions
diff --git a/examples/README.adoc b/examples/README.adoc
new file mode 100644
index 000000000000..bcecb22f5258
--- /dev/null
+++ b/examples/README.adoc
@@ -0,0 +1,98 @@
+= 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 NIST P-256 public key in
+	PEM format.
+
+- <blobkey>
+
+	A credential's associated FIDO 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 ecdsa|rsa|eddsa] [-k pubkey] [-ei cred_id] [-P pin] [-T seconds]
+       [-b blobkey] [-hruv] <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>.
+
+- assert [-t ecdsa|rsa|eddsa] [-a cred_id] [-h hmac_secret] [-s hmac_salt]
+	 [-P pin] [-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.  User verification may be requested through the -v
+	option. 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.