FIDO2 CTAP USB_HID transport binding. More...

Detailed Description

FIDO2 CTAP USB_HID transport binding.

Files
file	ctap_hid.h
	Definition for CTAPHID helper functions.

Data Structures
struct	ctap_hid_init_pkt_t
	CTAP_HID initialization packet struct. More...

struct	ctap_hid_cont_pkt_t
	CTAP_HID continuation packet struct. More...

struct	ctap_hid_pkt_t
	CTAP_HID packet struct. More...

struct	ctap_hid_init_resp_t
	CTAP_HID initialization response struct. More...

struct	ctap_hid_cid_t
	CTAP_HID channel identifier struct. More...

Macros
#define	CTAP_HID_PROTOCOL_VERSION 0x02
	CTAP_HID protocol version.

#define	CTAP_HID_INIT_NONCE_SIZE 8
	CTAP_HID size of nonce for init request.

#define	CTAP_HID_TRANSACTION_TIMEOUT_MS (500)
	CTAP_HID transaction timeout in microseconds.

#define	CTAP_HID_BUFFER_SIZE 7609
	CTAP_HID max message payload size.

#define	CTAP_HID_CIDS_MAX 0x08
	CTAP_HID max number of channels.

#define	CTAP_HID_WINK_DELAY 400
	CTAP_HID animation delay in milliseconds for wink command.

#define	CTAP_HID_BROADCAST_CID 0xffffffff
	CTAP_HID broadcast channel identifier.

Functions
void	fido2_ctap_transport_hid_init (event_queue_t *queue)
	Initialize CTAPHID.

void	fido2_ctap_transport_hid_handle_packet (void *pkt_raw)
	Handle CTAP_HID packet.

void	fido2_ctap_transport_hid_check_timeouts (void)
	Check logical channels for timeouts.

bool	fido2_ctap_transport_hid_should_cancel (void)
	Check if CTAPHID layer has received CANCEL command.

CTAP_HID packet type payload sizes
#define	CTAP_HID_INIT_PAYLOAD_SIZE (CONFIG_USBUS_HID_INTERRUPT_EP_SIZE - 7)
	endpoint size - init packet metadata

#define	CTAP_HID_CONT_PAYLOAD_SIZE (CONFIG_USBUS_HID_INTERRUPT_EP_SIZE - 5)
	endpoint size - cont packet metadata

CTAP_HID packet type identifiers
#define	CTAP_HID_INIT_PACKET 0x80
	initialization packet identifier

#define	CTAP_HID_CONT_PACKET 0x00
	continuation packet identifier

CTAP_HID commands
#define	CTAP_HID_COMMAND_PING (0x01 \| CTAP_HID_INIT_PACKET)
	CTAPHID_PING command.

#define	CTAP_HID_COMMAND_MSG (0x03 \| CTAP_HID_INIT_PACKET)
	CTAPHID_MSG command.

#define	CTAP_HID_COMMAND_LOCK (0x04 \| CTAP_HID_INIT_PACKET)
	CTAPHID_LOCK command.

#define	CTAP_HID_COMMAND_INIT (0x06 \| CTAP_HID_INIT_PACKET)
	CTAPHID_INIT command.

#define	CTAP_HID_COMMAND_WINK (0x08 \| CTAP_HID_INIT_PACKET)
	CTAPHID_WINK command.

#define	CTAP_HID_COMMAND_CBOR (0x10 \| CTAP_HID_INIT_PACKET)
	CTAPHID_CBOR command.

#define	CTAP_HID_COMMAND_CANCEL (0x11 \| CTAP_HID_INIT_PACKET)
	CTAPHID_CANCEL command.

#define	CTAP_HID_COMMAND_KEEPALIVE (0x3b \| CTAP_HID_INIT_PACKET)
	CTAPHID_KEEPALIVE command.

#define	CTAP_HID_COMMAND_ERROR (0x3f \| CTAP_HID_INIT_PACKET)
	CTAPHID_ERROR command.

