CTAP (client-to-authenticator-protocol) device backed by python's keyring library
Project description
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
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | f9a0845752f83e1fad235d18bfbb3d611a5bec16ff260936be3b5ad3e435d794 |
|
MD5 | a55057c28eec9cad8cfde319aee66fb8 |
|
BLAKE2b-256 | dde714a6f30dd290be2032176ab3a1d7a8a22934eea1c2fd17d20798552466be |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0e6f81d8968dcaa0ca3211001cf00b6d6bed77030902e3d5eaafd85689dfb7be |
|
MD5 | 6d06ff63164fcf12ca39deeaaf175880 |
|
BLAKE2b-256 | 4fef8597f33ddcc678915d253afc1c2891886de144cd30847ccd196ae5a3fbbb |