Crate passkey

Expand description

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 as client, which implements the Webauthn Level 3 standard for authentication to websites.
passkey-authenticator - a library, usable as authenticator, which implements the CTAP2 standard.
passkey-transports - a library, usable as transports, which implements the CTAP HID protocol.
passkey-types - type definitions, usable as types 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 in make_credential()
find_credentials() - searches the CredentialStore’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::*, rand::random_vec, crypto::sha256, webauthn::*, Bytes, Passkey},
};

use coset::iana;
use url::Url;

// Example of how to set up, register and authenticate with a `Client`.
let challenge_bytes_from_rp: Bytes = random_vec(32).into();
let parameters_from_rp = PublicKeyCredentialParameters {
    ty: PublicKeyCredentialType::PublicKey,
    alg: iana::Algorithm::ES256,
};
let origin = Url::parse("https://future.1password.com").expect("Should parse");
let user_entity = PublicKeyCredentialUserEntity {
    id: random_vec(32).into(),
    display_name: "Johnny Passkey".into(),
    name: "jpasskey@example.org".into(),
};
// 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: origin.domain().unwrap().into(),
        },
        user: user_entity,
        challenge: challenge_bytes_from_rp,
        pub_key_cred_params: vec![parameters_from_rp],
        timeout: None,
        exclude_credentials: None,
        authenticator_selection: None,
        hints: None,
        attestation: AttestationConveyancePreference::None,
        attestation_formats: None,
        extensions: None,
    },
};

// Now create the credential.
let my_webauthn_credential = my_client.register(&origin, request, None).await.unwrap();

// Let's try and authenticate.
// Create a challenge that would usually come from the RP.
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(),
        hints: None,
        attestation: AttestationConveyancePreference::None,
        attestation_formats: None,
        extensions: None,
    },
};

let authenticated_cred = my_client
    .authenticate(&origin, credential_request, None)
    .await
    .unwrap();

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.

// Note: this isn't really how you generate `client_data_hash` but it simplifies the example.
// See usage.rs for actual technique.
let client_data_hash: Bytes = random_vec(32).into();
let user_entity = PublicKeyCredentialUserEntity {
    id: random_vec(32).into(),
    display_name: "Johnny Passkey".into(),
    name: "jpasskey@example.org".into(),
};
let algorithms_from_rp = PublicKeyCredentialParameters {
    ty: PublicKeyCredentialType::PublicKey,
    alg: iana::Algorithm::ES256,
};
let rp_id: String = "future.1password.com".into();
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.clone(),
    rp: make_credential::PublicKeyCredentialRpEntity {
        id: rp_id.clone(),
        name: None,
    },
    user: user_entity,
    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.unwrap();

// Now try and authenticate with the credential.
let auth_request = get_assertion::Request {
    rp_id,
    client_data_hash,
    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.unwrap();

Re-exports

pub use passkey_authenticator as authenticator;
pub use passkey_client as client;
pub use passkey_transports as transports;
pub use passkey_types as types;