From c79050aa44b8836d836c5dd22a383a073c28b74b Mon Sep 17 00:00:00 2001 From: nicoo Date: Wed, 12 Feb 2020 13:42:22 +0100 Subject: Import upstream release 1.3.0 Closes: #951184 --- man/CMakeLists.txt | 314 ++++++++++++++++++++++++++++++++++++++++ man/NOTES | 4 + man/dyc.css | 14 ++ man/eddsa_pk_new.3 | 122 ++++++++++++++++ man/es256_pk_new.3 | 122 ++++++++++++++++ man/fido2-assert.1 | 220 ++++++++++++++++++++++++++++ man/fido2-cred.1 | 238 ++++++++++++++++++++++++++++++ man/fido2-token.1 | 158 ++++++++++++++++++++ man/fido_assert_allow_cred.3 | 47 ++++++ man/fido_assert_new.3 | 190 ++++++++++++++++++++++++ man/fido_assert_set_authdata.3 | 194 +++++++++++++++++++++++++ man/fido_assert_verify.3 | 79 ++++++++++ man/fido_bio_dev_get_info.3 | 120 +++++++++++++++ man/fido_bio_enroll_new.3 | 95 ++++++++++++ man/fido_bio_info_new.3 | 81 +++++++++++ man/fido_bio_template.3 | 169 +++++++++++++++++++++ man/fido_cbor_info_new.3 | 153 ++++++++++++++++++++ man/fido_cred_exclude.3 | 60 ++++++++ man/fido_cred_new.3 | 157 ++++++++++++++++++++ man/fido_cred_set_authdata.3 | 240 ++++++++++++++++++++++++++++++ man/fido_cred_verify.3 | 64 ++++++++ man/fido_credman_metadata_new.3 | 299 ++++++++++++++++++++++++++++++++++++++ man/fido_dev_get_assert.3 | 76 ++++++++++ man/fido_dev_info_manifest.3 | 143 ++++++++++++++++++ man/fido_dev_make_cred.3 | 77 ++++++++++ man/fido_dev_open.3 | 159 ++++++++++++++++++++ man/fido_dev_set_io_functions.3 | 95 ++++++++++++ man/fido_dev_set_pin.3 | 88 +++++++++++ man/fido_init.3 | 40 +++++ man/fido_strerr.3 | 27 ++++ man/rs256_pk_new.3 | 122 ++++++++++++++++ man/style.css | 24 +++ 32 files changed, 3991 insertions(+) create mode 100644 man/CMakeLists.txt create mode 100644 man/NOTES create mode 100644 man/dyc.css create mode 100644 man/eddsa_pk_new.3 create mode 100644 man/es256_pk_new.3 create mode 100644 man/fido2-assert.1 create mode 100644 man/fido2-cred.1 create mode 100644 man/fido2-token.1 create mode 100644 man/fido_assert_allow_cred.3 create mode 100644 man/fido_assert_new.3 create mode 100644 man/fido_assert_set_authdata.3 create mode 100644 man/fido_assert_verify.3 create mode 100644 man/fido_bio_dev_get_info.3 create mode 100644 man/fido_bio_enroll_new.3 create mode 100644 man/fido_bio_info_new.3 create mode 100644 man/fido_bio_template.3 create mode 100644 man/fido_cbor_info_new.3 create mode 100644 man/fido_cred_exclude.3 create mode 100644 man/fido_cred_new.3 create mode 100644 man/fido_cred_set_authdata.3 create mode 100644 man/fido_cred_verify.3 create mode 100644 man/fido_credman_metadata_new.3 create mode 100644 man/fido_dev_get_assert.3 create mode 100644 man/fido_dev_info_manifest.3 create mode 100644 man/fido_dev_make_cred.3 create mode 100644 man/fido_dev_open.3 create mode 100644 man/fido_dev_set_io_functions.3 create mode 100644 man/fido_dev_set_pin.3 create mode 100644 man/fido_init.3 create mode 100644 man/fido_strerr.3 create mode 100644 man/rs256_pk_new.3 create mode 100644 man/style.css (limited to 'man') diff --git a/man/CMakeLists.txt b/man/CMakeLists.txt new file mode 100644 index 0000000..c903ab8 --- /dev/null +++ b/man/CMakeLists.txt @@ -0,0 +1,314 @@ +# Copyright (c) 2018 Yubico AB. All rights reserved. +# Use of this source code is governed by a BSD-style +# license that can be found in the LICENSE file. + +find_program(MANDOC_PATH mandoc) +message(STATUS "MANDOC_PATH: ${MANDOC_PATH}") + +if(CMAKE_SYSTEM_NAME STREQUAL "Linux") + find_program(GZIP_PATH gzip) + message(STATUS "GZIP_PATH: ${GZIP_PATH}") +endif() + +list(APPEND MAN_SOURCES + eddsa_pk_new.3 + es256_pk_new.3 + fido2-assert.1 + fido2-cred.1 + fido2-token.1 + fido_init.3 + fido_assert_new.3 + fido_assert_allow_cred.3 + fido_assert_set_authdata.3 + fido_assert_verify.3 + fido_bio_dev_get_info.3 + fido_bio_enroll_new.3 + fido_bio_info_new.3 + fido_bio_template.3 + fido_cbor_info_new.3 + fido_cred_new.3 + fido_cred_exclude.3 + fido_credman_metadata_new.3 + fido_cred_set_authdata.3 + fido_cred_verify.3 + fido_dev_get_assert.3 + fido_dev_info_manifest.3 + fido_dev_make_cred.3 + fido_dev_open.3 + fido_dev_set_io_functions.3 + fido_dev_set_pin.3 + fido_strerr.3 + rs256_pk_new.3 +) + +list(APPEND MAN_ALIAS + eddsa_pk_new eddsa_pk_free + eddsa_pk_new eddsa_pk_from_ptr + eddsa_pk_new eddsa_pk_to_EVP_PKEY + es256_pk_new es256_pk_free + es256_pk_new es256_pk_from_EC_KEY + es256_pk_new es256_pk_from_ptr + es256_pk_new es256_pk_to_EVP_PKEY + fido_assert_new fido_assert_authdata_len + fido_assert_new fido_assert_authdata_ptr + fido_assert_new fido_assert_clientdata_hash_len + fido_assert_new fido_assert_clientdata_hash_ptr + fido_assert_new fido_assert_count + fido_assert_new fido_assert_free + fido_assert_new fido_assert_hmac_secret_len + fido_assert_new fido_assert_hmac_secret_ptr + fido_assert_new fido_assert_sigcount + fido_assert_new fido_assert_sig_len + fido_assert_new fido_assert_sig_ptr + fido_assert_new fido_assert_user_display_name + fido_assert_new fido_assert_user_icon + fido_assert_new fido_assert_user_id_len + fido_assert_new fido_assert_user_id_ptr + fido_assert_new fido_assert_user_name + fido_assert_set_authdata fido_assert_set_clientdata_hash + fido_assert_set_authdata fido_assert_set_count + fido_assert_set_authdata fido_assert_set_extensions + fido_assert_set_authdata fido_assert_set_hmac_salt + fido_assert_set_authdata fido_assert_set_rp + fido_assert_set_authdata fido_assert_set_sig + fido_assert_set_authdata fido_assert_set_up + fido_assert_set_authdata fido_assert_set_uv + fido_bio_dev_get_info fido_bio_dev_enroll_begin + fido_bio_dev_get_info fido_bio_dev_enroll_cancel + fido_bio_dev_get_info fido_bio_dev_enroll_continue + fido_bio_dev_get_info fido_bio_dev_enroll_remove + fido_bio_dev_get_info fido_bio_dev_get_template_array + fido_bio_dev_get_info fido_bio_dev_set_template_name + fido_bio_enroll_new fido_bio_enroll_free + fido_bio_enroll_new fido_bio_enroll_last_status + fido_bio_enroll_new fido_bio_enroll_remaining_samples + fido_bio_info_new fido_bio_info_free + fido_bio_info_new fido_bio_info_max_samples + fido_bio_info_new fido_bio_info_type + fido_bio_template fido_bio_template_array_count + fido_bio_template fido_bio_template_array_free + fido_bio_template fido_bio_template_array_new + fido_bio_template fido_bio_template_free + fido_bio_template fido_bio_template_id_len + fido_bio_template fido_bio_template_id_ptr + fido_bio_template fido_bio_template_name + fido_bio_template fido_bio_template_new + fido_bio_template fido_bio_template_set_id + fido_bio_template fido_bio_template_set_name + fido_cbor_info_new fido_cbor_info_aaguid_len + fido_cbor_info_new fido_cbor_info_aaguid_ptr + fido_cbor_info_new fido_cbor_info_extensions_len + 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_options_len + fido_cbor_info_new fido_cbor_info_options_name_ptr + fido_cbor_info_new fido_cbor_info_options_value_ptr + fido_cbor_info_new fido_cbor_info_protocols_len + fido_cbor_info_new fido_cbor_info_protocols_ptr + fido_cbor_info_new fido_cbor_info_versions_len + fido_cbor_info_new fido_cbor_info_versions_ptr + fido_cbor_info_new fido_dev_get_cbor_info + fido_cred_new fido_cred_authdata_len + fido_cred_new fido_cred_authdata_ptr + fido_cred_new fido_cred_clientdata_hash_len + fido_cred_new fido_cred_clientdata_hash_ptr + fido_cred_new fido_cred_fmt + 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_pubkey_len + fido_cred_new fido_cred_pubkey_ptr + fido_cred_new fido_cred_sig_len + fido_cred_new fido_cred_sig_ptr + fido_cred_new fido_cred_x5c_len + fido_cred_new fido_cred_x5c_ptr + fido_credman_metadata_new fido_credman_del_dev_rk + fido_credman_metadata_new fido_credman_get_dev_metadata + fido_credman_metadata_new fido_credman_get_dev_rk + fido_credman_metadata_new fido_credman_get_dev_rp + fido_credman_metadata_new fido_credman_metadata_free + fido_credman_metadata_new fido_credman_rk + fido_credman_metadata_new fido_credman_rk_count + fido_credman_metadata_new fido_credman_rk_existing + fido_credman_metadata_new fido_credman_rk_free + fido_credman_metadata_new fido_credman_rk_new + fido_credman_metadata_new fido_credman_rk_remaining + fido_credman_metadata_new fido_credman_rp_count + fido_credman_metadata_new fido_credman_rp_free + fido_credman_metadata_new fido_credman_rp_id + fido_credman_metadata_new fido_credman_rp_id_hash_len + fido_credman_metadata_new fido_credman_rp_id_hash_ptr + fido_credman_metadata_new fido_credman_rp_name + fido_credman_metadata_new fido_credman_rp_new + fido_cred_set_authdata fido_cred_set_authdata_raw + 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_rk + fido_cred_set_authdata fido_cred_set_rp + fido_cred_set_authdata fido_cred_set_sig + fido_cred_set_authdata fido_cred_set_type + fido_cred_set_authdata fido_cred_set_user + fido_cred_set_authdata fido_cred_set_uv + fido_cred_set_authdata fido_cred_set_x509 + fido_dev_info_manifest fido_dev_info_free + fido_dev_info_manifest fido_dev_info_manufacturer_string + fido_dev_info_manifest fido_dev_info_new + fido_dev_info_manifest fido_dev_info_path + fido_dev_info_manifest fido_dev_info_product + fido_dev_info_manifest fido_dev_info_product_string + fido_dev_info_manifest fido_dev_info_ptr + fido_dev_info_manifest fido_dev_info_vendor + fido_dev_open fido_dev_build + fido_dev_open fido_dev_cancel + fido_dev_open fido_dev_close + fido_dev_open fido_dev_flags + fido_dev_open fido_dev_force_fido2 + fido_dev_open fido_dev_force_u2f + fido_dev_open fido_dev_free + fido_dev_open fido_dev_is_fido2 + fido_dev_open fido_dev_major + fido_dev_open fido_dev_minor + fido_dev_open fido_dev_new + fido_dev_open fido_dev_protocol + fido_dev_set_pin fido_dev_get_retry_count + fido_dev_set_pin fido_dev_reset + rs256_pk_new rs256_pk_free + rs256_pk_new rs256_pk_from_ptr + rs256_pk_new rs256_pk_from_RSA + rs256_pk_new rs256_pk_to_EVP_PKEY +) + +list(LENGTH MAN_ALIAS MAN_ALIAS_LEN) +math(EXPR MAN_ALIAS_MAX "${MAN_ALIAS_LEN} - 2") + +# man_copy +foreach(f ${MAN_SOURCES}) + add_custom_command(OUTPUT ${f} + COMMAND cp -f ${CMAKE_SOURCE_DIR}/man/${f} . + DEPENDS ${f}) + list(APPEND COPY_FILES ${f}) +endforeach() + +# man_lint +foreach(f ${MAN_SOURCES}) + add_custom_command(OUTPUT ${f}.lint + COMMAND mandoc -T lint -W warning ${f} > ${f}.lint + DEPENDS ${f}) + list(APPEND LINT_FILES ${f}.lint) +endforeach() + +# man_html +foreach(f ${MAN_SOURCES}) + string(REGEX REPLACE ".[13]" "" g ${f}) + add_custom_command(OUTPUT ${g}.html + COMMAND mandoc -T html -O man="%N.html",style=style.css -I os="Yubico AB" ${f} > ${g}.html + DEPENDS ${f}) + list(APPEND HTML_FILES ${g}.html) +endforeach() + +# man_html_partial +foreach(f ${MAN_SOURCES}) + string(REGEX REPLACE ".[13]" "" g ${f}) + add_custom_command(OUTPUT ${g}.partial + COMMAND cat ${CMAKE_SOURCE_DIR}/man/dyc.css > ${g}.partial + COMMAND mandoc -T html -O man="%N.html",fragment ${f} >> ${g}.partial + DEPENDS ${f}) + list(APPEND HTML_PARTIAL_FILES ${g}.partial) +endforeach() + +# man_gzip +foreach(f ${MAN_SOURCES}) + add_custom_command(OUTPUT ${f}.gz + COMMAND gzip -c ${f} > ${f}.gz + DEPENDS ${f}) + list(APPEND GZ_FILES ${f}.gz) +endforeach() + +macro(define_symlink_target NAME EXT) + foreach(i RANGE 0 ${MAN_ALIAS_MAX} 2) + math(EXPR j "${i} + 1") + list(GET MAN_ALIAS ${i} SRC) + list(GET MAN_ALIAS ${j} DST) + add_custom_command(OUTPUT ${DST}.${EXT} + COMMAND ln -sf ${SRC}.${EXT} ${DST}.${EXT}) + list(APPEND ${NAME}_LINK_FILES ${DST}.${EXT}) + endforeach() + add_custom_target(${NAME} DEPENDS ${${NAME}_LINK_FILES}) +endmacro() + +add_custom_target(man_copy DEPENDS ${COPY_FILES}) +add_custom_target(man_lint DEPENDS ${LINT_FILES}) +add_custom_target(man_html DEPENDS ${HTML_FILES}) +add_custom_target(man_html_partial DEPENDS ${HTML_PARTIAL_FILES}) +add_custom_target(man_gzip DEPENDS ${GZ_FILES}) + +define_symlink_target(man_symlink 3) +define_symlink_target(man_symlink_html html) +define_symlink_target(man_symlink_html_partial partial) +define_symlink_target(man_symlink_gzip 3.gz) + +add_dependencies(man_symlink man_copy) +add_dependencies(man_lint man_symlink) +add_dependencies(man_html man_lint) +add_dependencies(man_symlink_html man_html) +add_dependencies(man_html_partial man_lint) +add_dependencies(man_symlink_html_partial man_html_partial) +add_custom_target(man ALL) + +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) + 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) + 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) + endforeach() +endif() + +if(GZIP_PATH) + add_dependencies(man_gzip man_copy) + add_dependencies(man_symlink_gzip man_gzip) + add_dependencies(man man_symlink_gzip) + foreach(f ${MAN_SOURCES}) + if (${f} MATCHES ".1$") + install(FILES ${CMAKE_BINARY_DIR}/man/${f}.gz + DESTINATION "${CMAKE_INSTALL_PREFIX}/share/man/man1") + elseif(${f} MATCHES ".3$") + install(FILES ${CMAKE_BINARY_DIR}/man/${f}.gz + DESTINATION "${CMAKE_INSTALL_PREFIX}/share/man/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) + 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") + elseif(${f} MATCHES ".3$") + install(FILES ${CMAKE_BINARY_DIR}/man/${f} + DESTINATION "${CMAKE_INSTALL_PREFIX}/man/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) + endforeach() +endif() diff --git a/man/NOTES b/man/NOTES new file mode 100644 index 0000000..4a461ff --- /dev/null +++ b/man/NOTES @@ -0,0 +1,4 @@ +To generate .partial files for https://developers.yubico.com/: + +$ make -C build man_symlink_html_partial +$ (cd build/man && pax -p p -r -w *.partial /tmp/partial) diff --git a/man/dyc.css b/man/dyc.css new file mode 100644 index 0000000..1ff5b59 --- /dev/null +++ b/man/dyc.css @@ -0,0 +1,14 @@ + diff --git a/man/eddsa_pk_new.3 b/man/eddsa_pk_new.3 new file mode 100644 index 0000000..65bf9a9 --- /dev/null +++ b/man/eddsa_pk_new.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 15 2019 $ +.Dt EDDSA_PK_NEW 3 +.Os +.Sh NAME +.Nm eddsa_pk_new , +.Nm eddsa_pk_free , +.Nm eddsa_pk_from_EVP_PKEY , +.Nm eddsa_pk_from_ptr , +.Nm eddsa_pk_to_EVP_PKEY +.Nd FIDO 2 COSE EDDSA API +.Sh SYNOPSIS +.In openssl/evp.h +.In fido/eddsa.h +.Ft eddsa_pk_t * +.Fn eddsa_pk_new "void" +.Ft void +.Fn eddsa_pk_free "eddsa_pk_t **pkp" +.Ft int +.Fn eddsa_pk_from_EVP_PKEY "eddsa_pk_t *pk" "const EVP_PKEY *pkey" +.Ft int +.Fn eddsa_pk_from_ptr "eddsa_pk_t *pk" "const void *ptr" "size_t len" +.Ft EVP_PKEY * +.Fn eddsa_pk_to_EVP_PKEY "const eddsa_pk_t *pk" +.Sh DESCRIPTION +EDDSA is the name given in the CBOR Object Signing and Encryption +(COSE) RFC to EDDSA over Curve25519 with SHA-512. +The COSE EDDSA API of +.Em libfido2 +is an auxiliary API with routines to convert between the different +EDDSA public key types used in +.Em libfido2 +and +.Em OpenSSL . +.Pp +In +.Em libfido2 , +EDDSA public keys are abstracted by the +.Vt eddsa_pk_t +type. +.Pp +The +.Fn eddsa_pk_new +function returns a pointer to a newly allocated, empty +.Vt eddsa_pk_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn eddsa_pk_free +function releases the memory backing +.Fa *pkp , +where +.Fa *pkp +must have been previously allocated by +.Fn eddsa_pk_new . +On return, +.Fa *pkp +is set to NULL. +Either +.Fa pkp +or +.Fa *pkp +may be NULL, in which case +.Fn eddsa_pk_free +is a NOP. +.Pp +The +.Fn eddsa_pk_from_EVP_PKEY +function fills +.Fa pk +with the contents of +.Fa pkey . +No references to +.Fa pkey +are kept. +.Pp +The +.Fn eddsa_pk_from_ptr +function fills +.Fa pk +with the contents of +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +No references to +.Fa ptr +are kept. +.Pp +The +.Fn eddsa_pk_to_EVP_PKEY +function converts +.Fa pk +to a newly allocated +.Fa EVP_PKEY +type with a reference count of 1. +No internal references to the returned pointer are kept. +If an error occurs, +.Fn eddsa_pk_to_EVP_PKEY +returns NULL. +.Sh RETURN VALUES +The +.Fn eddsa_pk_from_EC_KEY +and +.Fn eddsa_pk_from_ptr +functions return +.Dv FIDO_OK +on success. +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr es256_pk_new 3 , +.Xr fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 , +.Xr rs256_pk_new 3 diff --git a/man/es256_pk_new.3 b/man/es256_pk_new.3 new file mode 100644 index 0000000..48eda0b --- /dev/null +++ b/man/es256_pk_new.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 24 2018 $ +.Dt ES256_PK_NEW 3 +.Os +.Sh NAME +.Nm es256_pk_new , +.Nm es256_pk_free , +.Nm es256_pk_from_EC_KEY , +.Nm es256_pk_from_ptr , +.Nm es256_pk_to_EVP_PKEY +.Nd FIDO 2 COSE ES256 API +.Sh SYNOPSIS +.In openssl/ec.h +.In fido/es256.h +.Ft es256_pk_t * +.Fn es256_pk_new "void" +.Ft void +.Fn es256_pk_free "es256_pk_t **pkp" +.Ft int +.Fn es256_pk_from_EC_KEY "es256_pk_t *pk" "const EC_KEY *ec" +.Ft int +.Fn es256_pk_from_ptr "es256_pk_t *pk" "const void *ptr" "size_t len" +.Ft EVP_PKEY * +.Fn es256_pk_to_EVP_PKEY "const es256_pk_t *pk" +.Sh DESCRIPTION +ES256 is the name given in the CBOR Object Signing and Encryption +(COSE) RFC to ECDSA over P-256 with SHA-256. +The COSE ES256 API of +.Em libfido2 +is an auxiliary API with routines to convert between the different +ECDSA public key types used in +.Em libfido2 +and +.Em OpenSSL . +.Pp +In +.Em libfido2 , +ES256 public keys are abstracted by the +.Vt es256_pk_t +type. +.Pp +The +.Fn es256_pk_new +function returns a pointer to a newly allocated, empty +.Vt es256_pk_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn es256_pk_free +function releases the memory backing +.Fa *pkp , +where +.Fa *pkp +must have been previously allocated by +.Fn es256_pk_new . +On return, +.Fa *pkp +is set to NULL. +Either +.Fa pkp +or +.Fa *pkp +may be NULL, in which case +.Fn es256_pk_free +is a NOP. +.Pp +The +.Fn es256_pk_from_EC_KEY +function fills +.Fa pk +with the contents of +.Fa ec . +No references to +.Fa ec +are kept. +.Pp +The +.Fn es256_pk_from_ptr +function fills +.Fa pk +with the contents of +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +No references to +.Fa ptr +are kept. +.Pp +The +.Fn es256_pk_to_EVP_PKEY +function converts +.Fa pk +to a newly allocated +.Fa EVP_PKEY +type with a reference count of 1. +No internal references to the returned pointer are kept. +If an error occurs, +.Fn es256_pk_to_EVP_PKEY +returns NULL. +.Sh RETURN VALUES +The +.Fn es256_pk_from_EC_KEY +and +.Fn es256_pk_from_ptr +functions return +.Dv FIDO_OK +on success. +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr eddsa_pk_new 3 , +.Xr fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 , +.Xr rs256_pk_new 3 diff --git a/man/fido2-assert.1 b/man/fido2-assert.1 new file mode 100644 index 0000000..67883e2 --- /dev/null +++ b/man/fido2-assert.1 @@ -0,0 +1,220 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: November 5 2019 $ +.Dt FIDO2-ASSERT 1 +.Os +.Sh NAME +.Nm fido2-assert +.Nd get/verify a FIDO 2 assertion +.Sh SYNOPSIS +.Nm +.Fl G +.Op Fl dhpruv +.Op Fl i Ar input_file +.Op Fl o Ar output_file +.Ar device +.Nm +.Fl V +.Op Fl dhpv +.Op Fl i Ar input_file +.Ar key_file +.Op Ar type +.Sh DESCRIPTION +.Nm +gets or verifies a FIDO 2 assertion. +.Pp +The input of +.Nm +is defined by the parameters of the assertion to be obtained/verified. +See the +.Sx INPUT FORMAT +section for details. +.Pp +The output of +.Nm +is defined by the result of the selected operation. +See the +.Sx OUTPUT FORMAT +section for details. +.Pp +If an assertion is successfully obtained or verified, +.Nm +exits 0. +Otherwise, +.Nm +exits 1. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl G +Tells +.Nm +to obtain a new assertion from +.Ar device . +.It Fl V +Tells +.Nm +to verify an assertion using the PEM-encoded public key in +.Ar key_file +of type +.Ar type , +where +.Ar type +may be +.Em es256 +(denoting ECDSA over NIST P-256 with SHA-256), +.Em rs256 +(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or +.Em eddsa +(denoting EDDSA over Curve25519 with SHA-512). +If +.Ar type +is not specified, +.Em es256 +is assumed. +.It Fl h +If obtaining an assertion, enable the FIDO2 hmac-secret +extension. +If verifying an assertion, check whether the extension data bit was +signed by the authenticator. +.It Fl d +Causes +.Nm +to emit debugging output on +.Em stderr . +.It Fl i Ar input_file +Tells +.Nm +to read the parameters of the assertion from +.Ar input_file +instead of +.Em stdin . +.It Fl o Ar output_file +Tells +.Nm +to write output on +.Ar output_file +instead of +.Em stdout . +.It Fl p +If obtaining an assertion, request user presence. +If verifying an assertion, check whether the user presence bit was +signed by the authenticator. +.It Fl r +Obtain an assertion using a resident credential. +If +.Fl r +is specified, +.Nm +will not expect a credential id in its input, and may output +multiple assertions. +.It Fl u +Obtain an assertion using U2F. +By default, +.Nm +will use FIDO2 if supported by the authenticator, and fallback to +U2F otherwise. +.It Fl v +If obtaining an assertion, prompt the user for a PIN and request +user verification from the authenticator. +If a +.Em tty +is available, +.Nm +will use it to obtain the PIN. +Otherwise, +.Em stdin +is used. +If verifying an assertion, check whether the user verification bit +was signed by the authenticator. +.El +.Sh INPUT FORMAT +The input of +.Nm +consists of base64 blobs and UTF-8 strings separated +by newline characters ('\\n'). +.Pp +When obtaining an assertion, +.Nm +expects its input to consist of: +.Pp +.Bl -enum -offset indent -compact +.It +client data hash (base64 blob); +.It +relying party id (UTF-8 string); +.It +credential id, if credential not resident (base64 blob); +.It +hmac salt, if the FIDO2 hmac-secret extension is enabled +(base64 blob); +.El +.Pp +When verifying an assertion, +.Nm +expects its input to consist of: +.Pp +.Bl -enum -offset indent -compact +.It +client data hash (base64 blob); +.It +relying party id (UTF-8 string); +.It +authenticator data (base64 blob); +.It +assertion signature (base64 blob); +.El +.Pp +UTF-8 strings passed to +.Nm +must not contain embedded newline or NUL characters. +.Sh OUTPUT FORMAT +The output of +.Nm +consists of base64 blobs and UTF-8 strings separated +by newline characters ('\\n'). +.Pp +For each generated assertion, +.Nm +outputs: +.Pp +.Bl -enum -offset indent -compact +.It +client data hash (base64 blob); +.It +relying party id (UTF-8 string); +.It +authenticator data (base64 blob); +.It +assertion signature (base64 blob); +.It +user id, if credential resident (base64 blob); +.It +hmac secret, if the FIDO2 hmac-secret extension is enabled +(base64 blob); +.El +.Pp +When verifying an assertion, +.Nm +produces no output. +.Sh EXAMPLES +Assuming +.Pa cred +contains a +.Em es256 +credential created according to the steps outlined in +.Xr fido2-cred 1 , +obtain an assertion from an authenticator at +.Pa /dev/hidraw5 +and verify it: +.Pp +.Dl $ echo assertion challenge | openssl sha256 -binary | base64 > assert_param +.Dl $ echo relying party >> assert_param +.Dl $ head -1 cred >> assert_param +.Dl $ tail -n +2 cred > pubkey +.Dl $ fido2-assert -G -i assert_param /dev/hidraw5 | fido2-assert -V pubkey es256 +.Sh SEE ALSO +.Xr fido2-cred 1 , +.Xr fido2-token 1 diff --git a/man/fido2-cred.1 b/man/fido2-cred.1 new file mode 100644 index 0000000..d9bf7d2 --- /dev/null +++ b/man/fido2-cred.1 @@ -0,0 +1,238 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: November 5 2019 $ +.Dt FIDO2-CRED 1 +.Os +.Sh NAME +.Nm fido2-cred +.Nd make/verify a FIDO 2 credential +.Sh SYNOPSIS +.Nm +.Fl M +.Op Fl dhqruv +.Op Fl i Ar input_file +.Op Fl o Ar output_file +.Ar device +.Op Ar type +.Nm +.Fl V +.Op Fl dhv +.Op Fl i Ar input_file +.Op Fl o Ar output_file +.Op Ar type +.Sh DESCRIPTION +.Nm +makes or verifies a FIDO 2 credential. +.Pp +A credential +.Ar type +may be +.Em es256 +(denoting ECDSA over NIST P-256 with SHA-256), +.Em rs256 +(denoting 2048-bit RSA with PKCS#1.5 padding and SHA-256), or +.Em eddsa +(denoting EDDSA over Curve25519 with SHA-512). +If +.Ar type +is not specified, +.Em es256 +is assumed. +.Pp +When making a credential, the authenticator may require the user +to authenticate with a PIN. +If the +.Fl q +option is not specified, +.Nm +will prompt the user for the PIN. +If a +.Em tty +is available, +.Nm +will use it to obtain the PIN. +Otherwise, +.Em stdin +is used. +.Pp +The input of +.Nm +is defined by the parameters of the credential to be made/verified. +See the +.Sx INPUT FORMAT +section for details. +.Pp +The output of +.Nm +is defined by the result of the selected operation. +See the +.Sx OUTPUT FORMAT +section for details. +.Pp +If a credential is successfully created or verified, +.Nm +exits 0. +Otherwise, +.Nm +exits 1. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl M +Tells +.Nm +to make a new credential on +.Ar device . +.It Fl V +Tells +.Nm +to verify a credential. +.It Fl d +Causes +.Nm +to emit debugging output on +.Em stderr . +.It Fl h +If making a credential, enable the FIDO2 hmac-secret extension. +If verifying a credential, check whether the extension data bit was +signed by the authenticator. +.It Fl i Ar input_file +Tells +.Nm +to read the parameters of the credential from +.Ar input_file +instead of +.Em stdin . +.It Fl o Ar output_file +Tells +.Nm +to write output on +.Ar output_file +instead of +.Em stdout . +.It Fl q +Tells +.Nm +to be quiet. +If a PIN is required and +.Fl q +is specified, +.Nm +will fail. +.It Fl r +Create a resident credential. +.It Fl u +Create a U2F credential. +By default, +.Nm +will use FIDO2 if supported by the authenticator, and fallback to +U2F otherwise. +.It Fl v +If making a credential, request user verification. +If verifying a credential, check whether the user verification bit +was signed by the authenticator. +.El +.Sh INPUT FORMAT +The input of +.Nm +consists of base64 blobs and UTF-8 strings separated +by newline characters ('\\n'). +.Pp +When making a credential, +.Nm +expects its input to consist of: +.Pp +.Bl -enum -offset indent -compact +.It +client data hash (base64 blob); +.It +relying party id (UTF-8 string); +.It +user name (UTF-8 string); +.It +user id (base64 blob). +.El +.Pp +When verifying a credential, +.Nm +expects its input to consist of: +.Pp +.Bl -enum -offset indent -compact +.It +client data hash (base64 blob); +.It +relying party id (UTF-8 string); +.It +credential format (UTF-8 string); +.It +authenticator data (base64 blob); +.It +credential id (base64 blob); +.It +attestation signature (base64 blob); +.It +attestation certificate (optional, base64 blob). +.El +.Pp +UTF-8 strings passed to +.Nm +must not contain embedded newline or NUL characters. +.Sh OUTPUT FORMAT +The output of +.Nm +consists of base64 blobs, UTF-8 strings, and PEM-encoded public +keys separated by newline characters ('\\n'). +.Pp +Upon the successful generation of a credential, +.Nm +outputs: +.Pp +.Bl -enum -offset indent -compact +.It +client data hash (base64 blob); +.It +relying party id (UTF-8 string); +.It +credential format (UTF-8 string); +.It +authenticator data (base64 blob); +.It +credential id (base64 blob); +.It +attestation signature (base64 blob); +.It +attestation certificate, if present (base64 blob). +.El +.Pp +Upon the successful verification of a credential, +.Nm +outputs: +.Pp +.Bl -enum -offset indent -compact +.It +credential id (base64 blob); +.It +PEM-encoded credential key. +.El +.Sh EXAMPLES +Create a new +.Em es256 +credential on +.Pa /dev/hidraw5 , +verify it, and save the id and the public key of the credential in +.Em cred : +.Pp +.Dl $ echo credential challenge | openssl sha256 -binary | base64 > cred_param +.Dl $ echo relying party >> cred_param +.Dl $ echo user name >> cred_param +.Dl $ dd if=/dev/urandom bs=1 count=32 | base64 >> cred_param +.Dl $ fido2-cred -M -i cred_param /dev/hidraw5 | fido2-cred -V -o cred +.Sh SEE ALSO +.Xr fido2-assert 1 , +.Xr fido2-token 1 +.Sh CAVEATS +Please note that +.Nm +handles Basic Attestation and Self Attestation transparently. diff --git a/man/fido2-token.1 b/man/fido2-token.1 new file mode 100644 index 0000000..d5a5734 --- /dev/null +++ b/man/fido2-token.1 @@ -0,0 +1,158 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: September 13 2019 $ +.Dt FIDO2-TOKEN 1 +.Os +.Sh NAME +.Nm fido2-token +.Nd find and manage a FIDO 2 authenticator +.Sh SYNOPSIS +.Nm +.Op Fl CR +.Op Fl d +.Ar device +.Nm +.Fl D +.Op Fl de +.Fl i +.Ar id +.Ar device +.Nm +.Fl I +.Op Fl cd +.Op Fl k Ar rp_id Fl i Ar cred_id +.Ar device +.Nm +.Fl L +.Op Fl der +.Op Fl k Ar rp_id +.Op device +.Nm +.Fl S +.Op Fl de +.Op Fl i Ar template_id Fl n Ar template_name +.Ar device +.Nm +.Fl V +.Sh DESCRIPTION +.Nm +manages a FIDO 2 authenticator. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl C Ar device +Changes the PIN of +.Ar device . +The user will be prompted for the current and new PINs. +.It Fl D Fl i Ar id Ar device +Deletes the resident credential specified by +.Ar id +from +.Ar device , +where +.Ar id +is the credential's base64-encoded id. +The user will be prompted for the PIN. +.It Fl D Fl e Fl i Ar id Ar device +Deletes the biometric enrollment specified by +.Ar id +from +.Ar device , +where +.Ar id +is the enrollment's template base64-encoded id. +The user will be prompted for the PIN. +.It Fl I Ar device +Retrieves information on +.Ar device . +.It Fl I Fl c Ar device +Retrieves resident credential metadata from +.Ar device . +The user will be prompted for the PIN. +.It Fl I Fl k Ar rp_id Fl i Ar cred_id Ar device +Prints the credential id (base64-encoded) and public key +(PEM encoded) of the resident credential specified by +.Ar rp_id +and +.Ar cred_id , +where +.Ar rp_id +is a UTF-8 relying party id, and +.Ar cred_id +is a base64-encoded credential id. +The user will be prompted for the PIN. +.It Fl L +Produces a list of authenticators found by the operating system. +.It Fl L Fl e Ar device +Produces a list of biometric enrollments on +.Ar device . +The user will be prompted for the PIN. +.It Fl L Fl r Ar device +Produces a list of relying parties with resident credentials on +.Ar device . +The user will be prompted for the PIN. +.It Fl L Fl k Ar rp_id Ar device +Produces a list of resident credentials corresponding to +relying party +.Ar rp_id +on +.Ar device . +The user will be prompted for the PIN. +.It Fl R +Performs a reset on +.Ar device . +.Nm +will NOT prompt for confirmation. +.It Fl S +Sets the PIN of +.Ar device . +The user will be prompted for the PIN. +.It Fl S Fl e Ar device +Performs a new biometric enrollment on +.Ar device . +The user will be prompted for the PIN. +.It Fl S Fl e Fl i Ar template_id Fl n Ar template_name Ar device +Sets the friendly name of the biometric enrollment specified by +.Ar template_id +to +.Ar template_name +on +.Ar device , +where +.Ar template_id +is base64-encoded and +.Ar template_name +is a UTF-8 string. +The user will be prompted for the PIN. +.It Fl V +Prints version information. +.It Fl d +Causes +.Nm +to emit debugging output on +.Em stderr . +.El +.Pp +If a +.Em tty +is available, +.Nm +will use it to prompt for PINs. +Otherwise, +.Em stdin +is used. +.Pp +.Nm +exits 0 on success and 1 on error. +.Sh SEE ALSO +.Xr fido2-assert 1 , +.Xr fido2-cred 1 +.Sh CAVEATS +The actual user-flow to perform a reset is outside the scope of the +FIDO2 specification, and may therefore vary depending on the +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. diff --git a/man/fido_assert_allow_cred.3 b/man/fido_assert_allow_cred.3 new file mode 100644 index 0000000..bbe6e4d --- /dev/null +++ b/man/fido_assert_allow_cred.3 @@ -0,0 +1,47 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_ASSERT_ALLOW_CRED 3 +.Os +.Sh NAME +.Nm fido_assert_allow_cred +.Nd appends a credential ID to the list of credentials allowed in an assertion +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_assert_allow_cred "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" +.Sh DESCRIPTION +The +.Fn fido_assert_allow_cred +function adds +.Fa ptr +to the list of credentials allowed in +.Fa assert , +where +.Fa ptr +points to a credential ID of +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +If +.Fn fido_assert_allow_cred +fails, the existing list of allowed credentials is preserved. +.Pp +For the format of a FIDO 2 credential ID, please refer to the +Web Authentication (webauthn) standard. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_assert_allow_cred +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_assert_new 3 , +.Xr fido_assert_set_authdata 3 , +.Xr fido_dev_get_assert 3 diff --git a/man/fido_assert_new.3 b/man/fido_assert_new.3 new file mode 100644 index 0000000..0c2f92f --- /dev/null +++ b/man/fido_assert_new.3 @@ -0,0 +1,190 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: October 22 2019 $ +.Dt FIDO_ASSERT_NEW 3 +.Os +.Sh NAME +.Nm fido_assert_new , +.Nm fido_assert_free , +.Nm fido_assert_count , +.Nm fido_assert_user_display_name , +.Nm fido_assert_user_icon , +.Nm fido_assert_user_name , +.Nm fido_assert_authdata_ptr , +.Nm fido_assert_clientdata_hash_ptr , +.Nm fido_assert_hmac_secret_ptr , +.Nm fido_assert_user_id_ptr , +.Nm fido_assert_sig_ptr , +.Nm fido_assert_authdata_len , +.Nm fido_assert_clientdata_hash_len , +.Nm fido_assert_hmac_secret_len , +.Nm fido_assert_user_id_len , +.Nm fido_assert_sig_len , +.Nm fido_assert_sigcount +.Nd FIDO 2 assertion API +.Sh SYNOPSIS +.In fido.h +.Ft fido_assert_t * +.Fn fido_assert_new "void" +.Ft void +.Fn fido_assert_free "fido_assert_t **assert_p" +.Ft size_t +.Fn fido_assert_count "const fido_assert_t *assert" +.Ft const char * +.Fn fido_assert_user_display_name "const fido_assert_t *assert" "size_t idx" +.Ft const char * +.Fn fido_assert_user_icon "const fido_assert_t *assert" "size_t idx" +.Ft const char * +.Fn fido_assert_user_name "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_authdata_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_clientdata_hash_ptr "const fido_assert_t *assert" +.Ft const unsigned char * +.Fn fido_assert_hmac_secret_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_user_id_ptr "const fido_assert_t *assert" "size_t idx" +.Ft const unsigned char * +.Fn fido_assert_sig_ptr "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_authdata_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_clientdata_hash_len "const fido_assert_t *assert" +.Ft size_t +.Fn fido_assert_hmac_secret_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_user_id_len "const fido_assert_t *assert" "size_t idx" +.Ft size_t +.Fn fido_assert_sig_len "const fido_assert_t *assert" "size_t idx" +.Ft uint32_t +.Fn fido_assert_sigcount "const fido_assert_t *assert" "size_t idx" +.Sh DESCRIPTION +FIDO 2 assertions are abstracted in +.Em libfido2 +by the +.Vt fido_assert_t +type. +The functions described in this page allow a +.Vt fido_assert_t +type to be allocated, deallocated, and inspected. +For other operations on +.Vt fido_assert_t , +please refer to +.Xr fido_assert_set_authdata 3 , +.Xr fido_assert_allow_cred 3 , +.Xr fido_assert_verify 3 , +and +.Xr fido_dev_get_assert 3 . +.Pp +The +.Fn fido_assert_new +function returns a pointer to a newly allocated, empty +.Vt fido_assert_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_assert_free +function releases the memory backing +.Fa *assert_p , +where +.Fa *assert_p +must have been previously allocated by +.Fn fido_assert_new . +On return, +.Fa *assert_p +is set to NULL. +Either +.Fa assert_p +or +.Fa *assert_p +may be NULL, in which case +.Fn fido_assert_free +is a NOP. +.Pp +The +.Fn fido_assert_count +function returns the number of statements in +.Fa assert . +.Pp +The +.Fn fido_assert_user_display_name , +.Fn fido_assert_user_icon , +and +.Fn fido_assert_user_name , +functions return pointers to the user display name, icon, and +name attributes of statement +.Fa idx +in +.Fa assert . +If not NULL, the values returned by these functions point to +NUL-terminated UTF-8 strings. +.Pp +The +.Fn fido_assert_user_id_ptr , +.Fn fido_assert_authdata_ptr , +.Fn fido_assert_hmac_secret_ptr , +and +.Fn fido_assert_sig_ptr +functions return pointers to the user ID, authenticator data, +hmac-secret, and signature attributes of statement +.Fa idx +in +.Fa assert . +The +.Fn fido_assert_user_id_len , +.Fn fido_assert_authdata_len , +.Fn fido_assert_hmac_secret_len , +and +.Fn fido_assert_sig_len +functions can be used to retrieve the corresponding length of a +specific attribute. +.Pp +The +.Fn fido_assert_sigcount +function can be used to obtain the signature counter of statement +.Fa idx +in +.Fa assert . +.Pp +Please note that the first statement in +.Fa assert +has an +.Fa idx +(index) value of 0. +.Pp +The authenticator data and signature parts of an assertion +statement are typically passed to a FIDO 2 server for verification. +.Pp +The +.Fn fido_assert_clientdata_hash_ptr +function returns a pointer to the client data hash of +.Fa assert . +The corresponding length can be obtained by +.Fn fido_assert_clientdata_hash_len . +.Sh RETURN VALUES +The +.Fn fido_assert_user_display_name , +.Fn fido_assert_user_icon , +.Fn fido_assert_user_name , +.Fn fido_assert_authdata_ptr , +.Fn fido_assert_clientdata_hash_ptr , +.Fn fido_assert_user_id_ptr , +and +.Fn fido_assert_sig_ptr +functions return NULL if the respective field in +.Fa assert +is not set. +If not NULL, returned pointers are guaranteed to exist until any API +function that takes +.Fa assert +without the +.Em const +qualifier is invoked. +.Sh SEE ALSO +.Xr fido_assert_allow_cred 3 , +.Xr fido_assert_set_authdata 3 , +.Xr fido_assert_verify 3 , +.Xr fido_dev_get_assert 3 diff --git a/man/fido_assert_set_authdata.3 b/man/fido_assert_set_authdata.3 new file mode 100644 index 0000000..29a86c1 --- /dev/null +++ b/man/fido_assert_set_authdata.3 @@ -0,0 +1,194 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_ASSERT_SET_AUTHDATA 3 +.Os +.Sh NAME +.Nm fido_assert_set_authdata , +.Nm fido_assert_set_authdata_raw , +.Nm fido_assert_set_clientdata_hash , +.Nm fido_assert_set_count , +.Nm fido_assert_set_extensions , +.Nm fido_assert_set_hmac_salt , +.Nm fido_assert_set_up , +.Nm fido_assert_set_uv , +.Nm fido_assert_set_rp , +.Nm fido_assert_set_sig +.Nd set parameters of a FIDO 2 assertion +.Sh SYNOPSIS +.In fido.h +.Bd -literal +typedef enum { + FIDO_OPT_OMIT = 0, /* use authenticator's default */ + FIDO_OPT_FALSE, /* explicitly set option to false */ + FIDO_OPT_TRUE, /* explicitly set option to true */ +} fido_opt_t; +.Ed +.Ft int +.Fn fido_assert_set_authdata "fido_assert_t *assert" " size_t idx" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_authdata_raw "fido_assert_t *assert" " size_t idx" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_clientdata_hash "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_count "fido_assert_t *assert" "size_t n" +.Ft int +.Fn fido_assert_set_extensions "fido_assert_t *assert" "int flags" +.Ft int +.Fn fido_assert_set_hmac_salt "fido_assert_t *assert" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_assert_set_up "fido_assert_t *assert" "fido_opt_t up" +.Ft int +.Fn fido_assert_set_uv "fido_assert_t *assert" "fido_opt_t uv" +.Ft int +.Fn fido_assert_set_rp "fido_assert_t *assert" "const char *id" +.Ft int +.Fn fido_assert_set_sig "fido_assert_t *assert" "size_t idx" "const unsigned char *ptr" "size_t len" +.Sh DESCRIPTION +The +.Nm +set of functions define the various parameters of a FIDO 2 +assertion, allowing a +.Fa fido_assert_t +type to be prepared for a subsequent call to +.Xr fido_dev_get_assert 3 +or +.Xr fido_assert_verify 3 . +For the complete specification of a FIDO 2 assertion and the format +of its constituent parts, please refer to the Web Authentication +(webauthn) standard. +.Pp +The +.Fn fido_assert_set_count +function sets the number of assertion statements in +.Fa assert +to +.Fa n . +.Pp +The +.Fn fido_assert_set_authdata +and +.Fn fido_assert_set_sig +functions set the authenticator data and signature parts of the +statement with index +.Fa idx +of +.Fa assert +to +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +Please note that the first assertion statement of +.Fa assert +has an +.Fa idx +of +.Em 0 . +The authenticator data passed to +.Fn fido_assert_set_authdata +must be a CBOR-encoded byte string, as obtained from +.Fn fido_assert_authdata_ptr . +Alternatively, a raw binary blob may be passed to +.Fn fido_assert_set_authdata_raw . +.Pp +The +.Fn fido_assert_set_clientdata_hash +and +.Fn fido_assert_set_hmac_salt +functions set the client data hash and hmac-salt parts of +.Fa assert +to +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +.Pp +The +.Fn fido_assert_set_rp +function sets the relying party +.Fa id +of +.Fa assert , +where +.Fa id +is a NUL-terminated UTF-8 string. +The content of +.Fa id +is copied, and no references to the passed pointer are kept. +.Pp +The +.Fn fido_assert_set_extensions +function sets the extensions of +.Fa assert +to the bitmask +.Fa flags . +At the moment, only the +.Dv FIDO_EXT_HMAC_SECRET +extension is supported. +If +.Fa flags +is zero, the extensions of +.Fa assert +are cleared. +.Pp +The +.Fn fido_assert_set_up +and +.Fn fido_assert_set_uv +functions set the +.Fa up +(user presence) and +.Fa uv +(user verification) +attributes of +.Fa assert . +Both are +.Dv FIDO_OPT_OMIT +by default, allowing the authenticator to use its default settings. +.Pp +Use of the +.Nm +set of functions may happen in two distinct situations: +when asking a FIDO device to produce a series of assertion +statements, prior to +.Xr fido_dev_get_assert 3 +(i.e, in the context of a FIDO client), or when verifying assertion +statements using +.Xr fido_assert_verify 3 +(i.e, in the context of a FIDO server). +.Pp +For a complete description of the generation of a FIDO 2 assertion +and its verification, please refer to the FIDO 2 specification. +An example of how to use the +.Nm +set of functions can be found in the +.Pa examples/assert.c +file shipped with +.Em libfido2 . +.Sh RETURN VALUES +The +.Nm +functions return +.Dv FIDO_OK +on success. +The error codes returned by the +.Nm +set of functions are defined in +.In fido/err.h . +.Sh SEE ALSO +.Xr fido_assert_allow_cred 3 , +.Xr fido_assert_verify 3 , +.Xr fido_dev_get_assert 3 diff --git a/man/fido_assert_verify.3 b/man/fido_assert_verify.3 new file mode 100644 index 0000000..82e64e1 --- /dev/null +++ b/man/fido_assert_verify.3 @@ -0,0 +1,79 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 24 2018 $ +.Dt FIDO_ASSERT_VERIFY 3 +.Os +.Sh NAME +.Nm fido_assert_verify +.Nd verifies the signature of a FIDO 2 assertion statement +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_assert_verify "fido_assert_t *assert" "size_t idx" "int cose_alg" "const void *pk" +.Sh DESCRIPTION +The +.Fn fido_assert_verify +function verifies whether the signature contained in statement index +.Fa idx +of +.Fa assert +matches the parameters of the assertion. +Before using +.Fn fido_assert_verify +in a sensitive context, the reader is strongly encouraged to make +herself familiar with the FIDO 2 assertion statement process +as defined in the Web Authentication (webauthn) standard. +.Pp +A brief description follows: +.Pp +The +.Fn fido_assert_verify +function verifies whether the client data hash, relying party ID, +user presence and user verification attributes of +.Fa assert +have been attested by the holder of the private counterpart of +the public key +.Fa pk +of COSE type +.Fa cose_alg , +where +.Fa cose_alg +is +.Dv COSE_ES256 , +.Dv COSE_RS256 , +or +.Dv COSE_EDDSA , +and +.Fa pk +points to a +.Vt es256_pk_t , +.Vt rs256_pk_t , +or +.Vt eddsa_pk_t +type accordingly. +.Pp +Please note that the first statement in +.Fa assert +has an +.Fa idx +of 0. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_assert_verify +are defined in +.In fido/err.h . +If +statement +.Fa idx +of +.Fa assert +passes verification with +.Fa pk , +then +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_assert_new 3 , +.Xr fido_assert_set_authdata 3 diff --git a/man/fido_bio_dev_get_info.3 b/man/fido_bio_dev_get_info.3 new file mode 100644 index 0000000..bde1396 --- /dev/null +++ b/man/fido_bio_dev_get_info.3 @@ -0,0 +1,120 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: September 13 2019 $ +.Dt FIDO_BIO_DEV_GET_INFO 3 +.Os +.Sh NAME +.Nm fido_bio_dev_get_info , +.Nm fido_bio_dev_enroll_begin , +.Nm fido_bio_dev_enroll_continue , +.Nm fido_bio_dev_enroll_cancel , +.Nm fido_bio_dev_enroll_remove , +.Nm fido_bio_dev_get_template_array , +.Nm fido_bio_dev_set_template_name +.Nd FIDO 2 biometric authenticator API +.Sh SYNOPSIS +.In fido.h +.In fido/bio.h +.Ft int +.Fn fido_bio_dev_get_info "fido_dev_t *dev" "fido_bio_info_t *info" +.Ft int +.Fn fido_bio_dev_enroll_begin "fido_dev_t *dev" "fido_bio_template_t *template" "fido_bio_enroll_t *enroll" "uint32_t timeout_ms" "const char *pin" +.Ft int +.Fn fido_bio_dev_enroll_continue "fido_dev_t *dev" "const fido_bio_template_t *template" "fido_bio_enroll_t *enroll" "uint32_t timeout_ms" +.Ft int +.Fn fido_bio_dev_enroll_cancel "fido_dev_t *dev" +.Ft int +.Fn fido_bio_dev_enroll_remove "fido_dev_t *dev" "const fido_bio_template_t *template" "const char *pin" +.Ft int +.Fn fido_bio_dev_get_template_array "fido_dev_t *dev" "fido_bio_template_array_t *template_array" "const char *pin" +.Ft int +.Fn fido_bio_dev_set_template_name "fido_dev_t *dev" "const fido_bio_template_t *template" "const char *pin" +.Sh DESCRIPTION +The functions described in this page allow biometric +templates on a FIDO2 authenticator to be listed, created, +removed, and customised. +For a description of the types involved, please refer to +.Xr fido_bio_info_new 3 , +.Xr fido_bio_enroll_new 3 , +and +.Xr fido_bio_template 3 . +.Pp +The +.Fn fido_bio_dev_get_info +function populates +.Fa info +with sensor information from +.Fa dev . +.Pp +The +.Fn fido_bio_dev_enroll_begin +function initiates a biometric enrollment on +.Fa dev , +instructing the authenticator to wait +.Fa timeout_ms +milliseconds. +On success, +.Fa template +and +.Fa enroll +will be populated with the newly created template's +information and enrollment status, respectively. +.Pp +The +.Fn fido_bio_dev_enroll_continue +function continues an ongoing enrollment on +.Fa dev , +instructing the authenticator to wait +.Fa timeout_ms +milliseconds. +On success, +.Fa enroll +will be updated to reflect the status of the biometric +enrollment. +.Pp +The +.Fn fido_bio_dev_enroll_cancel +function cancels an ongoing enrollment on +.Fa dev . +.Pp +The +.Fn fido_bio_dev_enroll_remove +function removes +.Fa template +from +.Fa dev . +.Pp +The +.Fn fido_bio_dev_get_template_array +function populates +.Fa template_array +with the templates currently enrolled on +.Fa dev . +.Pp +The +.Fn fido_bio_dev_set_template_name +function sets the friendly name of +.Fa template +on +.Fa dev . +.Pp +The error codes returned by +.Fn fido_bio_dev_get_info , +.Fn fido_bio_dev_enroll_begin , +.Fn fido_bio_dev_enroll_continue , +.Fn fido_bio_dev_enroll_cancel , +.Fn fido_bio_dev_enroll_remove , +.Fn fido_bio_dev_get_template_array , +and +.Fn fido_bio_dev_set_template_name +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_bio_enroll_new 3 , +.Xr fido_bio_info_new 3 , +.Xr fido_bio_template 3 diff --git a/man/fido_bio_enroll_new.3 b/man/fido_bio_enroll_new.3 new file mode 100644 index 0000000..3db3e7a --- /dev/null +++ b/man/fido_bio_enroll_new.3 @@ -0,0 +1,95 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: September 13 2019 $ +.Dt FIDO_BIO_ENROLL_NEW 3 +.Os +.Sh NAME +.Nm fido_bio_enroll_new , +.Nm fido_bio_enroll_free , +.Nm fido_bio_enroll_last_status , +.Nm fido_bio_enroll_remaining_samples +.Nd FIDO 2 biometric enrollment API +.Sh SYNOPSIS +.In fido.h +.In fido/bio.h +.Bd -literal +#define FIDO_BIO_ENROLL_FP_GOOD 0x00 +#define FIDO_BIO_ENROLL_FP_TOO_HIGH 0x01 +#define FIDO_BIO_ENROLL_FP_TOO_LOW 0x02 +#define FIDO_BIO_ENROLL_FP_TOO_LEFT 0x03 +#define FIDO_BIO_ENROLL_FP_TOO_RIGHT 0x04 +#define FIDO_BIO_ENROLL_FP_TOO_FAST 0x05 +#define FIDO_BIO_ENROLL_FP_TOO_SLOW 0x06 +#define FIDO_BIO_ENROLL_FP_POOR_QUALITY 0x07 +#define FIDO_BIO_ENROLL_FP_TOO_SKEWED 0x08 +#define FIDO_BIO_ENROLL_FP_TOO_SHORT 0x09 +#define FIDO_BIO_ENROLL_FP_MERGE_FAILURE 0x0a +#define FIDO_BIO_ENROLL_FP_EXISTS 0x0b +#define FIDO_BIO_ENROLL_FP_DATABASE_FULL 0x0c +#define FIDO_BIO_ENROLL_NO_USER_ACTIVITY 0x0d +#define FIDO_BIO_ENROLL_NO_USER_PRESENCE_TRANSITION 0x0e +.Ed +.Ft fido_bio_enroll_t * +.Fn fido_bio_enroll_new "void" +.Ft void +.Fn fido_bio_enroll_free "fido_bio_enroll_t **enroll_p" +.Ft uint8_t +.Fn fido_bio_enroll_last_status "const fido_bio_enroll_t *enroll" +.Ft uint8_t +.Fn fido_bio_enroll_remaining_samples "const fido_bio_enroll_t *enroll" +.Sh DESCRIPTION +Ongoing FIDO 2 biometric enrollments are abstracted in +.Em libfido2 +by the +.Vt fido_bio_enroll_t +type. +.Pp +The functions described in this page allow a +.Vt fido_bio_enroll_t +type to be allocated, deallocated, and inspected. +For device operations on +.Vt fido_bio_enroll_t , +please refer to +.Xr fido_bio_dev_get_info 3 . +.Pp +The +.Fn fido_bio_enroll_new +function returns a pointer to a newly allocated, empty +.Vt fido_bio_enroll_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_bio_enroll_free +function releases the memory backing +.Fa *enroll_p , +where +.Fa *enroll_p +must have been previously allocated by +.Fn fido_bio_enroll_new . +On return, +.Fa *enroll_p +is set to NULL. +Either +.Fa enroll_p +or +.Fa *enroll_p +may be NULL, in which case +.Fn fido_bio_enroll_free +is a NOP. +.Pp +The +.Fn fido_bio_enroll_last_status +function returns the enrollment status of +.Fa enroll . +.Pp +The +.Fn fido_bio_enroll_remaining_samples +function returns the number of samples left for +.Fa enroll +to complete. +.Sh SEE ALSO +.Xr fido_bio_dev_get_info 3 , +.Xr fido_bio_template 3 diff --git a/man/fido_bio_info_new.3 b/man/fido_bio_info_new.3 new file mode 100644 index 0000000..c827333 --- /dev/null +++ b/man/fido_bio_info_new.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: September 13 2019 $ +.Dt FIDO_BIO_INFO_NEW 3 +.Os +.Sh NAME +.Nm fido_bio_info_new , +.Nm fido_bio_info_free , +.Nm fido_bio_info_type , +.Nm fido_bio_info_max_samples +.Nd FIDO 2 biometric sensor information API +.Sh SYNOPSIS +.In fido.h +.In fido/bio.h +.Ft fido_bio_info_t * +.Fn fido_bio_info_new "void" +.Ft void +.Fn fido_bio_info_free "fido_bio_info_t **info_p" +.Ft uint8_t +.Fn fido_bio_info_type "const fido_bio_info_t *info" +.Ft uint8_t +.Fn fido_bio_info_max_samples "const fido_bio_info_t *info" +.Sh DESCRIPTION +Biometric sensor metadata is abstracted in +.Em libfido2 +by the +.Vt fido_bio_info_t +type. +.Pp +The functions described in this page allow a +.Vt fido_bio_info_t +type to be allocated, deallocated, and inspected. +For device operations on +.Vt fido_bio_info_t , +please refer to +.Xr fido_bio_dev_get_info 3 . +.Pp +The +.Fn fido_bio_info_new +function returns a pointer to a newly allocated, empty +.Vt fido_bio_info_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_bio_info_free +function releases the memory backing +.Fa *info_p , +where +.Fa *info_p +must have been previously allocated by +.Fn fido_bio_info_new . +On return, +.Fa *info_p +is set to NULL. +Either +.Fa info_p +or +.Fa *info_p +may be NULL, in which case +.Fn fido_bio_info_free +is a NOP. +.Pp +The +.Fn fido_bio_info_type +function returns the fingerprint sensor type, which is +.Dv 1 +for touch sensors, and +.Dv 2 +for swipe sensors. +.Pp +The +.Fn fido_bio_info_max_samples +function returns the maximum number of successful samples +required for enrollment. +.Sh SEE ALSO +.Xr fido_bio_dev_get_info 3 , +.Xr fido_bio_enroll_new 3 , +.Xr fido_bio_template 3 diff --git a/man/fido_bio_template.3 b/man/fido_bio_template.3 new file mode 100644 index 0000000..6140926 --- /dev/null +++ b/man/fido_bio_template.3 @@ -0,0 +1,169 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: September 13 2019 $ +.Dt FIDO_BIO_TEMPLATE 3 +.Os +.Sh NAME +.Nm fido_bio_template , +.Nm fido_bio_template_array_count , +.Nm fido_bio_template_array_free , +.Nm fido_bio_template_array_new , +.Nm fido_bio_template_free , +.Nm fido_bio_template_id_len , +.Nm fido_bio_template_id_ptr , +.Nm fido_bio_template_name , +.Nm fido_bio_template_new , +.Nm fido_bio_template_set_id , +.Nm fido_bio_template_set_name +.Nd FIDO 2 biometric template API +.Sh SYNOPSIS +.In fido.h +.In fido/bio.h +.Ft fido_bio_template_t * +.Fn fido_bio_template_new "void" +.Ft void +.Fn fido_bio_template_free "fido_bio_template_t **template_p" +.Ft const char * +.Fn fido_bio_template_name "const fido_bio_template_t *template" +.Ft const unsigned char * +.Fn fido_bio_template_id_ptr "const fido_bio_template_t *template" +.Ft size_t +.Fn fido_bio_template_id_len "const fido_bio_template_t *template" +.Ft int +.Fn fido_bio_template_set_id "fido_bio_template_t *template" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_bio_template_set_name "fido_bio_template_t *template" "const char *name" +.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" +.Ft size_t +.Fn fido_bio_template_array_count "const fido_bio_template_array_t *template_array" +.Ft const fido_bio_template_t * +.Fn fido_bio_template "const fido_bio_template_array_t *template_array" "size_t idx" +.Sh DESCRIPTION +Existing FIDO 2 biometric enrollments are abstracted in +.Em libfido2 +by the +.Vt fido_bio_template_t +and +.Vt fido_bio_template_array_t +types. +.Pp +The functions described in this page allow a +.Vt fido_bio_template_t +type to be allocated, deallocated, changed, and inspected, +and a +.Vt fido_bio_template_array_t +type to be allocated, deallocated, and inspected. +For device operations on +.Vt fido_bio_template_t +and +.Vt fido_bio_template_array_t , +please refer to +.Xr fido_bio_dev_get_info 3 . +.Pp +The +.Fn fido_bio_template_new +function returns a pointer to a newly allocated, empty +.Vt fido_bio_template_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_bio_template_free +function releases the memory backing +.Fa *template_p , +where +.Fa *template_p +must have been previously allocated by +.Fn fido_bio_template_new . +On return, +.Fa *template_p +is set to NULL. +Either +.Fa template_p +or +.Fa *template_p +may be NULL, in which case +.Fn fido_bio_template_free +is a NOP. +.Pp +The +.Fn fido_bio_template_name +function returns a pointer to a NUL-terminated string containing +the friendly name of +.Fa template , +or NULL if +.Fa template +does not have a friendly name set. +.Pp +The +.Fn fido_bio_template_id_ptr +function returns a pointer to the template id of +.Fa template , +or NULL if +.Fa template +does not have an id. +The corresponding length can be obtained by +.Fn fido_bio_template_id_len . +.Pp +The +.Fn fido_bio_template_set_name +function sets the friendly name of +.Fa template +to +.Fa name . +If +.Fa name +is NULL, the friendly name of +.Fa template +is unset. +.Pp +The +.Fn fido_bio_template_array_new +function returns a pointer to a newly allocated, empty +.Vt fido_bio_template_array_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_bio_template_array_free +function releases the memory backing +.Fa *template_array_p , +where +.Fa *template_array_p +must have been previously allocated by +.Fn fido_bio_template_array_new . +On return, +.Fa *template_array_p +is set to NULL. +Either +.Fa template_array_p +or +.Fa *template_array_p +may be NULL, in which case +.Fn fido_bio_template_array_free +is a NOP. +.Pp +The +.Fn fido_bio_template_array_count +function returns the number of templates in +.Fa template_array . +.Pp +The +.Fn fido_bio_template +function returns a pointer to the template at index +.Fa idx +in +.Fa template_array . +Please note that the first template in +.Fa template_array +has an +.Fa idx +(index) value of 0. +.Sh SEE ALSO +.Xr fido_bio_dev_get_info 3 , +.Xr fido_bio_enroll_new 3 diff --git a/man/fido_cbor_info_new.3 b/man/fido_cbor_info_new.3 new file mode 100644 index 0000000..d1e4c41 --- /dev/null +++ b/man/fido_cbor_info_new.3 @@ -0,0 +1,153 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 24 2018 $ +.Dt FIDO_CBOR_INFO_NEW 3 +.Os +.Sh NAME +.Nm fido_cbor_info_new , +.Nm fido_cbor_info_free , +.Nm fido_dev_get_cbor_info , +.Nm fido_cbor_info_aaguid_ptr , +.Nm fido_cbor_info_extensions_ptr , +.Nm fido_cbor_info_protocols_ptr , +.Nm fido_cbor_info_versions_ptr , +.Nm fido_cbor_info_options_name_ptr , +.Nm fido_cbor_info_options_value_ptr , +.Nm fido_cbor_info_aaguid_len , +.Nm fido_cbor_info_extensions_len , +.Nm fido_cbor_info_protocols_len , +.Nm fido_cbor_info_versions_len , +.Nm fido_cbor_info_options_len , +.Nm fido_cbor_info_maxmsgsiz +.Nd FIDO 2 CBOR Info API +.Sh SYNOPSIS +.In fido.h +.Ft fido_cbor_info_t * +.Fn fido_cbor_info_new "void" +.Ft void +.Fn fido_cbor_info_free "fido_cbor_info_t **ci_p" +.Ft int +.Fn fido_dev_get_cbor_info "fido_dev_t *dev" "fido_cbor_info_t *ci" +.Ft const unsigned char * +.Fn fido_cbor_info_aaguid_ptr "const fido_cbor_info_t *ci" +.Ft char ** +.Fn fido_cbor_info_extensions_ptr "const fido_cbor_info_t *ci" +.Ft const uint8_t * +.Fn fido_cbor_info_protocols_ptr "const fido_cbor_info_t *ci" +.Ft char ** +.Fn fido_cbor_info_versions_ptr "const fido_cbor_info_t *ci" +.Ft char ** +.Fn fido_cbor_info_options_name_ptr "const fido_cbor_info_t *ci" +.Ft const bool * +.Fn fido_cbor_info_options_value_ptr "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_aaguid_len "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_extensions_len "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_protocols_len "const fido_cbor_info_t *ci" +.Ft size_t +.Fn fido_cbor_info_versions_len "const fido_cbor_info_t *ci" +.Ft size_t +.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" +.Sh DESCRIPTION +The +.Fn fido_cbor_info_new +function returns a pointer to a newly allocated, empty +.Vt fido_cbor_info_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_cbor_info_free +function releases the memory backing +.Fa *ci_p , +where +.Fa *ci_p +must have been previously allocated by +.Fn fido_cbor_info_new . +On return, +.Fa *ci_p +is set to NULL. +Either +.Fa ci_p +or +.Fa *ci_p +may be NULL, in which case +.Fn fido_cbor_info_free +is a NOP. +.Pp +The +.Fn fido_dev_get_cbor_info +function transmits a +.Dv CTAP_CBOR_GETINFO +command to +.Fa dev +and fills +.Fa ci +with attributes retrieved from the command's response. +The +.Fn fido_dev_get_cbor_info +function may block. +.Pp +The +.Fn fido_cbor_info_aaguid_ptr , +.Fn fido_cbor_info_extensions_ptr , +.Fn fido_cbor_info_protocols_ptr , +and +.Fn fido_cbor_info_versions_ptr +functions return pointers to the AAGUID, supported extensions, +PIN protocol and CTAP version strings of +.Fa ci . +The corresponding length of a given attribute can be +obtained by +.Fn fido_cbor_info_aaguid_len , +.Fn fido_cbor_info_extensions_len , +.Fn fido_cbor_info_protocols_len , +or +.Fn fido_cbor_info_versions_len . +.Pp +The +.Fn fido_cbor_info_options_name_ptr +and +.Fn fido_cbor_info_options_value_ptr +functions return pointers to the array of option names and their +respective values +in +.Fa ci . +The length of the options array is returned by +.Fn fido_cbor_info_options_len . +.Pp +The +.Fn fido_cbor_info_maxmsgsiz +function returns the maximum message size of +.Fa ci . +.Pp +A complete example of how to use these functions can be found in the +.Pa example/info.c +file shipped with +.Em libfido2 . +.Sh RETURN VALUES +The +.Fn fido_cbor_info_aaguid_ptr , +.Fn fido_cbor_info_extensions_ptr , +.Fn fido_cbor_info_protocols_ptr , +.Fn fido_cbor_info_versions_ptr , +.Fn fido_cbor_info_options_name_ptr , +and +.Fn fido_cbor_info_options_value_ptr +functions return NULL if the respective field in +.Fa ci +is absent. +If not NULL, returned pointers are guaranteed to exist until any +API function that takes +.Fa ci +without the +.Em const +qualifier is invoked. +.Sh SEE ALSO +.Xr fido_dev_open 3 diff --git a/man/fido_cred_exclude.3 b/man/fido_cred_exclude.3 new file mode 100644 index 0000000..700d6af --- /dev/null +++ b/man/fido_cred_exclude.3 @@ -0,0 +1,60 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_CRED_EXCLUDE 3 +.Os +.Sh NAME +.Nm fido_cred_exclude +.Nd appends a credential ID to a credential's list of excluded credentials +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_cred_exclude "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Sh DESCRIPTION +The +.Fn fido_cred_exclude +function adds +.Fa ptr +to the list of credentials excluded by +.Fa cred , +where +.Fa ptr +points to a credential ID of +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +If +.Fn fido_cred_exclude +fails, the existing list of excluded credentials is preserved. +.Pp +If +.Nm +returns success and +.Fa cred +is later passed to +.Xr fido_dev_make_cred 3 +on a device that contains the credential +denoted by +.Fa ptr , +then +.Xr fido_dev_make_cred 3 +will fail. +.Pp +For the format of a FIDO 2 credential ID, please refer to the +Web Authentication (webauthn) standard. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_cred_exclude +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cred_new 3 , +.Xr fido_cred_set_authdata 3 , +.Xr fido_dev_make_cred 3 diff --git a/man/fido_cred_new.3 b/man/fido_cred_new.3 new file mode 100644 index 0000000..47eeba8 --- /dev/null +++ b/man/fido_cred_new.3 @@ -0,0 +1,157 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_CRED_NEW 3 +.Os +.Sh NAME +.Nm fido_cred_new , +.Nm fido_cred_free , +.Nm fido_cred_fmt , +.Nm fido_cred_authdata_ptr , +.Nm fido_cred_clientdata_hash_ptr , +.Nm fido_cred_id_ptr , +.Nm fido_cred_pubkey_ptr , +.Nm fido_cred_sig_ptr , +.Nm fido_cred_x5c_ptr , +.Nm fido_cred_authdata_len , +.Nm fido_cred_clientdata_hash_len , +.Nm fido_cred_id_len , +.Nm fido_cred_pubkey_len , +.Nm fido_cred_sig_len , +.Nm fido_cred_x5c_len +.Nd FIDO 2 credential API +.Sh SYNOPSIS +.In fido.h +.Ft fido_cred_t * +.Fn fido_cred_new "void" +.Ft void +.Fn fido_cred_free "fido_cred_t **cred_p" +.Ft const char * +.Fn fido_cred_fmt "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_authdata_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_clientdata_hash_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_id_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_pubkey_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_sig_ptr "const fido_cred_t *cred" +.Ft const unsigned char * +.Fn fido_cred_x5c_ptr "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_authdata_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_clientdata_hash_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_id_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_pubkey_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_sig_len "const fido_cred_t *cred" +.Ft size_t +.Fn fido_cred_x5c_len "const fido_cred_t *cred" +.Sh DESCRIPTION +FIDO 2 credentials are abstracted in +.Em libfido2 +by the +.Vt fido_cred_t +type. +The functions described in this page allow a +.Vt fido_cred_t +type to be allocated, deallocated, and inspected. +For other operations on +.Vt fido_cred_t , +please refer to +.Xr fido_cred_set_authdata 3 , +.Xr fido_cred_exclude 3 , +.Xr fido_cred_verify 3 , +and +.Xr fido_dev_make_cred 3 . +.Pp +The +.Fn fido_cred_new +function returns a pointer to a newly allocated, empty +.Vt fido_cred_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_cred_free +function releases the memory backing +.Fa *cred_p , +where +.Fa *cred_p +must have been previously allocated by +.Fn fido_cred_new . +On return, +.Fa *cred_p +is set to NULL. +Either +.Fa cred_p +or +.Fa *cred_p +may be NULL, in which case +.Fn fido_cred_free +is a NOP. +.Pp +The +.Fn fido_cred_fmt +function returns a pointer to a NUL-terminated string containing +the format of +.Fa cred , +or NULL if +.Fa cred +does not have a format set. +.Pp +The +.Fn fido_cred_authdata_ptr , +.Fn fido_cred_clientdata_hash_ptr , +.Fn fido_cred_id_ptr , +.Fn fido_cred_pubkey_ptr , +.Fn fido_cred_sig_ptr , +and +.Fn fido_cred_x5c_ptr +functions return pointers to the authenticator data, client data +hash, ID, public key, signature and x509 certificate parts of +.Fa cred , +or NULL if the respective entry is not set. +.Pp +The corresponding length can be obtained by +.Fn fido_cred_authdata_len , +.Fn fido_cred_clientdata_hash_len , +.Fn fido_cred_id_len , +.Fn fido_cred_pubkey_len , +and +.Fn fido_cred_sig_len . +.Pp +The authenticator data, x509 certificate, and signature parts of a +credential are typically passed to a FIDO 2 server for verification. +.Sh RETURN VALUES +The authenticator data returned by +.Fn fido_cred_authdata_ptr +is a CBOR-encoded byte string, as obtained from the authenticator. +.Pp +If not NULL, pointers returned by +.Fn fido_cred_fmt , +.Fn fido_cred_authdata_ptr , +.Fn fido_cred_clientdata_hash_ptr , +.Fn fido_cred_id_ptr , +.Fn fido_cred_pubkey_ptr , +.Fn fido_cred_sig_ptr , +and +.Fn fido_cred_x5c_ptr +are guaranteed to exist until any API function that takes +.Fa cred +without the +.Em const +qualifier is invoked. +.Sh SEE ALSO +.Xr fido_cred_exclude 3 , +.Xr fido_cred_set_authdata 3 , +.Xr fido_cred_verify 3 , +.Xr fido_credman_metadata_new 3 , +.Xr fido_dev_make_cred 3 diff --git a/man/fido_cred_set_authdata.3 b/man/fido_cred_set_authdata.3 new file mode 100644 index 0000000..8b087fa --- /dev/null +++ b/man/fido_cred_set_authdata.3 @@ -0,0 +1,240 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_CRED_SET_AUTHDATA 3 +.Os +.Sh NAME +.Nm fido_cred_set_authdata , +.Nm fido_cred_set_authdata_raw , +.Nm fido_cred_set_x509 , +.Nm fido_cred_set_sig , +.Nm fido_cred_set_clientdata_hash , +.Nm fido_cred_set_rp , +.Nm fido_cred_set_user , +.Nm fido_cred_set_extensions , +.Nm fido_cred_set_rk , +.Nm fido_cred_set_uv , +.Nm fido_cred_set_fmt , +.Nm fido_cred_set_type +.Nd set parameters of a FIDO 2 credential +.Sh SYNOPSIS +.In fido.h +.Bd -literal +typedef enum { + FIDO_OPT_OMIT = 0, /* use authenticator's default */ + FIDO_OPT_FALSE, /* explicitly set option to false */ + FIDO_OPT_TRUE, /* explicitly set option to true */ +} fido_opt_t; +.Ed +.Ft int +.Fn fido_cred_set_authdata "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_authdata_raw "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_x509 "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_sig "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_clientdata_hash "fido_cred_t *cred" "const unsigned char *ptr" "size_t len" +.Ft int +.Fn fido_cred_set_rp "fido_cred_t *cred" "const char *id" "const char *name" +.Ft int +.Fn fido_cred_set_user "fido_cred_t *cred" "const unsigned char *user_id" "size_t user_id_len" "const char *name" "const char *display_name" "const char *icon" +.Ft int +.Fn fido_cred_set_extensions "fido_cred_t *cred" "int flags" +.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" +.Ft int +.Fn fido_cred_set_fmt "fido_cred_t *cred" "const char *ptr" +.Ft int +.Fn fido_cred_set_type "fido_cred_t *cred" "int cose_alg" +.Sh DESCRIPTION +The +.Nm +set of functions define the various parameters of a FIDO 2 +credential, allowing a +.Fa fido_cred_t +type to be prepared for a subsequent call to +.Xr fido_dev_make_cred 3 +or +.Xr fido_cred_verify 3 . +For the complete specification of a FIDO 2 credential and the format +of its constituent parts, please refer to the Web Authentication +(webauthn) standard. +.Pp +The +.Fn fido_cred_set_authdata , +.Fn fido_cred_set_x509 , +.Fn fido_cred_set_sig , +and +.Fn fido_cred_set_clientdata_hash +functions set the authenticator data, attestation certificate, +signature and client data hash parts of +.Fa cred +to +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +A copy of +.Fa ptr +is made, and no references to the passed pointer are kept. +The authenticator data passed to +.Fn fido_cred_set_authdata +must be a CBOR-encoded byte string, as obtained from +.Fn fido_cred_authdata_ptr . +Alternatively, a raw binary blob may be passed to +.Fn fido_cred_set_authdata_raw . +.Pp +The +.Fn fido_cred_set_rp +function sets the relying party +.Fa id +and +.Fa name +parameters of +.Fa cred , +where +.Fa id +and +.Fa name +are NUL-terminated UTF-8 strings. +The contents of +.Fa id +and +.Fa name +are copied, and no references to the passed pointers are kept. +.Pp +The +.Fn fido_cred_set_user +function sets the user attributes of +.Fa cred , +where +.Fa user_id +points to +.Fa user_id_len +bytes and +.Fa name , +.Fa display_name , +and +.Fa icon +are NUL-terminated UTF-8 strings. +The contents of +.Fa user_id , +.Fa name , +.Fa display_name , +and +.Fa icon +are copied, and no references to the passed pointers are kept. +Previously set user attributes are flushed. +The +.Fa user_id , +.Fa name , +.Fa display_name , +and +.Fa icon +parameters may be NULL. +.Pp +The +.Fn fido_cred_set_extensions +function sets the extensions of +.Fa cred +to the bitmask +.Fa flags . +At the moment, only the +.Dv FIDO_EXT_HMAC_SECRET +extension is supported. +If +.Fa flags +is zero, the extensions of +.Fa cred +are cleared. +.Pp +The +.Fn fido_cred_set_rk +and +.Fn fido_cred_set_uv +functions set the +.Em rk +(resident key) +and +.Em uv +(user verification) +attributes of +.Fa cred . +Both are +.Dv FIDO_OPT_OMIT +by default, allowing the authenticator to use its default settings. +.Pp +The +.Fn fido_cred_set_fmt +function sets the format of +.Fa cred +to +.Fa fmt , +where +.Fa fmt +must be either +.Vt "packed" +(the format used in FIDO 2) +or +.Vt "fido-u2f" +(the format used by U2F). +A copy of +.Fa fmt +is made, and no references to the passed pointer are kept. +Note that not all authenticators support FIDO2 and therefore may not +be able to generate +.Vt "packed" . +.Pp +The +.Fn fido_cred_set_type +function sets the type of +.Fa cred to +.Fa cose_alg , +where +.Fa cose_alg +is +.Dv COSE_ES256 , +.Dv COSE_RS256 , +or +.Dv COSE_EDDSA . +The type of a credential may only be set once. +Note that not all authenticators support COSE_RS256 or COSE_EDDSA. +.Pp +Use of the +.Nm +set of functions may happen in two distinct situations: +when generating a new credential on a FIDO device, prior to +.Xr fido_dev_make_cred 3 +(i.e, in the context of a FIDO client), or when validating +a generated credential using +.Xr fido_cred_verify 3 +(i.e, in the context of a FIDO server). +.Pp +For a complete description of the generation of a FIDO 2 credential +and its verification, please refer to the FIDO 2 specification. +A concrete utilisation example of the +.Nm +set of functions can be found in the +.Pa cred.c +example shipped with +.Em libfido2 . +.Sh RETURN VALUES +The error codes returned by the +.Nm +set of functions are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cred_exclude 3 , +.Xr fido_cred_verify 3 , +.Xr fido_dev_make_cred 3 diff --git a/man/fido_cred_verify.3 b/man/fido_cred_verify.3 new file mode 100644 index 0000000..c75b9a1 --- /dev/null +++ b/man/fido_cred_verify.3 @@ -0,0 +1,64 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_CRED_VERIFY 3 +.Os +.Sh NAME +.Nm fido_cred_verify +.Nd verifies the signature of a FIDO 2 credential +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_cred_verify "const fido_cred_t *cred" +.Sh DESCRIPTION +The +.Fn fido_cred_verify +function verifies whether the signature contained in +.Fa cred +matches the attributes of the credential. +Before using +.Fn fido_cred_verify +in a sensitive context, the reader is strongly encouraged to make +herself familiar with the FIDO 2 credential attestation process +as defined in the Web Authentication (webauthn) standard. +.Pp +A brief description follows: +.Pp +The +.Fn fido_cred_verify +function verifies whether the client data hash, relying party ID, +credential ID, type, and resident key and user verification +attributes of +.Fa cred +have been attested by the holder of the private counterpart of +the public key contained in the credential's x509 certificate. +.Pp +Please note that the x509 certificate itself is not verified. +.Pp +The attestation statement formats supported by +.Fn fido_cred_verify +are +.Em packed +and +.Em fido-u2f . +The attestation type implemented by +.Fn fido_cred_verify +is +.Em Basic Attestation . +The attestation key pair is assumed to be of the type ES256. +Other attestation formats and types are not supported. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_cred_verify +are defined in +.In fido/err.h . +If +.Fa cred +passes verification, then +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cred_new 3 , +.Xr fido_cred_set_authdata 3 diff --git a/man/fido_credman_metadata_new.3 b/man/fido_credman_metadata_new.3 new file mode 100644 index 0000000..16f0192 --- /dev/null +++ b/man/fido_credman_metadata_new.3 @@ -0,0 +1,299 @@ +.\" Copyright (c) 2019 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: June 28 2019 $ +.Dt FIDO_CREDMAN_METADATA_NEW 3 +.Os +.Sh NAME +.Nm fido_credman_metadata_new , +.Nm fido_credman_rk_new , +.Nm fido_credman_rp_new , +.Nm fido_credman_metadata_free , +.Nm fido_credman_rk_free , +.Nm fido_credman_rp_free , +.Nm fido_credman_rk_existing , +.Nm fido_credman_rk_remaining , +.Nm fido_credman_rk , +.Nm fido_credman_rk_count , +.Nm fido_credman_rp_id , +.Nm fido_credman_rp_name , +.Nm fido_credman_rp_count , +.Nm fido_credman_rp_id_hash_ptr , +.Nm fido_credman_rp_id_hash_len , +.Nm fido_credman_get_dev_metadata , +.Nm fido_credman_get_dev_rk , +.Nm fido_credman_del_dev_rk , +.Nm fido_credman_get_dev_rp +.Nd FIDO 2 credential management API +.Sh SYNOPSIS +.In fido.h +.In fido/credman.h +.Ft fido_credman_metadata_t * +.Fn fido_credman_metadata_new "void" +.Ft fido_credman_rk_t * +.Fn fido_credman_rk_new "void" +.Ft fido_credman_rp_t * +.Fn fido_credman_rp_new "void" +.Ft void +.Fn fido_credman_metadata_free "fido_credman_metadata_t **metadata_p" +.Ft void +.Fn fido_credman_rk_free "fido_credman_rk_t **rk_p" +.Ft void +.Fn fido_credman_rp_free "fido_credman_rp_t **rp_p" +.Ft uint64_t +.Fn fido_credman_rk_existing "const fido_credman_metadata_t *metadata" +.Ft uint64_t +.Fn fido_credman_rk_remaining "const fido_credman_metadata_t *metadata" +.Ft const fido_cred_t * +.Fn fido_credman_rk "const fido_credman_rk_t *rk" "size_t idx" +.Ft size_t +.Fn fido_credman_rk_count "const fido_credman_rk_t *rk" +.Ft const char * +.Fn fido_credman_rp_id "const fido_credman_rp_t *rp" "size_t idx" +.Ft const char * +.Fn fido_credman_rp_name "const fido_credman_rp_t *rp" "size_t idx" +.Ft size_t +.Fn fido_credman_rp_count "const fido_credman_rp_t *rp" +.Ft const unsigned char * +.Fn fido_credman_rp_id_hash_ptr "const fido_credman_rp_t *rp" "size_t idx" +.Ft size_t +.Fn fido_credman_rp_id_hash_len "const fido_credman_rp_t *" "size_t idx" +.Ft int +.Fn fido_credman_get_dev_metadata "fido_dev_t *dev" "fido_credman_metadata_t *metadata" "const char *pin" +.Ft int +.Fn fido_credman_get_dev_rk "fido_dev_t *dev" "const char *rp_id" "fido_credman_rk_t *rk" "const char *pin" +.Ft int +.Fn fido_credman_del_dev_rk "fido_dev_t *dev" const unsigned char *cred_id" "size_t cred_id_len" "const char *pin" +.Ft int +.Fn fido_credman_get_dev_rp "fido_dev_t *dev" "fido_credman_rp_t *rp" "const char *pin" +.Sh DESCRIPTION +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. +To obtain information on what an authenticator supports, please +refer to +.Xr fido_cbor_info_new 3 . +.Pp +The +.Vt fido_credman_metadata_t +type abstracts credential management metadata. +.Pp +The +.Fn fido_credman_metadata_new +function returns a pointer to a newly allocated, empty +.Vt fido_credman_metadata_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_credman_metadata_free +function releases the memory backing +.Fa *metadata_p , +where +.Fa *metadata_p +must have been previously allocated by +.Fn fido_credman_metadata_new . +On return, +.Fa *metadata_p +is set to NULL. +Either +.Fa metadata_p +or +.Fa *metadata_p +may be NULL, in which case +.Fn fido_credman_metadata_free +is a NOP. +.Pp +The +.Fn fido_credman_get_dev_metadata +function populates +.Fa metadata +with information retrieved from +.Fa dev . +A valid +.Fa pin +must be provided. +.Pp +The +.Fn fido_credman_rk_existing +function inspects +.Fa metadata +and returns the number of resident credentials on the +authenticator. +The +.Fn fido_credman_rk_remaining +function inspects +.Fa metadata +and returns the estimated number of resident credentials that can +be created on the authenticator. +.Pp +The +.Vt fido_credman_rk_t +type abstracts the set of resident credentials belonging to a +given relying party. +.Pp +The +.Fn fido_credman_rk_new +function returns a pointer to a newly allocated, empty +.Vt fido_credman_rk_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_credman_rk_free +function releases the memory backing +.Fa *rk_p , +where +.Fa *rk_p +must have been previously allocated by +.Fn fido_credman_rk_new . +On return, +.Fa *rk_p +is set to NULL. +Either +.Fa rk_p +or +.Fa *rk_p +may be NULL, in which case +.Fn fido_credman_rk_free +is a NOP. +.Pp +The +.Fn fido_credman_get_dev_rk +function populates +.Fa rk +with the set of resident credentials belonging to +.Fa rp_id +in +.Fa dev . +A valid +.Fa pin +must be provided. +.Pp +The +.Fn fido_credman_rk_count +function returns the number of resident credentials in +.Fa rk . +The +.Fn fido_credman_rk +function returns a pointer to the credential at index +.Fa idx +in +.Fa rk . +Please note that the first credential in +.Fa rk +has an +.Fa idx +(index) value of 0. +.Pp +The +.Fn fido_credman_del_dev_rk +function deletes the resident credential identified by +.Fa cred_id +from +.Fa dev , +where +.Fa cred_id +points to +.Fa cred_id_len +bytes. +A valid +.Fa pin +must be provided. +.Pp +The +.Vt fido_credman_rp_t +type abstracts information about a relying party. +.Pp +The +.Fn fido_credman_rp_new +function returns a pointer to a newly allocated, empty +.Vt fido_credman_rp_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_credman_rp_free +function releases the memory backing +.Fa *rp_p , +where +.Fa *rp_p +must have been previously allocated by +.Fn fido_credman_rp_new . +On return, +.Fa *rp_p +is set to NULL. +Either +.Fa rp_p +or +.Fa *rp_p +may be NULL, in which case +.Fn fido_credman_rp_free +is a NOP. +.Pp +The +.Fn fido_credman_get_dev_rp +function populates +.Fa rp +with information about relying parties with resident credentials +in +.Fa dev . +A valid +.Fa pin +must be provided. +.Pp +The +.Fn fido_credman_rp_count +function returns the number of relying parties in +.Fa rp . +.Pp +The +.Fn fido_credman_rp_id +and +.Fn fido_credman_rp_name +functions return pointers to the id and name of relying party +.Fa idx +in +.Fa rp . +If not NULL, the values returned by these functions point to +NUL-terminated UTF-8 strings. +Please note that the first relying party in +.Fa rp +has an +.Fa idx +(index) value of 0. +.Pp +The +.Fn fido_credman_rp_id_hash_ptr +function returns a pointer to the hashed id of relying party +.Fa idx +in +.Fa rp . +The corresponding length can be obtained by +.Fn fido_credman_rp_id_hash_len . +Please note that the first relying party in +.Fa rp +has an +.Fa idx +(index) value of 0. +.Sh RETURN VALUES +The +.Fn fido_credman_get_dev_metadata , +.Fn fido_credman_get_dev_rk , +.Fn fido_credman_del_dev_rk , +and +.Fn fido_credman_get_dev_rp +functions return +.Dv FIDO_OK +on success. +On error, a different error code defined in +.In fido/err.h +is returned. +Functions returning pointers are not guaranteed to succeed, and +should have their return values checked for NULL. +.Sh SEE ALSO +.Xr fido_cbor_info_new 3 , +.Xr fido_cred_new 3 diff --git a/man/fido_dev_get_assert.3 b/man/fido_dev_get_assert.3 new file mode 100644 index 0000000..2e33fc5 --- /dev/null +++ b/man/fido_dev_get_assert.3 @@ -0,0 +1,76 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 24 2018 $ +.Dt FIDO_DEV_GET_ASSERT 3 +.Os +.Sh NAME +.Nm fido_dev_get_assert +.Nd obtains an assertion from a FIDO device +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_get_assert "fido_dev_t *dev" " fido_assert_t *assert" "const char *pin" +.Sh DESCRIPTION +The +.Fn fido_dev_get_assert +function asks the FIDO device represented by +.Fa dev +for an assertion according to the following parameters defined in +.Fa assert : +.Pp +.Bl -dash -compact +.It +.Nm relying party ID ; +.It +.Nm client data hash ; +.It +.Nm list of allowed credential IDs ; +.It +.Nm user presence and user verification attributes . +.El +.Pp +See +.Xr fido_assert_set_authdata 3 +for information on how these values are set. +.Pp +If a PIN is not needed to authenticate the request against +.Fa dev , +then +.Fa pin +may be NULL. +Otherwise +.Fa pin +must point to a NUL-terminated UTF-8 string. +.Pp +After a successful call to +.Fn fido_dev_get_assert , +the +.Xr fido_assert_count 3 , +.Xr fido_assert_user_display_name 3 , +.Xr fido_assert_user_icon 3 , +.Xr fido_assert_user_name 3 , +.Xr fido_assert_authdata_ptr 3 , +.Xr fido_assert_user_id_ptr 3 , +.Xr fido_assert_sig_ptr 3 , +and +.Xr fido_assert_sigcount 3 +functions may be invoked on +.Fa assert +to retrieve the various attributes of the generated assertion. +.Pp +Please note that +.Fn fido_dev_get_assert +is synchronous and will block if necessary. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_dev_get_assert +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_assert_new 3 , +.Xr fido_assert_set_authdata 3 diff --git a/man/fido_dev_info_manifest.3 b/man/fido_dev_info_manifest.3 new file mode 100644 index 0000000..22519e2 --- /dev/null +++ b/man/fido_dev_info_manifest.3 @@ -0,0 +1,143 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_DEV_INFO_MANIFEST 3 +.Os +.Sh NAME +.Nm fido_dev_info_manifest , +.Nm fido_dev_info_new , +.Nm fido_dev_info_free , +.Nm fido_dev_info_ptr , +.Nm fido_dev_info_path , +.Nm fido_dev_info_product , +.Nm fido_dev_info_vendor , +.Nm fido_dev_info_manufacturer_string , +.Nm fido_dev_info_product_string +.Nd FIDO 2 device discovery functions +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_info_manifest "fido_dev_info_t *devlist" "size_t ilen" "size_t *olen" +.Ft fido_dev_info_t * +.Fn fido_dev_info_new "size_t n" +.Ft void +.Fn fido_dev_info_free "fido_dev_info_t **devlist_p" "size_t n" +.Ft const fido_dev_info_t * +.Fn fido_dev_info_ptr "const fido_dev_info_t *devlist" "size_t i" +.Ft const char * +.Fn fido_dev_info_path "const fido_dev_info_t *di" +.Ft int16_t +.Fn fido_dev_info_product "const fido_dev_info_t *di" +.Ft int16_t +.Fn fido_dev_info_vendor "const fido_dev_info_t *di" +.Ft const char * +.Fn fido_dev_info_manufacturer_string "const fido_dev_info_t *di" +.Ft const char * +.Fn fido_dev_info_product_string "const fido_dev_info_t *di" +.Sh DESCRIPTION +The +.Fn fido_dev_info_manifest +function fills +.Fa devlist +with up to +.Fa ilen +FIDO devices found by the underlying operating system. +Currently only USB HID devices are supported. +The number of discovered devices is returned in +.Fa olen , +where +.Fa olen +is an addressable pointer. +.Pp +The +.Fn fido_dev_info_new +function returns a pointer to a newly allocated, empty device list +with +.Fa n +available slots. +If memory is not available, NULL is returned. +.Pp +The +.Fn fido_dev_info_free +function releases the memory backing +.Fa *devlist_p , +where +.Fa *devlist_p +must have been previously allocated by +.Fn fido_dev_info_new . +The number +.Fa n +of allocated slots must also be provided. +On return, +.Fa *devlist_p +is set to NULL. +Either +.Fa devlist_p +or +.Fa *devlist_p +may be NULL, in which case +.Fn fido_dev_info_free +is a NOP. +.Pp +The +.Fn fido_dev_info_ptr +function returns a pointer to slot number +.Fa i +of +.Fa devlist . +It is the caller's responsibility to ensure that +.Fa i +is bounded. +Please note that the first slot has index 0. +.Pp +The +.Fn fido_dev_info_path +returns the filesystem path or subsystem-specific identification +string of +.Fa di . +.Pp +The +.Fn fido_dev_info_product +function returns the product ID of +.Fa di . +.Pp +The +.Fn fido_dev_info_vendor +function returns the vendor ID of +.Fa di . +.Pp +The +.Fn fido_dev_info_manufacturer_string +function returns the manufacturer string of +.Fa di . +.Pp +The +.Fn fido_dev_info_product_string +function returns the product string of +.Fa di . +.Pp +An example of how to use the functions described in this document +can be found in the +.Pa examples/manifest.c +file shipped with +.Em libfido2 . +.Sh RETURN VALUES +The +.Fn fido_dev_info_manifest +function always returns +.Dv FIDO_OK . +If a discovery error occurs, the +.Fa olen +pointer is set to 0. +.Pp +The pointers returned by +.Fn fido_dev_info_ptr , +.Fn fido_dev_info_path , +.Fn fido_dev_info_manufacturer_string , +and +.Fn fido_dev_info_product_string +are guaranteed to exist until +.Fn fido_dev_info_free +is called on the corresponding device list. diff --git a/man/fido_dev_make_cred.3 b/man/fido_dev_make_cred.3 new file mode 100644 index 0000000..ccaf788 --- /dev/null +++ b/man/fido_dev_make_cred.3 @@ -0,0 +1,77 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 23 2018 $ +.Dt FIDO_DEV_MAKE_CRED 3 +.Os +.Sh NAME +.Nm fido_dev_make_cred +.Nd generates a new credential on a FIDO device +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_make_cred "fido_dev_t *dev" " fido_cred_t *cred" "const char *pin" +.Sh DESCRIPTION +The +.Fn fido_dev_make_cred +function asks the FIDO device represented by +.Fa dev +to generate a new credential according to the following parameters +defined in +.Fa cred : +.Pp +.Bl -dash -compact +.It +.Nm type ; +.It +.Nm client data hash ; +.It +.Nm relying party ; +.It +.Nm user attributes ; +.It +.Nm list of excluded credential IDs ; +.It +.Nm resident key and user verification attributes . +.El +.Pp +See +.Xr fido_cred_set_authdata 3 +for information on how these values are set. +.Pp +If a PIN is not needed to authenticate the request against +.Fa dev , +then +.Fa pin +may be NULL. +Otherwise +.Fa pin +must point to a NUL-terminated UTF-8 string. +.Pp +After a successful call to +.Fn fido_dev_make_cred , +the +.Xr fido_cred_authdata_ptr 3 , +.Xr fido_cred_pubkey_ptr 3 , +.Xr fido_cred_x5c_ptr 3 , +and +.Xr fido_cred_sig_ptr 3 +functions may be invoked on +.Fa cred +to retrieve the various parts of the generated credential. +.Pp +Please note that +.Fn fido_dev_make_cred +is synchronous and will block if necessary. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_dev_make_cred +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh SEE ALSO +.Xr fido_cred_new 3 , +.Xr fido_cred_set_authdata 3 diff --git a/man/fido_dev_open.3 b/man/fido_dev_open.3 new file mode 100644 index 0000000..53e3a12 --- /dev/null +++ b/man/fido_dev_open.3 @@ -0,0 +1,159 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_DEV_OPEN 3 +.Os +.Sh NAME +.Nm fido_dev_open , +.Nm fido_dev_close , +.Nm fido_dev_cancel , +.Nm fido_dev_new , +.Nm fido_dev_free , +.Nm fido_dev_force_fido2 , +.Nm fido_dev_force_u2f , +.Nm fido_dev_is_fido2 , +.Nm fido_dev_protocol , +.Nm fido_dev_build , +.Nm fido_dev_flags , +.Nm fido_dev_major , +.Nm fido_dev_minor +.Nd FIDO 2 device open/close and related functions +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_open "fido_dev_t *dev" "const char *path" +.Ft int +.Fn fido_dev_close "fido_dev_t *dev" +.Ft int +.Fn fido_dev_cancel "fido_dev_t *dev" +.Ft fido_dev_t * +.Fn fido_dev_new "void" +.Ft void +.Fn fido_dev_free "fido_dev_t **dev_p" +.Ft void +.Fn fido_dev_force_fido2 "fido_dev_t *dev" +.Ft void +.Fn fido_dev_force_u2f "fido_dev_t *dev" +.Ft bool +.Fn fido_dev_is_fido2 "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_protocol "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_build "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_flags "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_major "const fido_dev_t *dev" +.Ft uint8_t +.Fn fido_dev_minor "const fido_dev_t *dev" +.Sh DESCRIPTION +The +.Fn fido_dev_open +function opens the device pointed to by +.Fa path , +where +.Fa dev +is a freshly allocated or otherwise closed +.Vt fido_dev_t . +.Pp +The +.Fn fido_dev_close +function closes the device represented by +.Fa dev . +If +.Fa dev +is already closed, +.Fn fido_dev_close +is a NOP. +.Pp +The +.Fn fido_dev_cancel +function cancels any pending requests on +.Fa dev . +.Pp +The +.Fn fido_dev_new +function returns a pointer to a newly allocated, empty +.Vt fido_dev_t . +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn fido_dev_free +function releases the memory backing +.Fa *dev_p , +where +.Fa *dev_p +must have been previously allocated by +.Fn fido_dev_new . +On return, +.Fa *dev_p +is set to NULL. +Either +.Fa dev_p +or +.Fa *dev_p +may be NULL, in which case +.Fn fido_dev_free +is a NOP. +.Pp +The +.Fn fido_dev_force_fido2 +function can be used to force CTAP2 communication with +.Fa dev . +.Pp +The +.Fn fido_dev_force_u2f +function can be used to force CTAP1 (U2F) communication with +.Fa dev . +.Pp +The +.Fn fido_dev_is_fido2 +function returns +.Dv true +if +.Fa dev +is a FIDO 2 device. +.Pp +The +.Fn fido_dev_protocol +function returns the CTAPHID protocol version identifier of +.Fa dev . +.Pp +The +.Fn fido_dev_build +function returns the CTAPHID build version number of +.Fa dev . +.Pp +The +.Fn fido_dev_flags +function returns the CTAPHID capabilities flags of +.Fa dev . +.Pp +The +.Fn fido_dev_major +function returns the CTAPHID major version number of +.Fa dev . +.Pp +The +.Fn fido_dev_minor +function returns the CTAPHID minor version number of +.Fa dev . +.Pp +For the format and meaning of the CTAPHID parameters returned by +functions above, please refer to the FIDO Client to Authenticator +Protocol (CTAP) specification. +.Sh RETURN VALUES +On success, +.Fn fido_dev_open +and +.Fn fido_dev_close +return +.Dv FIDO_OK . +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr fido_dev_info_manifest 3 , +.Xr fido_dev_set_io_functions 3 diff --git a/man/fido_dev_set_io_functions.3 b/man/fido_dev_set_io_functions.3 new file mode 100644 index 0000000..adc4a9e --- /dev/null +++ b/man/fido_dev_set_io_functions.3 @@ -0,0 +1,95 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_DEV_SET_IO_FUNCTIONS 3 +.Os +.Sh NAME +.Nm fido_dev_set_io_functions +.Nd FIDO 2 device I/O interface +.Sh SYNOPSIS +.In fido.h +.Bd -literal +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 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_t; +.Ed +.Ft int +.Fn fido_dev_set_io_functions "fido_dev_t *dev" "const fido_dev_io_t *io" +.Sh DESCRIPTION +The +.Nm +interface defines the I/O 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 +a FIDO device. +.Pp +A +.Vt fido_dev_io_open_t +function is expected to return a non-NULL opaque pointer on success, +and NULL on error. +The returned opaque pointer is never dereferenced by +.Em libfido2 . +.Pp +A +.Vt fido_dev_io_close_t +function receives the opaque handle obtained from +.Vt fido_dev_io_open_t . +It is not expected to be idempotent. +.Pp +A +.Vt fido_dev_io_read_t +function reads 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 +.Vt fido_dev_io_read_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_read_t +may block indefinitely. +The number of bytes read is returned. +On error, -1 is returned. +.Pp +Conversely, a +.Vt fido_dev_io_write_t +function writes to +.Fa dev . +The first parameter taken is the opaque handle returned by +.Vt fido_dev_io_open_t . +The write buffer is pointed to by the second parameter, and the +third parameter holds its size. +A +.Vt fido_dev_io_write_t +function may block. +The number of bytes written is returned. +On error, -1 is returned. +.Pp +No references to +.Fa io +are held by +.Fn fido_dev_set_io_functions . +.Sh RETURN VALUES +On success, +.Fn fido_dev_set_io_functions +returns +.Dv FIDO_OK . +On error, a different error code defined in +.In fido/err.h +is returned. diff --git a/man/fido_dev_set_pin.3 b/man/fido_dev_set_pin.3 new file mode 100644 index 0000000..94f841b --- /dev/null +++ b/man/fido_dev_set_pin.3 @@ -0,0 +1,88 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_DEV_SET_PIN 3 +.Os +.Sh NAME +.Nm fido_dev_set_pin , +.Nm fido_dev_get_retry_count , +.Nm fido_dev_reset +.Nd FIDO 2 device management functions +.Sh SYNOPSIS +.In fido.h +.Ft int +.Fn fido_dev_set_pin "fido_dev_t *dev" "const char *pin" "const char *oldpin" +.Ft int +.Fn fido_dev_get_retry_count "fido_dev_t *dev" "int *retries" +.Ft int +.Fn fido_dev_reset "fido_dev_t *dev" +.Sh DESCRIPTION +The +.Fn fido_dev_set_pin +function sets the PIN of device +.Fa dev +to +.Fa pin , +where +.Fa pin +is a NUL-terminated UTF-8 string. +If +.Fa oldpin +is not NULL, the device's PIN is changed from +.Fa oldpin +to +.Fa pin , +where +.Fa pin +and +.Fa oldpin +are NUL-terminated UTF-8 strings. +.Pp +The +.Fn fido_dev_get_retry_count +function fills +.Fa retries +with the number of PIN retries left in +.Fa dev +before lock-out, where +.Fa retries +is an addressable pointer. +.Pp +The +.Fn fido_dev_reset +function performs a reset on +.Fa dev , +resetting the device's PIN and erasing credentials stored on the +device. +.Pp +Please note that +.Fn fido_dev_set_pin , +.Fn fido_dev_get_retry_count , +and +.Fn fido_dev_reset +are synchronous and will block if necessary. +.Sh RETURN VALUES +The error codes returned by +.Fn fido_dev_set_pin , +.Fn fido_dev_get_retry_count , +and +.Fn fido_dev_reset +are defined in +.In fido/err.h . +On success, +.Dv FIDO_OK +is returned. +.Sh CAVEATS +Regarding +.Fn fido_dev_reset , +the actual user-flow to perform a reset is outside the scope of the +FIDO2 specification, and may therefore vary depending on the +authenticator. +Yubico authenticators will return +.Dv FIDO_ERR_NOT_ALLOWED +if a reset is issued later than 5 seconds after power-up, and +.Dv FIDO_ERR_ACTION_TIMEOUT +if the user fails to confirm the reset by touching the key +within 30 seconds. diff --git a/man/fido_init.3 b/man/fido_init.3 new file mode 100644 index 0000000..7f38948 --- /dev/null +++ b/man/fido_init.3 @@ -0,0 +1,40 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_INIT 3 +.Os +.Sh NAME +.Nm fido_init +.Nd initialise the FIDO 2 library +.Sh SYNOPSIS +.In fido.h +.Ft void +.Fn fido_init "int flags" +.Sh DESCRIPTION +The +.Fn fido_init +function initialises the +.Em libfido2 +library. +Its invocation must precede that of any other +.Em libfido2 +function. +If +.Dv FIDO_DEBUG +is set in +.Fa flags , +then +debug output will be emitted by +.Em libfido2 +on +.Em stderr . +Alternatively, the +.Ev FIDO_DEBUG +environment variable may be set. +.Sh SEE ALSO +.Xr fido_assert_new 3 , +.Xr fido_cred_new 3 , +.Xr fido_dev_info_manifest 3 , +.Xr fido_dev_open 3 diff --git a/man/fido_strerr.3 b/man/fido_strerr.3 new file mode 100644 index 0000000..05c86b9 --- /dev/null +++ b/man/fido_strerr.3 @@ -0,0 +1,27 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 25 2018 $ +.Dt FIDO_STRERR 3 +.Os +.Sh NAME +.Nm fido_strerr +.Nd FIDO 2 error codes +.Sh SYNOPSIS +.In fido.h +.Ft const char * +.Fn fido_strerr "int n" +.Sh DESCRIPTION +The +.Fn fido_strerr +function translates the error code +.Fa n +into a readable string, +where +.Fa n +is an error code defined in +.In fido/err.h . +.Fn fido_strerr +never returns NULL. +Returned pointers point to static strings. diff --git a/man/rs256_pk_new.3 b/man/rs256_pk_new.3 new file mode 100644 index 0000000..4ad0ebe --- /dev/null +++ b/man/rs256_pk_new.3 @@ -0,0 +1,122 @@ +.\" Copyright (c) 2018 Yubico AB. All rights reserved. +.\" Use of this source code is governed by a BSD-style +.\" license that can be found in the LICENSE file. +.\" +.Dd $Mdocdate: May 24 2018 $ +.Dt RS256_PK_NEW 3 +.Os +.Sh NAME +.Nm rs256_pk_new , +.Nm rs256_pk_free , +.Nm rs256_pk_from_RSA , +.Nm rs256_pk_from_ptr , +.Nm rs256_pk_to_EVP_PKEY +.Nd FIDO 2 COSE RS256 API +.Sh SYNOPSIS +.In openssl/rsa.h +.In fido/rs256.h +.Ft rs256_pk_t * +.Fn rs256_pk_new "void" +.Ft void +.Fn rs256_pk_free "rs256_pk_t **pkp" +.Ft int +.Fn rs256_pk_from_RSA "rs256_pk_t *pk" "const RSA *rsa" +.Ft int +.Fn rs256_pk_from_ptr "rs256_pk_t *pk" "const void *ptr" "size_t len" +.Ft EVP_PKEY * +.Fn rs256_pk_to_EVP_PKEY "const rs256_pk_t *pk" +.Sh DESCRIPTION +RS256 is the name given in the CBOR Object Signing and Encryption +(COSE) RFC to PKCS#1.5 2048-bit RSA with SHA-256. +The COSE RS256 API of +.Em libfido2 +is an auxiliary API with routines to convert between the different +RSA public key types used in +.Em libfido2 +and +.Em OpenSSL . +.Pp +In +.Em libfido2 , +RS256 public keys are abstracted by the +.Vt rs256_pk_t +type. +.Pp +The +.Fn rs256_pk_new +function returns a pointer to a newly allocated, empty +.Vt rs256_pk_t +type. +If memory cannot be allocated, NULL is returned. +.Pp +The +.Fn rs256_pk_free +function releases the memory backing +.Fa *pkp , +where +.Fa *pkp +must have been previously allocated by +.Fn rs256_pk_new . +On return, +.Fa *pkp +is set to NULL. +Either +.Fa pkp +or +.Fa *pkp +may be NULL, in which case +.Fn rs256_pk_free +is a NOP. +.Pp +The +.Fn rs256_pk_from_RSA +function fills +.Fa pk +with the contents of +.Fa rsa . +No references to +.Fa rsa +are kept. +.Pp +The +.Fn rs256_pk_from_ptr +function fills +.Fa pk +with the contents of +.Fa ptr , +where +.Fa ptr +points to +.Fa len +bytes. +No references to +.Fa ptr +are kept. +.Pp +The +.Fn rs256_pk_to_EVP_PKEY +function converts +.Fa pk +to a newly allocated +.Fa EVP_PKEY +type with a reference count of 1. +No internal references to the returned pointer are kept. +If an error occurs, +.Fn rs256_pk_to_EVP_PKEY +returns NULL. +.Sh RETURN VALUES +The +.Fn rs256_pk_from_RSA +and +.Fn rs256_pk_from_ptr +functions return +.Dv FIDO_OK +on success. +On error, a different error code defined in +.In fido/err.h +is returned. +.Sh SEE ALSO +.Xr eddsa_pk_new 3 , +.Xr es256_pk_new 3 , +.Xr fido_assert_verify 3 , +.Xr fido_cred_pubkey_ptr 3 diff --git a/man/style.css b/man/style.css new file mode 100644 index 0000000..8c223fa --- /dev/null +++ b/man/style.css @@ -0,0 +1,24 @@ +* { margin: 0; padding: 0; } + +body { + font-family: monospace; + font-size: 1em; + margin: 2% auto; + max-width: 54em; +} + +ul { margin-left: 1em; } +a { color: #009900; } +.Sh { font-size: 1em; padding-top: 1em; padding-bottom: 1em; } +.foot { padding-top: 1em; } + +table.head, table.foot { width: 100%; } +td.head-rtitle, td.foot-os { text-align: right; } +td.head-vol { text-align: center; } +div.Pp { margin: 1ex 0ex; } +div.Nd, div.Bf, div.Op { display: inline; } +span.Pa, span.Ad { font-style: italic; } +span.Ms { font-weight: bold; } +dl.Bl-diag > dt { font-weight: bold; } +code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn, +code.Cd { font-weight: bold; font-family: inherit; } -- cgit v1.2.3