Struct webauthn_rs::core::Webauthn

pub struct Webauthn<T> { /* fields omitted */ }

This is the core of the Webauthn operations. It provides 4 interfaces that you will likely use the most:

• generate_challenge_response
• register_credential
• generate_challenge_authenticate
• authenticate_credential

Each of these is described in turn, but they will all map to routes in your application. The generate functions return Json challenges that are intended to be processed by the client browser, and the register and authenticate will receive Json that is processed and verified.

These functions return state that you must store and handle correctly for the authentication or registration to proceed correctly.

As a result, it’s very important you read the function descriptions to understand the process as much as possible.

Implementations

impl<T> Webauthn<T>

pub fn new(config: T) -> Self where
    T: WebauthnConfig, 

Create a new Webauthn instance with the supplied configuration. The config type will receive and interact with various callbacks to allow the lifecycle and application handling of Credentials to be customised for your application.

You should see the Documentation for WebauthnConfig, which is the main part of the code you will interact with for site-specific customisation.

pub fn generate_challenge_register(
    &self,
    user_name: &str,
    user_verification_required: bool
) -> Result<(CreationChallengeResponse, RegistrationState), WebauthnError> where
    T: WebauthnConfig, 

Generate a new challenge for client registration. Same as generate_challenge_register_options but default options

pub fn generate_challenge_register_options(
    &self,
    user_id: UserId,
    user_name: String,
    user_display_name: String,
    exclude_credentials: Option<Vec<CredentialID>>,
    policy: Option<UserVerificationPolicy>,
    extensions: Option<RequestRegistrationExtensions>
) -> Result<(CreationChallengeResponse, RegistrationState), WebauthnError> where
    T: WebauthnConfig, 

Generate a new challenge for client registration. This is the first step in the lifecycle of a credential. This function will return the creationchallengeresponse which is suitable for serde json serialisation to be sent to the client. The client (generally a web browser) will pass this JSON structure to the navigator.credentials.create() javascript function for registration.

It also returns a RegistrationState, that you must persist. It is strongly advised you associate this RegistrationState with the UserId of the requester.

pub fn register_credential(
    &self,
    reg: &RegisterPublicKeyCredential,
    state: &RegistrationState,
    does_exist_fn: impl Fn(&CredentialID) -> Result<bool, ()>
) -> Result<(Credential, AuthenticatorData<Registration>), WebauthnError> where
    T: WebauthnConfig, 

Process a credential registration response. This is the output of navigator.credentials.create() which is sent to the webserver from the client.

Given the username you also must provide the associated RegistrationState for this operation to proceed.

On success this returns a new Credential that you must persist and associate with the user.

Optionally, you may provide a closure that is able to check if any credential of the same id has already been persisted by your server.

pub fn generate_challenge_authenticate(
    &self,
    creds: Vec<Credential>
) -> Result<(RequestChallengeResponse, AuthenticationState), WebauthnError> where
    T: WebauthnConfig, 

Convenience function for generate_challenge_authenticate_extensions without extensions

pub fn generate_challenge_authenticate_credential(
    &self,
    cred: Credential,
    policy: UserVerificationPolicy,
    extensions: Option<RequestAuthenticationExtensions>
) -> Result<(RequestChallengeResponse, AuthenticationState), WebauthnError> where
    T: WebauthnConfig, 

Authenticate a single credential, with the ability to override the userVerification policy requested, or extensions in use.

NOTE: Over-riding the UserVerificationPolicy may have SECURITY consequences. You should understand how this interacts with the single credential in use, and how that may impact your system security.

If in doubt, do NOT use this function!

pub fn generate_challenge_authenticate_options(
    &self,
    creds: Vec<Credential>,
    extensions: Option<RequestAuthenticationExtensions>
) -> Result<(RequestChallengeResponse, AuthenticationState), WebauthnError> where
    T: WebauthnConfig, 

Generate a challenge for an authenticate request for a user. You must supply the set of credentials that exist for the user that may be used in this authentication request. If an empty credential set is supplied, the authentication will fail.

This challenge is supplied to to the client javascript function navigator.credentials.get().

You must persist the AuthenticationState that is returned. You should associate this by UserId. The AuthenticationState is required for the authenticate_credential function to operate correctly.

NOTE: WebauthnError::InconsistentUserVerificationPolicy

This error is returning when the set of credentials has a mix of registration user verification policies. This is due to an issue with the webauthn standard as noted at https://github.com/w3c/webauthn/issues/1510. What can occur is that when you register a credential, you set an expectation as to the verification policy of that credential, and if that credential can soley be a MFA on it’s own or requires extra material to function as an MFA. However, when you mix credentials you can have unverified credentials require verification (register discouraged, or u2f on ctap1, then authenticate preferred and ctap2) or verified credentials NOT need verification.

As a result, this means the set of credentials that is provided must be internally consistent so that the policy can be set to discouraged or required based on the credentials given. This means you must consider a UX to allow the user to choose if they wish to use a verified token or not as webauthn as a standard can not make this distinction.

pub fn authenticate_credential<'a>(
    &self,
    rsp: &PublicKeyCredential,
    state: &'a AuthenticationState
) -> Result<(&'a CredentialID, AuthenticatorData<Authentication>), WebauthnError> where
    T: WebauthnConfig, 

Process an authenticate response from the authenticator and browser. This is the output of navigator.credentials.get(), which is processed by this function. If the authentication fails, appropriate errors will be returned.

This requires the associated AuthenticationState that was created by generate_challenge_authenticate

On successful authentication, an Ok result is returned. The Ok may contain the CredentialID and associated counter, which you should update for security purposes. If the Ok returns None then the credential does not have a counter.

Trait Implementations

impl<T: Debug> Debug for Webauthn<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.