FIDO2 - Fast Identity Online 2

Description of the FIDO2 CTAP implementation in RIOT. More...

Detailed Description

Description of the FIDO2 CTAP implementation in RIOT.

Author
Nils Ollrogge nils..nosp@m.ollr.nosp@m.ogge@.nosp@m.fu-b.nosp@m.erlin.nosp@m..de
Warning
This feature is experimental! This API is experimental and in an early state - expect changes.
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) and the Client to Authenticator Protocol (CTAP).

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 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 pkg.

Parsing of cryptographic signatures into ASN.1 DER format. Uses the tiny-asn1 pkg.

ctap_mem

Abstraction for flash operations. Uses the RIOT Flashpage MTD driver.

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:

For information about the FIDO2 CTAP methods refer to the CTAP specification.

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.

Credentials

Both types of credentials are supported. Resident and non resident.

For more information about the two types of credential refer to the WebAuthn specification

Attestation types

Currently only self attestation is supported.

For more information about available attestation types refer to the WebAuthn specification.

Unimplemented features

Backward compatibility with FIDO1

For more information about the backward compatibility of FIDO2 to FIDO1 refer to the CTAP specification.

Support of further attestation types

Specifically these are:

For more information about available attestation types refer to the WebAuthn specification.

Support of further transport bindings

Specifically these are:

For information about the available transport bindings refer to the CTAP specification.

Extensions

For information about CTAP extensions refer to the CTAP specification

CTAP 2.1 support

None of the additions from the CTAP 2.1 specification are implemented.

Testing

Testing is done with the help of the fido2-tests package based on the 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

Configuration

There are two CFLAGS which can be used to change the behavior of the FIDO2 CTAP implementation:

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:

Modules

 CTAP
 FIDO2 CTAP.