CTAP_HID capability flags
#define	CTAP_HID_CAPABILITY_WINK 0x01
	If set, authenticator implements CTAPHID_WINK function.

#define	CTAP_HID_CAPABILITY_CBOR 0x04
	If set, authenticator implements CTAPHID_CBOR function.

#define	CTAP_HID_CAPABILITY_NMSG 0x08
	If set, authenticator DOES NOT implement CTAPHID_MSG function (CTAP1 / U2F)

CTAP_HID error codes
#define	CTAP_HID_OK 0x00
	Success.

#define	CTAP_HID_ERR_INVALID_CMD 0x01
	The command in the request is invalid.

#define	CTAP_HID_ERR_INVALID_PAR 0x02
	The parameter(s) in the request is invalid.

#define	CTAP_HID_ERR_INVALID_LEN 0x03
	The length field (BCNT) is invalid for the request.

#define	CTAP_HID_ERR_INVALID_SEQ 0x04
	The sequence does not match expected value.

#define	CTAP_HID_ERR_MSG_TIMEOUT 0x05
	The message has timed out.

#define	CTAP_HID_ERR_CHANNEL_BUSY 0x06
	The device is busy for the requesting channel.

#define	CTAP_HID_ERR_LOCK_REQUIRED 0x0a
	Command requires channel lock.

#define	CTAP_HID_ERR_INVALID_CHANNEL 0x0b
	CID is not valid.

#define	CTAP_HID_ERR_OTHER 0x7f
	Unspecified error.

CTAP_HID status codes
#define	CTAP_HID_STATUS_PROCESSING 0x01
	processing status code

#define	CTAP_HID_STATUS_UPNEEDED 0x02
	user presence needed status code

CTAP_HID buffer status
#define	CTAP_HID_BUFFER_STATUS_BUFFERING 0x00
	packets are being buffered

#define	CTAP_HID_BUFFER_STATUS_DONE 0x01
	packet processing done

#define	CTAP_HID_BUFFER_STATUS_ERROR 0x02
	error occurred processing packets

Macro Definition Documentation

◆ CTAP_HID_BROADCAST_CID

#define CTAP_HID_BROADCAST_CID 0xffffffff

CTAP_HID broadcast channel identifier.

Definition at line 144 of file ctap_hid.h.

◆ CTAP_HID_BUFFER_SIZE

#define CTAP_HID_BUFFER_SIZE 7609

CTAP_HID max message payload size.

CTAP specification (version 20190130) section 8.2.4.

Definition at line 75 of file ctap_hid.h.

◆ CTAP_HID_BUFFER_STATUS_BUFFERING

#define CTAP_HID_BUFFER_STATUS_BUFFERING 0x00

packets are being buffered

Definition at line 151 of file ctap_hid.h.

◆ CTAP_HID_BUFFER_STATUS_DONE

#define CTAP_HID_BUFFER_STATUS_DONE 0x01

packet processing done

Definition at line 152 of file ctap_hid.h.

◆ CTAP_HID_BUFFER_STATUS_ERROR

#define CTAP_HID_BUFFER_STATUS_ERROR 0x02

error occurred processing packets

Definition at line 153 of file ctap_hid.h.

◆ CTAP_HID_CAPABILITY_CBOR

#define CTAP_HID_CAPABILITY_CBOR 0x04

If set, authenticator implements CTAPHID_CBOR function.

Definition at line 99 of file ctap_hid.h.

◆ CTAP_HID_CAPABILITY_NMSG

#define CTAP_HID_CAPABILITY_NMSG 0x08

If set, authenticator DOES NOT implement CTAPHID_MSG function (CTAP1 / U2F)

Definition at line 100 of file ctap_hid.h.

◆ CTAP_HID_CAPABILITY_WINK

#define CTAP_HID_CAPABILITY_WINK 0x01

If set, authenticator implements CTAPHID_WINK function.

