.. image:: https://img.shields.io/pypi/v/ctap-keyring-device.svg
:target: https://pypi.org/project/ctap-keyring-device
:alt: PyPi version
.. image:: https://img.shields.io/pypi/pyversions/ctap-keyring-device.svg
:alt: Python version
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
:alt: Code style: Black
.. image:: https://readthedocs.org/projects/ctap-keyring-device/badge/?version=latest
:target: https://ctap-keyring-device.readthedocs.io/en/latest/?badge=latest
:alt: Read the docs
.. image:: https://img.shields.io/github/workflow/status/dany74q/ctap-keyring-device/CI
:alt: CI workflow
This library provides an implementation of a virtual CTAP2 (client-to-authenticator-protocol)
device, which uses the `keyring <https://github.com/jaraco/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
********************
.. code-block:: python
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
******************
.. code-block:: python
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
********************
.. image:: images/make-credential-flow.png
:alt: Make Credential Flow
|
Get Assertion Flow
******************
.. image:: images/get-assertion-flow.png
:alt: 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 <https://www.iana.org/assignments/cose/cose.xhtml#algorithms>`_.
Private keys are encrypted with a random UUID4 as the passphrase, using hazmat's `BestAvailableEncryption <https://cryptography.io/en/latest/hazmat/primitives/asymmetric/serialization/#cryptography.hazmat.primitives.serialization.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 <https://pypi.org/project/tox>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/dany74q/ctap-keyring-device",
"name": "ctap-keyring-device",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Danny Shemesh",
"author_email": "dany74q@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c4/c5/5c4ce510d457679c8886229ddbdc2a84969d63e50fe9fb09d6975d8e500e/ctap-keyring-device-1.0.6.tar.gz",
"platform": "",
"description": ".. image:: https://img.shields.io/pypi/v/ctap-keyring-device.svg\n :target: https://pypi.org/project/ctap-keyring-device\n :alt: PyPi version\n\n.. image:: https://img.shields.io/pypi/pyversions/ctap-keyring-device.svg\n :alt: Python version\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :target: https://github.com/psf/black\n :alt: Code style: Black\n\n.. image:: https://readthedocs.org/projects/ctap-keyring-device/badge/?version=latest\n :target: https://ctap-keyring-device.readthedocs.io/en/latest/?badge=latest\n :alt: Read the docs\n\n.. image:: https://img.shields.io/github/workflow/status/dany74q/ctap-keyring-device/CI\n :alt: CI workflow\n\n\nThis library provides an implementation of a virtual CTAP2 (client-to-authenticator-protocol)\ndevice, which uses the `keyring <https://github.com/jaraco/keyring>`_ library as its backend.\n\nOne may use this implementation as a reference for CTAP2-compatible devices,\nor to use ones host machine as an authenticator, rather than using an external one.\n\nA common use-case would be to use this library as an authenticator for a webauthn flow,\nstoring keys and retrieving assertions on a machine's configured keyring.\n\nSupported features are:\n * The make-credential, get-assertion, get-next-assertion and get-info CTAP2 flows\n * The management of keys using the following COSE algorithms: RS1, RS256, PS256, EC256, EdDSA\n * The use of any available keyring as a backend for the created key-pairs (e.g. WinCred, Keychain, ...)\n * User presence & verification on OSX and Windows, via Touch-ID and Windows-Hello\n * Storing keys in a secure manner, with no PII (personal-identifying-information) attached to them\n\n|\n\nInstallation\n============\n\nRun the following (on a darwin machine)::\n\n $ pip install ctap-keyring-device\n\n\n|\n\nUsing This Library\n==================\n\nMake Credential Flow\n********************\n\n.. code-block:: python\n\n from fido2.webauthn import PublicKeyCredentialCreationOptions, PublicKeyCredentialType, PublicKeyCredentialParameters\n from ctap_keyring_device.ctap_keyring_device import CtapKeyringDevice\n from fido2.client import Fido2Client\n from fido2 import cose\n import base64\n\n device = CtapKeyringDevice.list_devices()[0]\n origin = 'https://rp.pasten.com'\n client = Fido2Client(device, origin)\n\n rp = {'id': 'pasten.com', 'name': origin[8:], 'icon': '...'}\n user = {'id': 'danny@pasten.io', 'name': 'Danny Shemesh', 'icon': '...', 'displayName': 'Danny Pastanny'}\n challenge = base64.b64encode(b'my-challenge')\n timeout_ms = 30_000\n\n pub_key_cred_params = [PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, cose.ES256.ALGORITHM)]\n options = PublicKeyCredentialCreationOptions(rp, user, challenge, pub_key_cred_params, timeout=timeout_ms)\n\n attestation, client_data = client.make_credential(options)\n\n|\n\nGet Assertion Flow\n******************\n.. code-block:: python\n\n from fido2.webauthn import PublicKeyCredentialRequestOptions, PublicKeyCredentialType, \\\n PublicKeyCredentialParameters, PublicKeyCredentialDescriptor, UserVerificationRequirement\n from ctap_keyring_device.ctap_keyring_device import CtapKeyringDevice\n from fido2.client import Fido2Client\n from fido2 import cose\n import base64\n\n device = CtapKeyringDevice.list_devices()[0]\n origin = 'https://rp.pasten.com'\n client = Fido2Client(device, origin)\n\n challenge = base64.b64encode(b'my-challenge')\n rp = {'id': 'pasten.com', 'name': origin[8:], 'icon': '...'}\n credential_id = b'.......'\n allow_list = [\n PublicKeyCredentialDescriptor(PublicKeyCredentialType.PUBLIC_KEY, credential_id)\n ]\n timeout_ms = 30_000\n\n pub_key_cred_params = [PublicKeyCredentialParameters(PublicKeyCredentialType.PUBLIC_KEY, cose.ES256.ALGORITHM)]\n options = PublicKeyCredentialRequestOptions(challenge=challenge, rp_id=rp['id'],\n allow_credentials=allow_list, timeout=timeout_ms,\n user_verification=UserVerificationRequirement.PREFERRED)\n assertions, client_data = client.get_assertion(options)\n\n|\n\nSee examples in ``ctap-keyring-device/tests``.\n\n|\n\nCTAP Flow Diagrams\n==================\n\nMake Credential Flow\n********************\n\n.. image:: images/make-credential-flow.png\n :alt: Make Credential Flow\n\n|\n\nGet Assertion Flow\n******************\n\n.. image:: images/get-assertion-flow.png\n :alt: Get Assertion Flow\n\n|\n\nSecurity Considerations\n=======================\n\nUsing this library will help one utilize their machine's keyring as a CTAP2-compliant FIDO authenticator.\n\nCredentials are stores on the configured keyring, which defaults to a sensible implementation,\nper the platform the code is running on (e.g. keychain on OSX, WinCred on Windows, ...)\n\nThe make-credentials flow will create a key-pair for signing, using the requested `COSE algorithm <https://www.iana.org/assignments/cose/cose.xhtml#algorithms>`_.\n\nPrivate keys are encrypted with a random UUID4 as the passphrase, using hazmat's `BestAvailableEncryption <https://cryptography.io/en/latest/hazmat/primitives/asymmetric/serialization/#cryptography.hazmat.primitives.serialization.BestAvailableEncryption>`_.\n\nCredential IDs comprise of <UUID5-of-user-id>_<key-passphrase>, and are sent back to the requesting client;\nit is assumed that the credential ID is kept in a remote machine, and is always provided in the\nallow-list of a ctap get-assertion request.\n\nThe above allows us to generate and store our keys in a manner that renders key exposure as less risky,\ndue to the key being encrypted; and not storing the user-id directly, making it harder to use the key,\neven if decrypted.\n\nOn top of the mentioned safeguards, one may request the UV (user-verification) option,\nin order to trigger a 2nd factor before returning an assertion; Touch-ID / Password prompt\nis used on OSX, and Windows-Hello on Windows.\n\n|\n\nMaking Releases\n===============\n\nA CI/CD pipeline is setup on github - once a PR is merged to master, a pre-release\nwill be automatically deployed to github;\nWhen a release is tagged, it will be automatically deployed to pypi.\n\n|\n\nRunning Tests\n=============\n\nTo run the tests locally, install and invoke\n`tox <https://pypi.org/project/tox>`_.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "CTAP (client-to-authenticator-protocol) device backed by python's keyring library",
"version": "1.0.6",
"project_urls": {
"Homepage": "https://github.com/dany74q/ctap-keyring-device"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e5e3af7b4655eb93c9458e3aa92a25b2358b4b08e36b05188f4f5bb377508be9",
"md5": "48267688de8afa643ecd86f5cd7762fa",
"sha256": "12c08aabd60318bd4223eebd12463e979b8ebfec36c5943059b2eca226ed1427"
},
"downloads": -1,
"filename": "ctap_keyring_device-1.0.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "48267688de8afa643ecd86f5cd7762fa",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.6",
"size": 16719,
"upload_time": "2021-03-06T15:23:02",
"upload_time_iso_8601": "2021-03-06T15:23:02.191598Z",
"url": "https://files.pythonhosted.org/packages/e5/e3/af7b4655eb93c9458e3aa92a25b2358b4b08e36b05188f4f5bb377508be9/ctap_keyring_device-1.0.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c4c55c4ce510d457679c8886229ddbdc2a84969d63e50fe9fb09d6975d8e500e",
"md5": "5738caf5184542eb9368fc302f9ded54",
"sha256": "a44264bb3d30c4ab763e4a3098b136602f873d86b666210d2bb1405b5e0473f6"
},
"downloads": -1,
"filename": "ctap-keyring-device-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "5738caf5184542eb9368fc302f9ded54",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 266766,
"upload_time": "2021-03-06T15:23:03",
"upload_time_iso_8601": "2021-03-06T15:23:03.769217Z",
"url": "https://files.pythonhosted.org/packages/c4/c5/5c4ce510d457679c8886229ddbdc2a84969d63e50fe9fb09d6975d8e500e/ctap-keyring-device-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2021-03-06 15:23:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dany74q",
"github_project": "ctap-keyring-device",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "ctap-keyring-device"
}
JSON
