fido2.ctap2.pin

Classes

PinProtocol	Helper class that provides a standard way to create an ABC using
PinProtocolV1	Implementation of the CTAP2 PIN/UV protocol v1.
PinProtocolV2	Implementation of the CTAP2 PIN/UV protocol v2.
ClientPin	Implementation of the CTAP2 Client PIN API.

Module Contents

class fido2.ctap2.pin.PinProtocol

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

VERSION: ClassVar[int]

abstractmethod encapsulate(peer_cose_key)

Generates an encapsulation of the public key. Returns the message to transmit and the shared secret.

Parameters:

peer_cose_key (fido2.cose.CoseKey)

Return type:

tuple[Mapping[int, Any], bytes]

abstractmethod encrypt(key, plaintext)

Encrypts data

Parameters:

• key (bytes)

• plaintext (bytes)

Return type:

bytes

abstractmethod decrypt(key, ciphertext)

Decrypts encrypted data

Parameters:

• key (bytes)

• ciphertext (bytes)

Return type:

bytes

abstractmethod authenticate(key, message)

Computes a MAC of the given message.

Parameters:

• key (bytes)

• message (bytes)

Return type:

bytes

abstractmethod validate_token(token)

Validates that a token is well-formed. Returns the token, or if invalid, raises a ValueError.

Parameters:

token (bytes)

Return type:

bytes

class fido2.ctap2.pin.PinProtocolV1

Bases: PinProtocol

Implementation of the CTAP2 PIN/UV protocol v1.

Parameters:

ctap – An instance of a CTAP2 object.

Variables:

• VERSION – The version number of the PIV/UV protocol.

• IV – An all-zero IV used for some cryptographic operations.

VERSION = 1

IV = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00'

kdf(z)

Parameters:

z (bytes)

Return type:

bytes

encapsulate(peer_cose_key)

Generates an encapsulation of the public key. Returns the message to transmit and the shared secret.

encrypt(key, plaintext)

Encrypts data

decrypt(key, ciphertext)

Decrypts encrypted data

authenticate(key, message)

Computes a MAC of the given message.

validate_token(token)

Validates that a token is well-formed. Returns the token, or if invalid, raises a ValueError.

class fido2.ctap2.pin.PinProtocolV2

Bases: PinProtocolV1

Implementation of the CTAP2 PIN/UV protocol v2.

Parameters:

ctap – An instance of a CTAP2 object.

Variables:

• VERSION – The version number of the PIV/UV protocol.

• IV – An all-zero IV used for some cryptographic operations.

VERSION = 2

HKDF_SALT = b'\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x0...

HKDF_INFO_HMAC = b'CTAP2 HMAC key'

HKDF_INFO_AES = b'CTAP2 AES key'

kdf(z)

encrypt(key, plaintext)

Encrypts data

decrypt(key, ciphertext)

Decrypts encrypted data

authenticate(key, message)

Computes a MAC of the given message.

validate_token(token)

Validates that a token is well-formed. Returns the token, or if invalid, raises a ValueError.

class fido2.ctap2.pin.ClientPin(ctap, protocol=None)

Implementation of the CTAP2 Client PIN API.

Parameters:

• ctap (fido2.ctap2.base.Ctap2) – An instance of a CTAP2 object.

• protocol (PinProtocol | None) – An optional instance of a PinUvAuthProtocol object. If None is provided then the latest protocol supported by both library and Authenticator will be used.

PROTOCOLS

class CMD

Bases: enum.IntEnum

Enum where members are also (and must be) ints

GET_PIN_RETRIES = 1

GET_KEY_AGREEMENT = 2

SET_PIN = 3

CHANGE_PIN = 4

GET_TOKEN_USING_PIN_LEGACY = 5

GET_TOKEN_USING_UV = 6

GET_UV_RETRIES = 7

GET_TOKEN_USING_PIN = 9

class RESULT

Bases: enum.IntEnum

Enum where members are also (and must be) ints

KEY_AGREEMENT = 1

PIN_UV_TOKEN = 2

PIN_RETRIES = 3

POWER_CYCLE_STATE = 4

UV_RETRIES = 5

class PERMISSION

Bases: enum.IntFlag

Support for integer-based Flags

MAKE_CREDENTIAL = 1

GET_ASSERTION = 2

CREDENTIAL_MGMT = 4

BIO_ENROLL = 8

LARGE_BLOB_WRITE = 16

AUTHENTICATOR_CFG = 32

PERSISTENT_CREDENTIAL_MGMT = 64

static is_supported(info)

Checks if ClientPin functionality is supported.

Note that the ClientPin function is still usable without support for client PIN functionality, as UV token may still be supported.

static is_token_supported(info)

Checks if pinUvAuthToken is supported.

ctap

get_pin_token(pin, permissions=None, permissions_rpid=None)

Get a PIN/UV token from the authenticator using PIN.

Parameters:

• pin (str) – The PIN of the authenticator.

• permissions (ClientPin | None) – The permissions to associate with the token.

• permissions_rpid (str | None) – The permissions RPID to associate with the token.

Returns:

A PIN/UV token.

Return type:

bytes

get_uv_token(permissions=None, permissions_rpid=None, event=None, on_keepalive=None)

Get a PIN/UV token from the authenticator using built-in UV.

Parameters:

• permissions (ClientPin | None) – The permissions to associate with the token.

• permissions_rpid (str | None) – The permissions RPID to associate with the token.

• event (threading.Event | None) – An optional threading.Event which can be used to cancel the invocation.

• on_keepalive (Callable[[int], None] | None) – An optional callback to handle keep-alive messages from the authenticator. The function is only called once for consecutive keep-alive messages with the same status.

Returns:

A PIN/UV token.

Return type:

bytes

get_pin_retries()

Get the number of PIN retries remaining.

Returns:

A tuple of the number of PIN attempts remaining until the

Return type:

tuple[int, int | None]

authenticator is locked, and the power cycle state, if available.

get_uv_retries()

Get the number of UV retries remaining.

Returns:

A tuple of the number of UV attempts remaining until the

Return type:

int

authenticator is locked, and the power cycle state, if available.

set_pin(pin)

Set the PIN of the autenticator.

This only works when no PIN is set. To change the PIN when set, use change_pin.

Parameters:

pin (str) – A PIN to set.

Return type:

None

change_pin(old_pin, new_pin)

Change the PIN of the authenticator.

This only works when a PIN is already set. If no PIN is set, use set_pin.

Parameters:

• old_pin (str) – The currently set PIN.

• new_pin (str) – The new PIN to set.

Return type:

None