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.
CTAP Flow Diagrams
Make Credential Flow
Get Assertion Flow
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.
1 maintainer
Metadata
1 maintainer
Release files for ctap-keyring-device 1.0.6
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ctap-keyring-device-1.0.6.tar.gz | 266.8 kB | Without provenance | Details for ctap-keyring-device-1.0.6.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ctap_keyring_device-1.0.6-py2.py3-none-any.whl | Python 2, Python 3 | none | any | Details for ctap_keyring_device-1.0.6-py2.py3-none-any.whl |
Total release size: 283.5 kB
Release files / ctap-keyring-device-1.0.6.tar.gz
| Download URL | ctap-keyring-device-1.0.6.tar.gz |
|---|---|
| Size | 266.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a44264bb3d30c4ab763e4a3098b136602f873d86b666210d2bb1405b5e0473f6
|
|
BLAKE2b-256 checksum How to use checksums |
c4c55c4ce510d457679c8886229ddbdc2a84969d63e50fe9fb09d6975d8e500e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/52.0.0 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.2
|
Release files / ctap_keyring_device-1.0.6-py2.py3-none-any.whl
| Download URL | ctap_keyring_device-1.0.6-py2.py3-none-any.whl |
|---|---|
| Size | 16.7 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
12c08aabd60318bd4223eebd12463e979b8ebfec36c5943059b2eca226ed1427
|
|
BLAKE2b-256 checksum How to use checksums |
e5e3af7b4655eb93c9458e3aa92a25b2358b4b08e36b05188f4f5bb377508be9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/3.3.0 pkginfo/1.7.0 requests/2.25.1 setuptools/52.0.0 requests-toolbelt/0.9.1 tqdm/4.59.0 CPython/3.9.2
|
Security for ctap-keyring-device 1.0.6
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
