RIOT/sys/fido2/doc.txt

/*
 * Copyright (C) 2021 Freie Universität Berlin
 *
 * This file is subject to the terms and conditions of the GNU Lesser
 * General Public License v2.1. See the file LICENSE in the top level
 * directory for more details.
 */

/**
 * @defgroup    fido2 FIDO2 - Fast Identity Online 2
 * @ingroup     sys
 * @brief       Description of the FIDO2 CTAP implementation in RIOT
 * @author      Nils Ollrogge <nils.ollrogge@fu-berlin.de>
 *
 * @warning This feature is experimental!
 *          This API is experimental and in an early state - expect changes.
 *
 * @warning The FIDO2 implementation currently stores private keys in plain text inside flash memory.
 *
 * @warning This implementation persists FIDO CTAP data across reboots and when unpowered;
 *          any firmware update loses the data because it will be overwritten. This applies both to firmware updates through
 *          bootloaders and to firmware updates through external programmers.
 *
 * FIDO2 is an authentication standard that seeks to solve the password problem
 * by enabling passwordless authentication. Instead of using passwords to
 * authenticate to web services, FIDO2 enables users to use common devices
 * (authenticators) to create cryptographic credentials which are then used
 * for authentication. FIDO2 consists of the [W3C Web Authentication
 * specification (WebAuthn)](https://www.w3.org/TR/2019/REC-webauthn-1-20190304/)
 * and the [Client to Authenticator Protocol (CTAP)](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html).
 *
 * **This code implements the FIDO2 CTAP protocol.**
 *
 * ### General
 *
 * Following is an overview of the entities of this implementation and their relationships:
 *
 *
 *                     +-----------+  +-----------+   +-----------+   +-----------+
 *                     |           |  |           |   |           |   |           |
 *                     | ctap_cbor |  |ctap_crypto|   | ctap_mem  |   |ctap_utils |
 *                     |           |  |           |   |           |   |           |
 *                     +-----------+  +-----------+   +-----------+   +-----|-----+
 *                           |             |               |                |
 *                           |             |               |                |
 *                           |         +---------------------------+        |
 *                           |         |                           |        |
 *                           |---------|           ctap            |--------|
 *                                     |                           |
 *                                     +---------------------------+
 *                                                   |
 *                                     +-------------|-------------+
 *                                     |                           |
 *                                     |       ctap_transport      |
 *                                     |                           |
 *                                     +---------------------------+
 *                                           |
 *                                           |
 *                                     +-----------+
 *                                     |           |
 *                                     | ctap_hid  |
 *                                     |           |
 *                                     +-----------+
 *
 *
 *
 * **ctap_hid**
 *
 * USB Human Interface Device (USB HID) transport binding for CTAP (CTAPHID).
 *
 * Initializes the USBUS HID interface.
 *
 * Communicates with the USBUS USB HID interface through the USBUS HID IO interface.
 *
 * **ctap_transport**
 *
 * Initializes CTAP layer.
 *
 * Initializes CTAP event queue.
 *
 * Manages CTAP transport bindings (currently only CTAPHID).
 *
 * **ctap**
 *
 * Contains the main CTAP logic.
 *
 * Makes use of helpers for flash access, cryptographic operations and CBOR operations.
 *
 * **ctap_cbor**
 *
 * Helper containing functionality to parse and encode CBOR messages. Uses the [tinyCBOR](https://doc.riot-os.org/group__pkg__tinycbor.html) pkg.
 *
 * **ctap_crypto**
 *
 * Helper containing functionality for cryptographic operations.
 *
 * Abstraction for cryptographic operations (SHA256, HMAC-SHA-256, AES CCM).
 *
 * @note This abstraction exposes error return values which are currently not implemented in all cases by the RIOT crypto API.
 *
 * Abstraction for Elliptic curve cryptography (ECC) operations. Uses the [micro-ecc](https://api.riot-os.org/group__pkg__micro__ecc.html) pkg.
 *
 * Parsing of cryptographic signatures into ASN.1 DER format. Uses the [tiny-asn1](http://doc.riot-os.org/group__pkg__tiny-asn1.html) pkg.
 *
 * **ctap_mem**
 *
 * Abstraction for flash operations. Uses the RIOT [Flashpage MTD driver](http://api.riot-os.org/group__drivers__mtd__flashpage.html).
 *
 * Flash memory is reserved at build time using the `FLASH_WRITABLE_INIT` macro. The amount of flashpages reserved can be configured as `FIDO2_CTAP_NUM_FLASHPAGES` in KConfig. The implementation needs at least 1 flashpage to store state information and 1 flashpage to store credentials also called resident keys (rks). Therefore, the minimum amount of flashpages needed is 2. State information is stored on the first flashpage, credentials (rks) on the following flashpages.
 *
 * Adds additional functionality to speedup flash accesses (e.g. by checking if a flash page is erased to avoid unnecessary erasures of flash pages).
 *
 * **ctap_utils**
 *
 * Abstraction for GPIO functionality and LED animations.
 *
 * ### Implemented features
 * **FIDO2 CTAP methods**
 *
 * All methods defined in the FIDO2 CTAP specification are implemented. Specifically
 * these are:
 *      * MakeCredential
 *      * GetAssertion
 *      * GetNextAssertion
 *      * GetInfo
 *      * ClientPIN
 *      * Reset
 *
 * For information about the FIDO2 CTAP methods refer to the [CTAP specification](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#authenticator-api).
 *
 * **Transport bindings**
 *
 * The USB Human Interface Device (USB HID) transport binding is fully implemented.
 *
 * For more information about the available transport bindings refer to the [CTAP specification](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#transport-specific-bindings).
 *
 * **Credentials**
 *
 * Both types of credentials are supported. Resident and non resident.
 *
 *  * Resident Credentials
 *      * Resident credentials are credentials stored on the authenticator.
 *      * They are also called resident key (rk) credentials due to the key material
 *        being stored on the device.
 *      * This implementation stores resident keys in flash memory.
 *      @warning As of now the credentials (containing a private key) are stored
 *       in plain text inside flash memory
 *
 *  * Non-resident credentials
 *      * Non-resident credentials are credentials that are stored by the relying
 *        party in encrypted form.
 *      * To encrypt the credentials, this implementation uses the RIOT [AES-CCM 128
 *        CCM implementation](https://api.riot-os.org/ccm_8h.html).
 *
 * For more information about the two types of credential refer to the [WebAuthn specification](https://www.w3.org/TR/2019/REC-webauthn-1-20190304/#sctn-credential-storage-modality)
 *
 * **Attestation types**
 *
 * Currently only self attestation is supported.
 *
 * For more information about available attestation types refer to the [WebAuthn specification](https://www.w3.org/TR/2019/REC-webauthn-1-20190304/#sctn-attestation-types).
 *
 * ### Unimplemented features
 *
 * **Backward compatibility with FIDO1**
 *
 * For more information about the backward compatibility of FIDO2 to FIDO1
 * refer to the [CTAP specification](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#u2f-interoperability).
 *
 * **Support of further attestation types**
 *
 * Specifically these are:
 *  * Basic Attestation
 *  * Attestation Certificate Authority
 *  * Elliptic Curve based Direct Anonymous Attestation
 *
 * For more information about available attestation types refer to the [WebAuthn specification](https://www.w3.org/TR/2019/REC-webauthn-1-20190304/#sctn-attestation-types).
 *
 * **Support of further transport bindings**
 *
 * Specifically these are:
 *  * Near Field Communication (NFC)
 *  * Bluetooth Low Energy (BLE)
 *
 * For information about the available transport bindings refer to the
 * [CTAP specification](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#transport-specific-bindings).
 *
 * **Extensions**
 *
 * For information about CTAP extensions refer to the [CTAP specification](https://fidoalliance.org/specs/fido-v2.0-ps-20190130/fido-client-to-authenticator-protocol-v2.0-ps-20190130.html#sctn-defined-extensions)
 *
 * **CTAP 2.1 support**
 *
 * None of the additions from the [CTAP 2.1 specification](https://fidoalliance.org/specs/fido-v2.1-ps-20210615/fido-client-to-authenticator-protocol-v2.1-ps-20210615.html)  are implemented.
 *
 * ### Testing
 *
 * Testing is done with the help of the fido2-tests package based on the [solokeys fido2-tests](https://github.com/solokeys/fido2-tests).
 *
 * For for more information about testing the FIDO2 CTAP implementation refer to the README of the test application (`/tests/sys/fido2_ctap`).
 *
 * **Todo**
 *
 * * The expected return codes of some tests were changed due to different opinions of how to interpret the CTAP2 specification. Refer to the [issue](https://github.com/solokeys/fido2-tests/issues/55) for more information. As of writing this the issue is still open.
 *
 * ### Configuration
 *
 * There are two CFLAGS which can be used to change the behavior of the FIDO2 CTAP implementation:
 *
 *  * **FIDO2_CTAP_DISABLE_UP**: Disables the user presence test. User presence will always be set to true.
 * This is helpful when running the fido2-tests as one doesn't have to click the button many times, as well as other use cases
 * where no user presence test is wanted.
 *  * **FIDO2_CTAP_DISABLE_LED**: Disables LED animations which are used to indicate that user action is needed.
 *
 * The CFLAGS can either be set in the Makefile or configured via KConfig.
 *
 * ### Future work
 *
 * Future improvements / extensions to the FIDO2 CTAP implementation that should be implemented are:
 *
 * * Usage of secure elements if available to safely store private keys of FIDO2 credentials.
 * * Usage of an extra cryptographic processor (e.g. [ARM CryptoCell](https://infocenter.nordicsemi.com/index.jsp?topic=%2Fps_nrf9160%2Fcryptocell.html)) to improve efficiency and drop dependency for ECC cryptography.
 * * Support of further attestation types.
 * * Support of further CTAP transport bindings.
 * * Support of CTAP 2.1.
 */