4 releases (breaking)
0.3.0 | Sep 13, 2024 |
---|---|
0.2.0 | Dec 14, 2023 |
0.1.0 | Jul 28, 2023 |
0.0.1 | Feb 8, 2023 |
#74 in Authentication
1,388 downloads per month
515KB
8K
SLoC
Passkey-rs by 1Password
The passkey-rs
library is a collection of Rust libraries to enable developers to use Passkeys in Rust code through a comprehensive implementation of both the Webauthn Level 3 and CTAP2 standards. It is comprised of five sub-libraries:
passkey-client
- a library, usable asclient
, which implements the Webauthn Level 3 standard for authentication to websites.passkey-authenticator
- a library, usable asauthenticator
, which implements the CTAP2 standard.passkey-transports
- a library, usable astransports
, which implements the CTAP HID protocol.passkey-types
- type definitions, usable astypes
for the-client
and-authenticator
libraries.public-suffix
- a library which efficiently determines the effictive Top-Level Domain of a given URL, based on the Mozilla Public Suffix List.
In understanding how to use this library, developers should read the Webauthn Level 3 and CTAP2 standards. Much of the type naming in these libraries refer directly to the terms used in these standards and being familiar with their terminology will greatly aid your understanding of how to use these libraries.
Examples in this documentation shows certain values being assumed to come from the website (Relying Party). It is not within the scope of these libraries to manage the details of the interaction with the Relying Party. How these values and the authentication results are communicated with the Relying Party is an implementation detail for users of these crates.
Basic Concepts
Conceptually, working with Passkeys involves receiving requests for registration of new credentials, storing those credentials, and performing authentication with existing credentials. Two standards are involved here: Webauthn is the protocol by which a website (a "Relying Party") communicates with your application. The Client-to-Authenticator Protocol (CTAP2) is the protocol by which your application communicates with an authenticator - which can be software or a hardware device such as a FIDO2 USB key.
This library provides Rust types to implement both protocols, as well as a software Authenticator
which can be used in place of the USB keys that many will be familiar with.
You can think of these libraries as a chain that interacts with Relying Parties in the following way:
RelyingParty <-> Client
<-> Authenticator
<-> CredentialStore
The Client
type marshals and unmarshals options and data from the Relying Party. It provides the following API for registration and authentication:
register()
- Register a webauthn credential.authenticate()
- Authenticate a webauthn request.
The Client
does not itself perform cryptographic operations. Instead it depends on an internal Authenticator
for these operations.
The Authenticator
type provides a virtual authenticator which can create new credentials and authenticate users using the following functions:
make_credential()
- creates a credential.get_assertion()
- generates the cryptograhic proof of user authentication
The Authenticator
does not store credentials itself, but relies on a generic type which implements the CredentialStore
trait. This trait provides the API for storing and retrieving Passkey structures:
save_credential()
- stores a credential created inmake_credential()
find_credentials()
- searches theCredentialStore
's internal storage for credentials which might be used for an authentication.
The authenticator
library provides a range of implementations of authenticator::CredentialStore
but users of the library can provide their own.
A runnable demonstration binary is provided in passkey/examples/usage.rs
.
Example: Using the Client type for Webauthn Operations
The highest-level type in these libraries is the passkey-client::Client
. This is the type you will primarily use to implement Webauthn authentication in your application.
The following example demonstrates how to create a Client
and use it to create a credential. Doing this from scratch involves creating an Authenticator
and a CredentialStore
, then providing those to the Client
.
In this example, we are going to manually create a CredentialCreationOptions
struct with hypothetical values named *_from_rp
to indicate that these are values that would usually be supplied by the Relying Party. For simplicity, most of the CredentialCreationOptions
are being set to None
here.
use passkey::{
authenticator::{Authenticator, UserValidationMethod},
client::{Client, WebauthnError},
types::{ctap2::*, webauthn::*, Bytes, Passkey},
};
use url::Url;
// First create an Authenticator for the Client to use.
let my_aaguid = Aaguid::new_empty();
let user_validation_method = MyUserValidationMethod {};
// Create the CredentialStore for the Authenticator.
// Option<Passkey> is the simplest possible implementation of CredentialStore
let store: Option<Passkey> = None;
let my_authenticator = Authenticator::new(my_aaguid, store, user_validation_method);
// Create the Client
// If you are creating credentials, you need to declare the Client as mut
let mut my_client = Client::new(my_authenticator);
// The following values, provided as parameters to this function would usually be
// retrieved from a Relying Party according to the context of the application.
let request = CredentialCreationOptions {
public_key: PublicKeyCredentialCreationOptions {
rp: PublicKeyCredentialRpEntity {
id: None, // Leaving the ID as None means use the effective domain
name: name_from_rp.clone(),
},
user: PublicKeyCredentialUserEntity {
id: user_handle_from_rp,
display_name: display_name_from_rp,
name: name_from_rp,
},
challenge: challenge_bytes_from_rp,
pub_key_cred_params: vec![parameters_from_rp],
timeout: None,
exclude_credentials: None,
authenticator_selection: None,
attestation: AttestationConveyancePreference::None,
extensions: None,
},
};
// Now create the credential.
let my_webauthn_credential: CreatedPublicKeyCredential = my_client.register(origin, request, DefaultClientData).await?;
The above example shows how a Webauthn credential can be created. Now, we can go ahead and try to authenticate the user.
let challenge_bytes_from_rp: Bytes = random_vec(32).into();
// Now try and authenticate
let credential_request = CredentialRequestOptions {
public_key: PublicKeyCredentialRequestOptions {
challenge: challenge_bytes_from_rp,
timeout: None,
rp_id: Some(String::from(origin.domain().unwrap())),
allow_credentials: None,
user_verification: UserVerificationRequirement::default(),
extensions: None,
},
};
let authenticated_cred: AuthenticatedPublicKeyCredential = my_client
.authenticate(origin, credential_request, None)
.await?;
Example: Using the Authenticator for CTAP2 Operations
The following code provides a basic example of how to create and use an Authenticator
by itself to generate a credential and store it.
// Option<Passkey> is the simplest possible implementation of CredentialStore
let store: Option<Passkey> = None;
let user_validation_method = MyUserValidationMethod {};
let my_aaguid = Aaguid::new_empty();
let mut my_authenticator = Authenticator::new(my_aaguid, store, user_validation_method);
let reg_request = make_credential::Request {
client_data_hash: client_data_hash_from_rp.clone(),
rp: make_credential::PublicKeyCredentialRpEntity {
id: tld_from_rp.clone(),
name: None,
},
user: PublicKeyCredentialUserEntity {
id: user_handle_from_rp,
display_name: display_name_from_rp,
name: name_from_rp,
},
pub_key_cred_params: vec![algorithms_from_rp],
exclude_list: None,
extensions: None,
options: make_credential::Options::default(),
pin_auth: None,
pin_protocol: None,
};
let credential: make_credential::Response =
my_authenticator.make_credential(reg_request).await?;
The credential is stored within the Authenticator
's CredentialStore
as part of the creation process. Now, we can use this credential directly to perform an authentication:
let auth_request = get_assertion::Request {
rp_id: tld_from_rp,
client_data_hash: client_data_hash_from_rp,
allow_list: None,
extensions: None,
options: make_credential::Options::default(),
pin_auth: None,
pin_protocol: None,
};
let response = my_authenticator.get_assertion(auth_request).await?;
Crates in Detail
Passkey-Types
Passkey-types
provides the type definitions for the other crates. It may be initially confusing to realise that there are sometimes two variants of what is seemingly the same type. For example, we have a webauthn::PublicKeyCredentialRpEntity
and a ctap2::PublicKeyCredentialRpEntity
. This is because the different protocols have different requirements for which fields must be present and which are optional. In cases where the CTAP2 structures are the same as those in Webauthn, the CTAP2 libraries use the Webauthn types.
Public-Suffix
The Public-Suffix
crate provides an efficient library for determining the effective top-level domain or 'public suffix' for a given URL. Most crate users will not need to work with this library directly. It is used internally by the passkey-client::Client
type.
However, depending on the context, it may be necessary for some applications to take an alternative interpretation of certain top-level domains. To do this, users can reimplement the public-suffix list in this crate or provide an alternative implementation. Next, users should implement the public-suffix::EffectiveTLDProvider
trait and provide that implementation to Client::new_with_custom_tld_provider()
. An example of how to do this is provided in the validate_domain_with_private_list_provider()
test in passkey_client::tests
. See, also, the README in public-suffix
for more information on how to generate a custom TLD list according to the needs of your application.
Current Limitations
Client::authenticate()
andClient::register()
do not respect timeout values set inCredentialRequestOptions
.- The
Client
always reports its Authenticator Attachment Modality as "Platform" Client
only supports the "internal" type of AuthenticatorTransport- The
Authenticator
currently only supports the ECDSA w/SHA-256 algorithm.
Contributing and feedback
passkey-rs
is an open source project.
🐛 If you find an issue you'd like to report, or otherwise have feedback, please file a new Issue.
🧑💻 If you'd like to contribute to the code please start by filing or commenting on an Issue so we can track the work.
Credits
Made with ❤️ and ☕ by the 1Password team.
Get a free 1Password account for your open source project
Does your team need a secure way to manage passwords and other credentials for your open source project? Head on over to our other repository to get a 1Password Teams account on us:
✨1Password for Open Source Projects
License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
~9–16MB
~249K SLoC