Repository files navigation

PyWARP is an implementation of the W3CWebAuthn standard's Relying Partycomponent in Python. The WebAuthn standard is used to provide advanced authentication security for two-factor,multifactor and passwordless authentication models through the use of dedicated hardware security keys and biometricdevices such asYubico YubiKey,Google Titan,TPM, andTouch ID. PyWARP's design goal is to provide anergonomic and intuitive API to guide the implementer with gooddefaults and trusted dependencies.

Compared to earlier two-factor standards like HOTP (RFC 4226) and TOTP(RFC 6238), theFIDO U2F profile of WebAuthn uses asymmetric cryptography toavoid using a shared secret design, which strengthens your authentication solution against server-side attacks. HardwareU2F also sequesters the client secret in a dedicated single-purpose device, which strengthens your clients againstclient-side attacks. And by automating scoping of credentials to relying party IDs (application origin/domain names),WebAuthn/U2F adds protection against phishing attacks.

PyWARP implements theRelying Party component of WebAuthn. A Relying Party is a server-side application that instructsthe browser (user agent) to use WebAuthn APIs to authenticate its users.

To see an example of PyWARP in action, check theexamples directory. Two demos are included: anAWS Chalice app and aFlask app.

In addition to reading theWebAuthn standard, we recommend that implementers readtheOWASP Authentication Cheat Sheet andNIST SP 800-63-3: Digital Authentication Guideline for a high level overview ofauthentication best practices.

pip install pywarp

PyWARP requires Python 3.6+. Python 2.7 and <= 3.5 is not supported.

PyWARP depends oncryptography, which in turn requires OpenSSL and CFFI. Seethecryptography installation docs for more details.

frompywarpimportRelyingPartyManager,Credential# Using DynamoDB as an example. See "storage backends" below for other databases.frompywarp.backendsimportDynamoBackendrp_id="myapp.example.com"# This must match the origin domain of your app, as seen by the browser.rp=RelyingPartyManager("PyWARP demo",rp_id=rp_id,credential_storage_backend=DynamoBackend())# Get options for navigator.credentials.create() - pass these to your frontend when registering a useropts=rp.get_registration_options(email=str)# Run the protocol in https://www.w3.org/TR/webauthn/#registering-a-new-credential,# then call the credential storage backend to store the credential public key.rp.register(attestation_object=bytes,client_data_json=bytes,email=bytes)# Get options for navigator.credentials.get() - pass these to your frontend when logging in a useropts=rp.get_authentication_options(email=str)# Run the protocol in https://www.w3.org/TR/webauthn/#verifying-assertion,# calling the credential storage backend to retrieve the credential public key.# If no exception is raised, proceed with user login.rp.verify(authenticator_data=bytes,client_data_json=bytes,signature=bytes,user_handle=bytes,raw_id=bytes,email=bytes)

Seeexamples/chalice/app.py andexamples/chalice/chalicelib/index.html(frontend) for a complete example.

Your application is presumably using an application server like uWSGI, a database backend like MySQL, PostgreSQL orMongoDB, and maybe a framework like Flask or Django to tie them together. PyWARP makes no assumptions about yourdatabase, schema, or model. Instead, it provides an abstract class (pywarp.backends.CredentialStorageBackend)representing an interface for storing and retrieving WebAuthn credential data for your users.

To deploy PyWARP, declare a subclass ofCredentialStorageBackend. In your subclass, implement bindings to yourdatabase, then pass an instance of your subclass topywarp.RelyingPartyManager(credential_storage_backend=...):

frompywarpimportRelyingPartyManager,Credentialfrompywarp.backendsimportCredentialStorageBackendclassMyDBBackend(CredentialStorageBackend):def__init__(self, ...):self.database_client= ...defget_credential_by_email(self,email):user_record=self.database_client.get(email)returnCredential(credential_id=user_record["cred_id"],credential_public_key=user_record["cred_pub_key"])defsave_credential_for_user(self,email,credential):self.database_client.update(email, {"cred_id":credential.credential_id,"cred_pub_key":bytes(credential.public_key)})defsave_challenge_for_user(self,email,challenge,type):self.database_client.update(email, {type+"challenge":challenge})defget_challenge_for_user(self,email,type):user_record=self.database_client.get(email)returnuser_record[type+"challenge"]my_rp=RelyingPartyManager(credential_storage_backend=MyDBBackend(...), ...)

The Chalice app example (in theexamples/chalice directory) can be deployed as anAWS Lambda application when used with conventional AWS account credentials(configured viaaws configure in theAWS CLI). This example usesDynamoDB as a storage backend.

To deploy this example, runmake -C examples/chalice after configuring your AWS CLI credentials.

See theAPI documentation for more.

• Andrey Kislyuk

• Project home page (GitHub)
• Documentation (Read the Docs)
• Package distribution (PyPI)
• Change log

Please report bugs, issues, feature requests, etc. onGitHub.

Licensed under the terms of theApache License, Version 2.0.