Skip to main content

CTAP (client-to-authenticator-protocol) device backed by python's keyring library

Project description

PyPi version Python version Code style: Black Read the docs CI workflow

This library provides an implementation of a virtual CTAP2 (client-to-authenticator-protocol) device, which uses the keyring library as its backend.

One may use this implementation as a reference for CTAP2-compatible devices, or to use ones host machine as an authenticator, rather than using an external one.

A common use-case would be to use this library as an authenticator for a webauthn flow, storing keys and retrieving assertions on a machine’s configured keyring.

Supported features are:
  • The make-credential, get-assertion, get-next-assertion and get-info CTAP2 flows

  • The management of keys using the following COSE algorithms: RS1, RS256, PS256, EC256, EdDSA

  • The use of any available keyring as a backend for the created key-pairs (e.g. WinCred, Keychain, …)

  • User presence & verification on OSX and Windows, via Touch-ID and Windows-Hello

  • Storing keys in a secure manner, with no PII (personal-identifying-information) attached to them


Installation

Run the following (on a darwin machine):

$ pip install ctap-keyring-device

Using This Library

Make Credential Flow

from fido2.webauthn import PublicKeyCredentialCreationOptions, PublicKeyCredentialType, PublicKeyCredentialParameters
from ctap_keyring_device.ctap_keyring_device import CtapKeyringDevice
from fido2.client import Fido2Client
from fido2 import cose
import base64

device = CtapKeyringDevice.list_devices()[0]
origin = 'https://rp.pasten.com'
client = Fido2Client(device, origin)

rp = {'id': 'pasten.com', 'name': origin[8:], 'icon': '...'}
user = {'id': 'danny@pasten.io', 'name': 'Danny Shemesh', 'icon': '...', 'displayName': 'Danny Pastanny'}
challenge = base64.b64encode(b'my-challenge')
timeout_ms = 30_000

pub_key_cred_params = [PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, cose.ES256.ALGORITHM)]
options = PublicKeyCredentialCreationOptions(rp, user, challenge, pub_key_cred_params, timeout=timeout_ms)

attestation, client_data = client.make_credential(options)

Get Assertion Flow

from fido2.webauthn import PublicKeyCredentialRequestOptions, PublicKeyCredentialType, \
    PublicKeyCredentialParameters, PublicKeyCredentialDescriptor, UserVerificationRequirement
from ctap_keyring_device.ctap_keyring_device import CtapKeyringDevice
from fido2.client import Fido2Client
from fido2 import cose
import base64

device = CtapKeyringDevice.list_devices()[0]
origin = 'https://rp.pasten.com'
client = Fido2Client(device, origin)

challenge = base64.b64encode(b'my-challenge')
rp = {'id': 'pasten.com', 'name': origin[8:], 'icon': '...'}
credential_id = b'.......'
allow_list = [
    PublicKeyCredentialDescriptor(PublicKeyCredentialType.PUBLIC_KEY, credential_id)
]
timeout_ms = 30_000

pub_key_cred_params = [PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, cose.ES256.ALGORITHM)]
options = PublicKeyCredentialRequestOptions(challenge=challenge, rp_id=rp['id'],
                                            allow_credentials=allow_list, timeout=timeout_ms,
                                            user_verification=UserVerificationRequirement.PREFERRED)
assertions, client_data = client.get_assertion(options)

See examples in ctap-keyring-device/tests.


Security Considerations

Using this library will help one utilize their machine’s keyring as a CTAP2-compliant FIDO authenticator.

Credentials are stores on the configured keyring, which defaults to a sensible implementation, per the platform the code is running on (e.g. keychain on OSX, WinCred on Windows, …)

The make-credentials flow will create a key-pair for signing, using the requested COSE algorithm.

Private keys are encrypted with a random UUID4 as the passphrase, using hazmat’s BestAvailableEncryption.

Credential IDs comprise of <UUID5-of-user-id>_<key-passphrase>, and are sent back to the requesting client; it is assumed that the credential ID is kept in a remote machine, and is always provided in the allow-list of a ctap get-assertion request.

The above allows us to generate and store our keys in a manner that renders key exposure as less risky, due to the key being encrypted; and not storing the user-id directly, making it harder to use the key, even if decrypted.

On top of the mentioned safeguards, one may request the UV (user-verification) option, in order to trigger a 2nd factor before returning an assertion; Touch-ID / Password prompt is used on OSX, and Windows-Hello on Windows.


Making Releases

A CI/CD pipeline is setup on github - once a PR is merged to master, a pre-release will be automatically deployed to github; When a release is tagged, it will be automatically deployed to pypi.


Running Tests

To run the tests locally, install and invoke tox.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ctap-keyring-device-1.0.1.tar.gz (147.5 kB view details)

Uploaded Source

Built Distribution

ctap_keyring_device-1.0.1-py2.py3-none-any.whl (17.0 kB view details)

Uploaded Python 2 Python 3

File details

Details for the file ctap-keyring-device-1.0.1.tar.gz.

File metadata

  • Download URL: ctap-keyring-device-1.0.1.tar.gz
  • Upload date:
  • Size: 147.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.1 CPython/3.8.6

File hashes

Hashes for ctap-keyring-device-1.0.1.tar.gz
Algorithm Hash digest
SHA256 f9a0845752f83e1fad235d18bfbb3d611a5bec16ff260936be3b5ad3e435d794
MD5 a55057c28eec9cad8cfde319aee66fb8
BLAKE2b-256 dde714a6f30dd290be2032176ab3a1d7a8a22934eea1c2fd17d20798552466be

See more details on using hashes here.

File details

Details for the file ctap_keyring_device-1.0.1-py2.py3-none-any.whl.

File metadata

  • Download URL: ctap_keyring_device-1.0.1-py2.py3-none-any.whl
  • Upload date:
  • Size: 17.0 kB
  • Tags: Python 2, Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.2.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/50.3.0 requests-toolbelt/0.9.1 tqdm/4.50.1 CPython/3.8.6

File hashes

Hashes for ctap_keyring_device-1.0.1-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 0e6f81d8968dcaa0ca3211001cf00b6d6bed77030902e3d5eaafd85689dfb7be
MD5 6d06ff63164fcf12ca39deeaaf175880
BLAKE2b-256 4fef8597f33ddcc678915d253afc1c2891886de144cd30847ccd196ae5a3fbbb

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page