New upstream version 1.4.0

10 files changed, 159 insertions, 31 deletions

diff --git a/man/CMakeLists.txt b/man/CMakeLists.txt
index c903ab8..44e4a96 100644
--- a/man/CMakeLists.txt
+++ b/man/CMakeLists.txt
@@ -5,7 +5,7 @@
 find_program(MANDOC_PATH mandoc)
 message(STATUS "MANDOC_PATH: ${MANDOC_PATH}")
 
-if(CMAKE_SYSTEM_NAME STREQUAL "Linux")
+if(CMAKE_SYSTEM_NAME STREQUAL "FreeBSD" OR CMAKE_SYSTEM_NAME STREQUAL "Linux")
         find_program(GZIP_PATH gzip)
         message(STATUS "GZIP_PATH: ${GZIP_PATH}")
 endif()
@@ -101,6 +101,7 @@ list(APPEND MAN_ALIAS
         fido_cbor_info_new fido_cbor_info_extensions_ptr 
         fido_cbor_info_new fido_cbor_info_free 
         fido_cbor_info_new fido_cbor_info_maxmsgsiz
+        fido_cbor_info_new fido_cbor_info_fwversion
         fido_cbor_info_new fido_cbor_info_options_len 
         fido_cbor_info_new fido_cbor_info_options_name_ptr 
         fido_cbor_info_new fido_cbor_info_options_value_ptr 
@@ -117,6 +118,7 @@ list(APPEND MAN_ALIAS
         fido_cred_new fido_cred_free
         fido_cred_new fido_cred_id_len
         fido_cred_new fido_cred_id_ptr
+        fido_cred_new fido_cred_prot
         fido_cred_new fido_cred_pubkey_len
         fido_cred_new fido_cred_pubkey_ptr
         fido_cred_new fido_cred_sig_len
@@ -145,6 +147,7 @@ list(APPEND MAN_ALIAS
         fido_cred_set_authdata fido_cred_set_clientdata_hash
         fido_cred_set_authdata fido_cred_set_extensions
         fido_cred_set_authdata fido_cred_set_fmt
+        fido_cred_set_authdata fido_cred_set_prot
         fido_cred_set_authdata fido_cred_set_rk
         fido_cred_set_authdata fido_cred_set_rp
         fido_cred_set_authdata fido_cred_set_sig
@@ -261,17 +264,17 @@ if(MANDOC_PATH)
         add_dependencies(man man_symlink_html)
         add_dependencies(man_gzip man_lint)
         install(FILES ${CMAKE_SOURCE_DIR}/man/style.css
-                DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/libfido2)
+                DESTINATION "${CMAKE_INSTALL_DOCDIR}/html")
         foreach(f ${MAN_SOURCES})
                 string(REGEX REPLACE ".[13]" "" f ${f})
                 install(FILES ${CMAKE_BINARY_DIR}/man/${f}.html
-                        DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/libfido2)
+                        DESTINATION "${CMAKE_INSTALL_DOCDIR}/html")
         endforeach()
         foreach(i RANGE 0 ${MAN_ALIAS_MAX} 2)
                 math(EXPR j "${i} + 1")
                 list(GET MAN_ALIAS ${j} DST)
                 install(FILES ${CMAKE_BINARY_DIR}/man/${DST}.html
-                        DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/libfido2)
+                        DESTINATION "${CMAKE_INSTALL_DOCDIR}/html")
         endforeach()
 endif()
 