Definition at line 98 of file ctap_hid.h.

◆ CTAP_HID_CIDS_MAX

#define CTAP_HID_CIDS_MAX 0x08

CTAP_HID max number of channels.

Definition at line 133 of file ctap_hid.h.

◆ CTAP_HID_COMMAND_CANCEL

#define CTAP_HID_COMMAND_CANCEL (0x11 | CTAP_HID_INIT_PACKET)

CTAPHID_CANCEL command.

Definition at line 88 of file ctap_hid.h.

◆ CTAP_HID_COMMAND_CBOR

#define CTAP_HID_COMMAND_CBOR (0x10 | CTAP_HID_INIT_PACKET)

CTAPHID_CBOR command.

Definition at line 87 of file ctap_hid.h.

◆ CTAP_HID_COMMAND_ERROR

#define CTAP_HID_COMMAND_ERROR (0x3f | CTAP_HID_INIT_PACKET)

CTAPHID_ERROR command.

Definition at line 90 of file ctap_hid.h.

◆ CTAP_HID_COMMAND_INIT

#define CTAP_HID_COMMAND_INIT (0x06 | CTAP_HID_INIT_PACKET)

CTAPHID_INIT command.

Definition at line 85 of file ctap_hid.h.

◆ CTAP_HID_COMMAND_KEEPALIVE

#define CTAP_HID_COMMAND_KEEPALIVE (0x3b | CTAP_HID_INIT_PACKET)

CTAPHID_KEEPALIVE command.

Definition at line 89 of file ctap_hid.h.

◆ CTAP_HID_COMMAND_LOCK

#define CTAP_HID_COMMAND_LOCK (0x04 | CTAP_HID_INIT_PACKET)

CTAPHID_LOCK command.

Definition at line 84 of file ctap_hid.h.

◆ CTAP_HID_COMMAND_MSG

#define CTAP_HID_COMMAND_MSG (0x03 | CTAP_HID_INIT_PACKET)

CTAPHID_MSG command.

Definition at line 83 of file ctap_hid.h.

◆ CTAP_HID_COMMAND_PING

#define CTAP_HID_COMMAND_PING (0x01 | CTAP_HID_INIT_PACKET)

CTAPHID_PING command.

Definition at line 82 of file ctap_hid.h.

◆ CTAP_HID_COMMAND_WINK

#define CTAP_HID_COMMAND_WINK (0x08 | CTAP_HID_INIT_PACKET)

CTAPHID_WINK command.

Definition at line 86 of file ctap_hid.h.

◆ CTAP_HID_CONT_PACKET

#define CTAP_HID_CONT_PACKET 0x00

continuation packet identifier

Definition at line 53 of file ctap_hid.h.

◆ CTAP_HID_CONT_PAYLOAD_SIZE

#define CTAP_HID_CONT_PAYLOAD_SIZE (CONFIG_USBUS_HID_INTERRUPT_EP_SIZE - 5)

endpoint size - cont packet metadata

Definition at line 39 of file ctap_hid.h.

◆ CTAP_HID_ERR_CHANNEL_BUSY

#define CTAP_HID_ERR_CHANNEL_BUSY 0x06

The device is busy for the requesting channel.

Definition at line 114 of file ctap_hid.h.

◆ CTAP_HID_ERR_INVALID_CHANNEL

#define CTAP_HID_ERR_INVALID_CHANNEL 0x0b

CID is not valid.

Definition at line 116 of file ctap_hid.h.

◆ CTAP_HID_ERR_INVALID_CMD

#define CTAP_HID_ERR_INVALID_CMD 0x01

The command in the request is invalid.

Definition at line 109 of file ctap_hid.h.

◆ CTAP_HID_ERR_INVALID_LEN

#define CTAP_HID_ERR_INVALID_LEN 0x03

The length field (BCNT) is invalid for the request.

Definition at line 111 of file ctap_hid.h.

