# Copyright (c) 2013 Yubico AB
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or
# without modification, are permitted provided that the following
# conditions are met:
#
# 1. Redistributions of source code must retain the above copyright
# notice, this list of conditions and the following disclaimer.
# 2. Redistributions in binary form must reproduce the above
# copyright notice, this list of conditions and the following
# disclaimer in the documentation and/or other materials provided
# with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
# COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
# LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
from __future__ import annotations
from .hid import CTAPHID
from .ctap import CtapDevice
from .utils import websafe_encode, websafe_decode, bytes2int, ByteBuffer
from .cose import ES256
from .attestation import FidoU2FAttestation
from enum import IntEnum, unique
from dataclasses import dataclass
import struct
[docs]
@unique
class APDU(IntEnum):
"""APDU response codes."""
OK = 0x9000
USE_NOT_SATISFIED = 0x6985
WRONG_DATA = 0x6A80
[docs]
class ApduError(Exception):
"""An Exception thrown when a response APDU doesn't have an OK (0x9000)
status.
:param code: APDU response code.
:param data: APDU response body.
"""
def __init__(self, code: int, data: bytes = b""):
self.code = code
self.data = data
[docs]
def __repr__(self):
return f"APDU error: 0x{self.code:04X} {len(self.data):d} bytes of data"
[docs]
@dataclass(init=False)
class RegistrationData(bytes):
"""Binary response data for a CTAP1 registration.
:param _: The binary contents of the response data.
:ivar public_key: Binary representation of the credential public key.
:ivar key_handle: Binary key handle of the credential.
:ivar certificate: Attestation certificate of the authenticator, DER
encoded.
:ivar signature: Attestation signature.
"""
public_key: bytes
key_handle: bytes
certificate: bytes
signature: bytes
def __init__(self, _: bytes):
super().__init__()
reader = ByteBuffer(self)
if reader.unpack("B") != 0x05:
raise ValueError("Reserved byte != 0x05")
self.public_key = reader.read(65)
self.key_handle = reader.read(reader.unpack("B"))
cert_buf = reader.read(2) # Tag and first length byte
cert_len = cert_buf[1]
if cert_len > 0x80: # Multi-byte length
n_bytes = cert_len - 0x80
len_bytes = reader.read(n_bytes)
cert_buf += len_bytes
cert_len = bytes2int(len_bytes)
self.certificate = cert_buf + reader.read(cert_len)
self.signature = reader.read()
@property
def b64(self) -> str:
"""Websafe base64 encoded string of the RegistrationData."""
return websafe_encode(self)
[docs]
def verify(self, app_param: bytes, client_param: bytes) -> None:
"""Verify the included signature with regard to the given app and client
params.
:param app_param: SHA256 hash of the app ID used for the request.
:param client_param: SHA256 hash of the ClientData used for the request.
"""
FidoU2FAttestation.verify_signature(
app_param,
client_param,
self.key_handle,
self.public_key,
self.certificate,
self.signature,
)
[docs]
@classmethod
def from_b64(cls, data: str) -> RegistrationData:
"""Parse a RegistrationData from a websafe base64 encoded string.
:param data: Websafe base64 encoded string.
:return: The decoded and parsed RegistrationData.
"""
return cls(websafe_decode(data))
[docs]
@dataclass(init=False)
class SignatureData(bytes):
"""Binary response data for a CTAP1 authentication.
:param _: The binary contents of the response data.
:ivar user_presence: User presence byte.
:ivar counter: Signature counter.
:ivar signature: Cryptographic signature.
"""
user_presence: int
counter: int
signature: bytes
def __init__(self, _: bytes):
super().__init__()
reader = ByteBuffer(self)
self.user_presence = reader.unpack("B")
self.counter = reader.unpack(">I")
self.signature = reader.read()
@property
def b64(self) -> str:
"""str: Websafe base64 encoded string of the SignatureData."""
return websafe_encode(self)
[docs]
def verify(self, app_param: bytes, client_param: bytes, public_key: bytes) -> None:
"""Verify the included signature with regard to the given app and client
params, using the given public key.
:param app_param: SHA256 hash of the app ID used for the request.
:param client_param: SHA256 hash of the ClientData used for the request.
:param public_key: Binary representation of the credential public key.
"""
m = app_param + self[:5] + client_param
ES256.from_ctap1(public_key).verify(m, self.signature)
[docs]
@classmethod
def from_b64(cls, data: str) -> SignatureData:
"""Parse a SignatureData from a websafe base64 encoded string.
:param data: Websafe base64 encoded string.
:return: The decoded and parsed SignatureData.
"""
return cls(websafe_decode(data))
[docs]
class Ctap1:
"""Implementation of the CTAP1 specification.
:param device: A CtapHidDevice handle supporting CTAP1.
"""
[docs]
@unique
class INS(IntEnum):
REGISTER = 0x01
AUTHENTICATE = 0x02
VERSION = 0x03
def __init__(self, device: CtapDevice):
self.device = device
[docs]
def send_apdu(
self, cla: int = 0, ins: int = 0, p1: int = 0, p2: int = 0, data: bytes = b""
) -> bytes:
"""Packs and sends an APDU for use in CTAP1 commands.
This is a low-level method mainly used internally. Avoid calling it
directly if possible, and use the get_version, register, and
authenticate methods if possible instead.
:param cla: The CLA parameter of the request.
:param ins: The INS parameter of the request.
:param p1: The P1 parameter of the request.
:param p2: The P2 parameter of the request.
:param data: The body of the request.
:return: The response APDU data of a successful request.
:raise: ApduError
"""
apdu = struct.pack(">BBBBBH", cla, ins, p1, p2, 0, len(data)) + data + b"\0\0"
response = self.device.call(CTAPHID.MSG, apdu)
status = struct.unpack(">H", response[-2:])[0]
data = response[:-2]
if status != APDU.OK:
raise ApduError(status, data)
return data
[docs]
def get_version(self) -> str:
"""Get the U2F version implemented by the authenticator.
The only version specified is "U2F_V2".
:return: A U2F version string.
"""
return self.send_apdu(ins=Ctap1.INS.VERSION).decode()
[docs]
def register(self, client_param: bytes, app_param: bytes) -> RegistrationData:
"""Register a new U2F credential.
:param client_param: SHA256 hash of the ClientData used for the request.
:param app_param: SHA256 hash of the app ID used for the request.
:return: The registration response from the authenticator.
"""
data = client_param + app_param
response = self.send_apdu(ins=Ctap1.INS.REGISTER, data=data)
return RegistrationData(response)
[docs]
def authenticate(
self,
client_param: bytes,
app_param: bytes,
key_handle: bytes,
check_only: bool = False,
) -> SignatureData:
"""Authenticate a previously registered credential.
:param client_param: SHA256 hash of the ClientData used for the request.
:param app_param: SHA256 hash of the app ID used for the request.
:param key_handle: The binary key handle of the credential.
:param check_only: True to send a "check-only" request, which is used to
determine if a key handle is known.
:return: The authentication response from the authenticator.
"""
data = (
client_param + app_param + struct.pack(">B", len(key_handle)) + key_handle
)
p1 = 0x07 if check_only else 0x03
response = self.send_apdu(ins=Ctap1.INS.AUTHENTICATE, p1=p1, data=data)
return SignatureData(response)