@@ -282,33 +285,33 @@ if(GZIP_PATH)
         foreach(f ${MAN_SOURCES})
                 if (${f} MATCHES ".1$")
                         install(FILES ${CMAKE_BINARY_DIR}/man/${f}.gz
-                                DESTINATION "${CMAKE_INSTALL_PREFIX}/share/man/man1")
+                                DESTINATION "${CMAKE_INSTALL_MANDIR}/man1")
                 elseif(${f} MATCHES ".3$")
                         install(FILES ${CMAKE_BINARY_DIR}/man/${f}.gz
-                                DESTINATION "${CMAKE_INSTALL_PREFIX}/share/man/man3")
+                                DESTINATION "${CMAKE_INSTALL_MANDIR}/man3")
                 endif()
         endforeach()
         foreach(i RANGE 0 ${MAN_ALIAS_MAX} 2)
                 math(EXPR j "${i} + 1")
                 list(GET MAN_ALIAS ${j} DST)
                 install(FILES ${CMAKE_BINARY_DIR}/man/${DST}.3.gz
-                        DESTINATION ${CMAKE_INSTALL_PREFIX}/share/man/man3)
+                        DESTINATION "${CMAKE_INSTALL_MANDIR}/man3")
         endforeach()
 elseif(NOT MSVC)
         add_dependencies(man man_symlink)
         foreach(f ${MAN_SOURCES})
                 if (${f} MATCHES ".1$")
                         install(FILES ${CMAKE_BINARY_DIR}/man/${f}
-                                DESTINATION "${CMAKE_INSTALL_PREFIX}/man/man1")
+                                DESTINATION "${CMAKE_INSTALL_MANDIR}/man1")
                 elseif(${f} MATCHES ".3$")
                         install(FILES ${CMAKE_BINARY_DIR}/man/${f}
-                                DESTINATION "${CMAKE_INSTALL_PREFIX}/man/man3")
+                                DESTINATION "${CMAKE_INSTALL_MANDIR}/man3")
                 endif()
         endforeach()
         foreach(i RANGE 0 ${MAN_ALIAS_MAX} 2)
                 math(EXPR j "${i} + 1")
                 list(GET MAN_ALIAS ${j} DST)
                 install(FILES ${CMAKE_BINARY_DIR}/man/${DST}.3
-                        DESTINATION ${CMAKE_INSTALL_PREFIX}/man/man3)
+                        DESTINATION "${CMAKE_INSTALL_MANDIR}/man3")
         endforeach()
 endif()
diff --git a/man/es256_pk_new.3 b/man/es256_pk_new.3
index 48eda0b..54439cd 100644
--- a/man/es256_pk_new.3
+++ b/man/es256_pk_new.3
@@ -89,6 +89,10 @@ where
 points to
 .Fa len
 bytes.
+The
+.Fa ptr
+pointer may point to an uncompressed point, or to the
+concatenation of the x and y coordinates.
 No references to
 .Fa ptr
 are kept.
diff --git a/man/fido2-token.1 b/man/fido2-token.1
index d5a5734..b59463a 100644
--- a/man/fido2-token.1
+++ b/man/fido2-token.1
@@ -156,3 +156,5 @@ authenticator.
 Yubico authenticators do not allow resets after 5 seconds from
 power-up, and expect a reset to be confirmed by the user through
 touch within 30 seconds.
+.Pp
+An authenticator's path may contain spaces.
diff --git a/man/fido_bio_dev_get_info.3 b/man/fido_bio_dev_get_info.3
index bde1396..d18c9ec 100644
--- a/man/fido_bio_dev_get_info.3
+++ b/man/fido_bio_dev_get_info.3
@@ -35,6 +35,8 @@
 The functions described in this page allow biometric
 templates on a FIDO2 authenticator to be listed, created,
 removed, and customised.
+Please note that not all FIDO2 authenticators support biometric
+enrollment.
 For a description of the types involved, please refer to
 .Xr fido_bio_info_new 3 ,
 .Xr fido_bio_enroll_new 3 ,
@@ -118,3 +120,11 @@ is returned.
 .Xr fido_bio_enroll_new 3 ,
 .Xr fido_bio_info_new 3 ,
 .Xr fido_bio_template 3
+.Sh CAVEATS
+Biometric enrollment is a tentative feature of FIDO 2.1.
+Applications willing to strictly abide by FIDO 2.0 should refrain
+from using biometric enrollment.
+Applications using biometric enrollment should ensure it is
+supported by the authenticator prior to using the API.
+Since FIDO 2.1 hasn't been finalised, there is a chance the
+functionality and associated data structures may change.
diff --git a/man/fido_bio_template.3 b/man/fido_bio_template.3
index 6140926..8414937 100644
--- a/man/fido_bio_template.3
+++ b/man/fido_bio_template.3
@@ -38,11 +38,11 @@
 .Ft fido_bio_template_array_t *
 .Fn fido_bio_template_array_new "void"
 .Ft void
