From 75073d0a8478441cc97a6efa10b566c5fb1dac81 Mon Sep 17 00:00:00 2001 From: Colin Watson Date: Fri, 17 Apr 2020 20:57:17 +0100 Subject: New upstream version 1.4.0 --- man/CMakeLists.txt | 23 ++++++++------ man/es256_pk_new.3 | 4 +++ man/fido2-token.1 | 2 ++ man/fido_bio_dev_get_info.3 | 10 ++++++ man/fido_bio_template.3 | 22 ++++++------- man/fido_cbor_info_new.3 | 12 +++++-- man/fido_cred_new.3 | 12 +++++++ man/fido_cred_set_authdata.3 | 25 ++++++++++++++- man/fido_credman_metadata_new.3 | 11 ++++++- man/fido_dev_set_io_functions.3 | 69 +++++++++++++++++++++++++++++++++++++---- 10 files changed, 159 insertions(+), 31 deletions(-) (limited to 'man') 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 -- cgit v1.2.3