DeviceAuthenticator

public protocol DeviceAuthenticator

A protocol defining the capabilities and requirements for any device authenticator. Authenticators conforming to this protocol are responsible for key management (generation, authentication, deletion) and JWT signing operations specific to their authentication type (e.g., biometrics, PIN).

  • An optional Journey object providing context for the authentication flow.

    Declaration

    Swift

    var journey: Journey? { get set }
  • register() Asynchronous

    Generates a new public and private key pair for the authenticator.

    Throws

    KeyPairGenerationError if key generation fails.

    Declaration

    Swift

    func register() async throws -> KeyPair

    Return Value

    A KeyPair containing the newly generated public and private keys.

  • authenticate(keyTag:) Asynchronous

    Declaration

    Swift

    func authenticate(keyTag: String) async -> Result<SecKey, Error>

    Return Value

    A Result containing the SecKey on success, or an Error on failure.

  • Checks if the authenticator is supported on the current device.

    Declaration

    Swift

    func isSupported(attestation: Attestation) -> Bool

    Parameters

    attestation

    The attestation type to consider for support.

    Return Value

    true if the authenticator is supported, false otherwise.

  • Returns the specific type of device binding authentication this authenticator handles.

    Declaration

    Swift

    func type() -> DeviceBindingAuthenticationType

  • Provides the access control settings for the authenticator’s keys.

    Declaration

    Swift

    func accessControl() -> SecAccessControl?

    Return Value

    A SecAccessControl object defining key access policies, or nil if not applicable.

  • Sets the prompt information to be displayed to the user during authentication.

    Declaration

    Swift

    func setPrompt(_ prompt: Prompt)

    Parameters

    prompt

    A Prompt struct containing title, subtitle, and description.

  • Initializes the authenticator with a user ID and prompt.

    Declaration

    Swift

    func initialize(userId: String, prompt: Prompt)

    Parameters

    userId

    The ID of the user associated with the authenticator.
    prompt

    The prompt to display to the user.

  • Initializes the authenticator with a user ID.

    Declaration

    Swift

    func initialize(userId: String)

    Parameters

    userId

    The ID of the user associated with the authenticator.
  • deleteKeys() Asynchronous

    Deletes all keys associated with this authenticator.

    Throws

    KeyDeletionError if key deletion fails.

    Declaration

    Swift

    func deleteKeys() async throws

  • Returns the issue time for a token, typically the current date.

    Declaration

    Swift

    func issueTime() -> Date

    Return Value

    A Date object representing the issue time.

  • Returns the not-before time for a token, typically the current date.

    Declaration

    Swift

    func notBeforeTime() -> Date

    Return Value

    A Date object representing the not-before time.

  • Validates custom claims against a list of reserved JWT claim names.

    Declaration

    Swift

    func validateCustomClaims(_ customClaims: [String : Any]) -> Bool

    Parameters

    customClaims

    A dictionary of custom claims to be validated.

    Return Value

    true if no custom claims conflict with reserved names, false otherwise.

  • sign(params:journey:) Default implementation

    Signs the given parameters to generate a JWS (JSON Web Signature). This method is used for initial device binding where a new key pair is generated.

    Throws

    JwtError if JWT signing fails.

    Default Implementation

    Signs the given parameters with an existing user key to generate a JWS. This constructs the JWT payload with standard and custom claims and signs it using the provided keys.

    Throws

    JwtError if JWT signing fails or SecKeyToJWKError if JWK conversion fails.

    Declaration

    Swift

    func sign(params: SigningParameters, journey: Journey?) throws -> String

    Parameters

    params

    The SigningParameters containing all necessary data for signing.
    journey

    An optional Journey object for context, used to derive the issuer.

    Return Value

    The compact serialized JWS string.

  • Signs the given parameters to generate a JWS (JSON Web Signature). This method is used for subsequent signing operations with an already bound user key.

    Throws

    JwtError if JWT signing fails.

    Declaration

    Swift

    func sign(params: UserKeySigningParameters, journey: Journey?) throws -> String

    Parameters

    params

    The UserKeySigningParameters containing all necessary data for signing.
    journey

    An optional Journey object for context, used to derive the issuer.

    Return Value

    The compact serialized JWS string.