-.Fn fido_bio_template_array_free "fido_bio_template_array_t **template_array_p"
+.Fn fido_bio_template_array_free "fido_bio_template_array_t **array_p"
 .Ft size_t
-.Fn fido_bio_template_array_count "const fido_bio_template_array_t *template_array"
+.Fn fido_bio_template_array_count "const fido_bio_template_array_t *array"
 .Ft const fido_bio_template_t *
-.Fn fido_bio_template "const fido_bio_template_array_t *template_array" "size_t idx"
+.Fn fido_bio_template "const fido_bio_template_array_t *array" "size_t idx"
 .Sh DESCRIPTION
 Existing FIDO 2 biometric enrollments are abstracted in
 .Em libfido2
@@ -132,18 +132,18 @@ If memory cannot be allocated, NULL is returned.
 The
 .Fn fido_bio_template_array_free
 function releases the memory backing
-.Fa *template_array_p ,
+.Fa *array_p ,
 where
-.Fa *template_array_p
+.Fa *array_p
 must have been previously allocated by
 .Fn fido_bio_template_array_new .
 On return,
-.Fa *template_array_p
+.Fa *array_p
 is set to NULL.
 Either
-.Fa template_array_p
+.Fa array_p
 or
-.Fa *template_array_p
+.Fa *array_p
 may be NULL, in which case
 .Fn fido_bio_template_array_free
 is a NOP.
@@ -151,16 +151,16 @@ is a NOP.
 The
 .Fn fido_bio_template_array_count
 function returns the number of templates in
-.Fa template_array .
+.Fa array .
 .Pp
 The
 .Fn fido_bio_template
 function returns a pointer to the template at index
 .Fa idx
 in
-.Fa template_array .
+.Fa array .
 Please note that the first template in
-.Fa template_array
+.Fa array
 has an
 .Fa idx
 (index) value of 0.
diff --git a/man/fido_cbor_info_new.3 b/man/fido_cbor_info_new.3
index d1e4c41..3e7de1f 100644
--- a/man/fido_cbor_info_new.3
+++ b/man/fido_cbor_info_new.3
@@ -20,7 +20,8 @@
 .Nm fido_cbor_info_protocols_len ,
 .Nm fido_cbor_info_versions_len ,
 .Nm fido_cbor_info_options_len ,
-.Nm fido_cbor_info_maxmsgsiz
+.Nm fido_cbor_info_maxmsgsiz ,
+.Nm fido_cbor_info_fwversion
 .Nd FIDO 2 CBOR Info API
 .Sh SYNOPSIS
 .In fido.h
@@ -54,6 +55,8 @@
 .Fn fido_cbor_info_options_len "const fido_cbor_info_t *ci"
 .Ft uint64_t
 .Fn fido_cbor_info_maxmsgsiz "const fido_cbor_info_t *ci"
+.Ft uint64_t
+.Fn fido_cbor_info_fwversion "const fido_cbor_info_t *ci"
 .Sh DESCRIPTION
 The
 .Fn fido_cbor_info_new
@@ -124,7 +127,12 @@ The length of the options array is returned by
 .Pp
 The
 .Fn fido_cbor_info_maxmsgsiz
-function returns the maximum message size of
+function returns the maximum message size attribute of
+.Fa ci .
+.Pp
+The
+.Fn fido_cbor_info_fwversion
+function returns the firmware version attribute of
 .Fa ci .
 .Pp
 A complete example of how to use these functions can be found in the
diff --git a/man/fido_cred_new.3 b/man/fido_cred_new.3
index 47eeba8..22af60c 100644
--- a/man/fido_cred_new.3
+++ b/man/fido_cred_new.3
@@ -8,6 +8,7 @@
 .Sh NAME
 .Nm fido_cred_new ,
 .Nm fido_cred_free ,
+.Nm fido_cred_prot ,
 .Nm fido_cred_fmt ,
 .Nm fido_cred_authdata_ptr ,
 .Nm fido_cred_clientdata_hash_ptr ,
