mirror of
https://github.com/RIOT-OS/RIOT.git
synced 2024-12-29 04:50:03 +01:00
218 lines
9.9 KiB
Plaintext
218 lines
9.9 KiB
Plaintext
/*
|
|
* 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.
|
|
*
|
|
* 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).
|
|
*
|
|
* 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.
|
|
* * 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.
|
|
*/ |