◆ CTAP_HID_ERR_INVALID_PAR

#define CTAP_HID_ERR_INVALID_PAR 0x02

The parameter(s) in the request is invalid.

Definition at line 110 of file ctap_hid.h.

◆ CTAP_HID_ERR_INVALID_SEQ

#define CTAP_HID_ERR_INVALID_SEQ 0x04

The sequence does not match expected value.

Definition at line 112 of file ctap_hid.h.

◆ CTAP_HID_ERR_LOCK_REQUIRED

#define CTAP_HID_ERR_LOCK_REQUIRED 0x0a

Command requires channel lock.

Definition at line 115 of file ctap_hid.h.

◆ CTAP_HID_ERR_MSG_TIMEOUT

#define CTAP_HID_ERR_MSG_TIMEOUT 0x05

The message has timed out.

Definition at line 113 of file ctap_hid.h.

◆ CTAP_HID_ERR_OTHER

#define CTAP_HID_ERR_OTHER 0x7f

Unspecified error.

Definition at line 117 of file ctap_hid.h.

◆ CTAP_HID_INIT_NONCE_SIZE

#define CTAP_HID_INIT_NONCE_SIZE 8

CTAP_HID size of nonce for init request.

Definition at line 59 of file ctap_hid.h.

◆ CTAP_HID_INIT_PACKET

#define CTAP_HID_INIT_PACKET 0x80

initialization packet identifier

Definition at line 52 of file ctap_hid.h.

◆ CTAP_HID_INIT_PAYLOAD_SIZE

#define CTAP_HID_INIT_PAYLOAD_SIZE (CONFIG_USBUS_HID_INTERRUPT_EP_SIZE - 7)

endpoint size - init packet metadata

Definition at line 38 of file ctap_hid.h.

◆ CTAP_HID_OK

#define CTAP_HID_OK 0x00

Success.

Definition at line 108 of file ctap_hid.h.

◆ CTAP_HID_PROTOCOL_VERSION

#define CTAP_HID_PROTOCOL_VERSION 0x02

CTAP_HID protocol version.

Definition at line 45 of file ctap_hid.h.

◆ CTAP_HID_STATUS_PROCESSING

#define CTAP_HID_STATUS_PROCESSING 0x01

processing status code

Definition at line 125 of file ctap_hid.h.

◆ CTAP_HID_STATUS_UPNEEDED

#define CTAP_HID_STATUS_UPNEEDED 0x02

user presence needed status code

Definition at line 126 of file ctap_hid.h.

◆ CTAP_HID_TRANSACTION_TIMEOUT_MS

#define CTAP_HID_TRANSACTION_TIMEOUT_MS (500)

CTAP_HID transaction timeout in microseconds.

Definition at line 67 of file ctap_hid.h.

◆ CTAP_HID_WINK_DELAY

#define CTAP_HID_WINK_DELAY 400

CTAP_HID animation delay in milliseconds for wink command.

Definition at line 138 of file ctap_hid.h.

Function Documentation

◆ fido2_ctap_transport_hid_check_timeouts()

void fido2_ctap_transport_hid_check_timeouts ( void )

Check logical channels for timeouts.

This function is used to prevent one channel from locking the authenticator. E.g. if a device starts a transaction that does not fit in one packet and sends a CTAPHID initialization packet but not continuation packet the authenticator will keep waiting. This function will prevent this by cancelling a transaction if it takes longer than

CTAP specification (version 20190130) section 5.6

CTAP_HID_TRANSACTION_TIMEOUT_MS

◆ fido2_ctap_transport_hid_handle_packet()

void fido2_ctap_transport_hid_handle_packet ( void * pkt_raw )

Handle CTAP_HID packet.

Parameters

[in] pkt_raw raw CTAP_HID packet

◆ fido2_ctap_transport_hid_init()

void fido2_ctap_transport_hid_init ( event_queue_t * queue )

Initialize CTAPHID.