@@ -28,6 +29,8 @@
 .Fn fido_cred_new "void"
 .Ft void
 .Fn fido_cred_free "fido_cred_t **cred_p"
+.Ft int
+.Fn fido_cred_prot "fido_cred_t *cred"
 .Ft const char *
 .Fn fido_cred_fmt "const fido_cred_t *cred"
 .Ft const unsigned char *
@@ -99,6 +102,15 @@ may be NULL, in which case
 is a NOP.
 .Pp
 The
+.Fn fido_cred_prot
+function returns the protection of
+.Fa cred .
+See
+.Xr fido_cred_set_prot 3
+for the values understood by
+.Em libfido2 .
+.Pp
+The
 .Fn fido_cred_fmt
 function returns a pointer to a NUL-terminated string containing
 the format of
diff --git a/man/fido_cred_set_authdata.3 b/man/fido_cred_set_authdata.3
index 8b087fa..d28c61e 100644
--- a/man/fido_cred_set_authdata.3
+++ b/man/fido_cred_set_authdata.3
@@ -14,6 +14,7 @@
 .Nm fido_cred_set_rp ,
 .Nm fido_cred_set_user ,
 .Nm fido_cred_set_extensions ,
+.Nm fido_cred_set_prot ,
 .Nm fido_cred_set_rk ,
 .Nm fido_cred_set_uv ,
 .Nm fido_cred_set_fmt ,
