ExSwan.Registration (exswan v0.1.0)

View Source

Handles WebAuthn registration ceremony operations.

This module provides functions for generating credential creation options, processing attestation responses, and verifying registration ceremonies according to the WebAuthn specification.

Registration Flow

  1. Generate creation options with generate_creation_options/3
  2. Send options to client for credential creation
  3. Receive attestation response from client
  4. Verify the response with verify_creation/3
  5. Store the resulting credential

Examples

# Generate creation options
rp = %ExSwan.Credential.RelyingParty{id: "example.com", name: "Example"}
user = %ExSwan.Credential.User{id: user_id, name: "user@example.com", display_name: "User"}

{:ok, options} = ExSwan.Registration.generate_creation_options(rp, user)

# After receiving attestation response from client
{:ok, credential} = ExSwan.Registration.verify_creation(response, options, origin)

Summary

Functions

generate_creation_options(rp, user, opts \\ [])

Generates creation options for registering a new credential.

options_to_json(options)

Converts creation options to JSON-serializable format for client.

verify_creation(response, options, origin)

Verifies a registration response and returns a validated credential.

Functions

generate_creation_options(rp, user, opts \\ [])

@spec generate_creation_options(
  ExSwan.Credential.RelyingParty.t(),
  ExSwan.Credential.User.t(),
  keyword()
) :: {:ok, ExSwan.Attestation.CreationOptions.t()} | {:error, atom()}

Generates creation options for registering a new credential.

Creates properly formatted options for the navigator.credentials.create() call including challenge, user information, relying party details, and algorithm preferences.

Parameters

  • rp - Relying party information
  • user - User entity information
  • opts - Optional configuration (timeout, exclude_credentials, etc.)

Examples

rp = %ExSwan.Credential.RelyingParty{id: "example.com", name: "Example Corp"}
user = %ExSwan.Credential.User{
  id: :crypto.strong_rand_bytes(32),
  name: "john@example.com",
  display_name: "John Doe"
}

{:ok, options} = ExSwan.Registration.generate_creation_options(rp, user)

options_to_json(options)

@spec options_to_json(ExSwan.Attestation.CreationOptions.t()) :: map()

Converts creation options to JSON-serializable format for client.

Encodes binary data as base64url strings and formats the options according to WebAuthn specification requirements.

verify_creation(response, options, origin)

@spec verify_creation(
  map(),
  ExSwan.Attestation.CreationOptions.t(),
  String.t() | [String.t()]
) :: {:ok, ExSwan.Credential.t()} | {:error, atom()}

Verifies a registration response and returns a validated credential.

Processes the attestation response from the client, validates the attestation statement, parses authenticator data, and extracts the credential information.

Parameters

  • response - Raw attestation response from client
  • options - Creation options used for the registration
  • origin - Expected origin(s) for the ceremony

Returns

  • {:ok, credential} - Successfully validated credential
  • {:error, reason} - Validation failure with reason

Examples

{:ok, credential} = ExSwan.Registration.verify_creation(
  attestation_response,
  creation_options,
  "https://example.com"
)