@@ -45,6 +46,8 @@ typedef enum {
 .Ft int
 .Fn fido_cred_set_extensions "fido_cred_t *cred" "int flags"
 .Ft int
+.Fn fido_cred_set_prot "fido_cred_t *cred" "int prot"
+.Ft int
 .Fn fido_cred_set_rk "fido_cred_t *cred" "fido_opt_t rk"
 .Ft int
 .Fn fido_cred_set_uv "fido_cred_t *cred" "fido_opt_t uv"
@@ -149,7 +152,9 @@ to the bitmask
 .Fa flags .
 At the moment, only the
 .Dv FIDO_EXT_HMAC_SECRET
-extension is supported.
+and
+.Dv FIDO_EXT_CRED_PROTECT
+extensions are supported.
 If
 .Fa flags
 is zero, the extensions of
@@ -157,6 +162,24 @@ is zero, the extensions of
 are cleared.
 .Pp
 The
+.Fn fido_cred_set_prot
+function sets the protection of
+.Fa cred
+to the scalar
+.Fa prot .
+At the moment, only the
+.Dv FIDO_CRED_PROT_UV_OPTIONAL ,
+.Dv FIDO_CRED_PROT_UV_OPTIONAL_WITH_ID ,
+and
+.Dv FIDO_CRED_PROT_UV_REQUIRED
+protections are supported.
+If
+.Fa prot
+is zero, the protection of
+.Fa cred
+is cleared.
+.Pp
+The
 .Fn fido_cred_set_rk
 and
 .Fn fido_cred_set_uv
diff --git a/man/fido_credman_metadata_new.3 b/man/fido_credman_metadata_new.3
index 16f0192..1a65978 100644
--- a/man/fido_credman_metadata_new.3
+++ b/man/fido_credman_metadata_new.3
@@ -72,7 +72,8 @@ The credential management API of
 .Em libfido2
 allows resident credentials on a FIDO2 authenticator to be listed,
 inspected, and removed.
-Please note that not all authenticators support credential management.
+Please note that not all FIDO2 authenticators support credential
+management.
 To obtain information on what an authenticator supports, please
 refer to
 .Xr fido_cbor_info_new 3 .
@@ -297,3 +298,11 @@ should have their return values checked for NULL.
 .Sh SEE ALSO
 .Xr fido_cbor_info_new 3 ,
 .Xr fido_cred_new 3
+.Sh CAVEATS
+Credential management is a tentative feature of FIDO 2.1.
+Applications willing to strictly abide by FIDO 2.0 should refrain
+from using credential management.
+Applications using credential management should ensure it is
+supported by the authenticator prior to using the API.
+Since FIDO 2.1 hasn't been finalised, there is a chance the
+functionality and associated data structures may change.
diff --git a/man/fido_dev_set_io_functions.3 b/man/fido_dev_set_io_functions.3
index adc4a9e..67bc6d0 100644
--- a/man/fido_dev_set_io_functions.3
+++ b/man/fido_dev_set_io_functions.3
@@ -15,12 +15,16 @@ typedef void *fido_dev_io_open_t(const char *);
 typedef void  fido_dev_io_close_t(void *);
 typedef int   fido_dev_io_read_t(void *, unsigned char *, size_t, int);
 typedef int   fido_dev_io_write_t(void *, const unsigned char *, size_t);
+typedef int   fido_dev_io_rx_t(struct fido_dev *, uint8_t, unsigned char *, size_t, int);
+typedef int   fido_dev_io_tx_t(struct fido_dev *, uint8_t, const unsigned char *, size_t);
 
 typedef struct fido_dev_io {
         fido_dev_io_open_t  *open;
         fido_dev_io_close_t *close;
         fido_dev_io_read_t  *read;
         fido_dev_io_write_t *write;
+        fido_dev_io_rx_t    *rx;
+        fido_dev_io_tx_t    *tx;
 } fido_dev_io_t;
 .Ed
 .Ft int
@@ -28,12 +32,12 @@ typedef struct fido_dev_io {
 .Sh DESCRIPTION
 The
 .Nm
-interface defines the I/O handlers used to talk to
+interface defines the I/O and transmission handlers used to talk to
 .Fa dev .
 Its usage is optional.
 By default,
 .Em libfido2
-will use the operating system's native HID interface to talk to
+will use the operating system's native HID interface to talk CTAP2 to
 a FIDO device.
 .Pp
 A
@@ -51,13 +55,13 @@ It is not expected to be idempotent.
 .Pp
 A
 .Vt fido_dev_io_read_t
-function reads from
+function reads a single HID report from
 .Fa dev .
 The first parameter taken is the opaque handle obtained from
 .Vt fido_dev_io_open_t .
 The read buffer is pointed to by the second parameter, and the
 third parameter holds its size.
-Finally, the last argument passed to
+The last argument passed to
 .Vt fido_dev_io_read_t
 is the number of milliseconds the caller is willing to sleep,
 should the call need to block.
@@ -67,9 +71,9 @@ may block indefinitely.
 The number of bytes read is returned.
 On error, -1 is returned.
 .Pp
-Conversely, a
+A
 .Vt fido_dev_io_write_t
-function writes to
+function writes a single HID report to
 .Fa dev .
 The first parameter taken is the opaque handle returned by
 .Vt fido_dev_io_open_t .
@@ -81,6 +85,59 @@ function may block.
 The number of bytes written is returned.
 On error, -1 is returned.
 .Pp
+A
+.Vt fido_dev_io_rx_t
+function receives a complete CTAP2 message from
+.Fa dev .
+The first parameter taken is a pointer to
+.Fa dev .
+The second parameter holds the expected CTAP2 command byte.
+The read buffer is pointed to by the third parameter, and the
+fourth parameter holds its size.
+The last argument passed to
+.Vt fido_dev_io_rx_t
+is the number of milliseconds the caller is willing to sleep,
+should the call need to block.
+If this value holds -1,
+.Vt fido_dev_io_rx_t
+may block indefinitely.
+The number of bytes read is returned.
+On error, -1 is returned.
+.Pp
+A
+.Vt fido_dev_io_tx_t
+function transmits a complete CTAP2 message to
+.Fa dev .
+The first parameter taken is a pointer to
+.Fa dev .
+The second parameter holds the CTAP2 command byte.
+The write buffer is pointed to by the third parameter, and the
+fourth parameter holds its size.
+A
+.Vt fido_dev_io_tx_t
+function may block.
+On success, 0 is returned.
+On error, -1 is returned.
+.Pp
+When calling
+.Fn fido_dev_set_io_functions ,
+the
+.Fa open ,
+.Fa close ,
+.Fa read
+and
+.Fa write
+fields of
+.Fa io
+may not be NULL.
+Either
+.Fa rx
+or
+.Fa tx
+may be NULL, in which case
+.Em libfido2
+uses its corresponding CTAP2 HID transport method.
+.Pp
 No references to
 .Fa io
 are held by