de.adesso.softauthn

Interface Authenticator

All Known Implementing Classes:

BrokenAuthenticator, NopAuthenticator, WebAuthnAuthenticator

public interface Authenticator

The Authenticator interface represents the API provided by WebAuthn authenticators as specified by the WebAuthn spec (see below).

See Also:

WebAuthn Authenticator Model, Authenticators

API Note:

Not every authenticator operation is implemented. Specifically, authenticatorCancel is missing because it serves no purpose in a non-concurrent software environment.

Implementation Note:

The intention behind this interface is to allow the definition of WebAuthn authenticators in software (like the main implementation of this library WebAuthnAuthenticator), but it can of course be implemented in other ways to achieve different purposes. For instance, there are several "broken" implementations provided by this library that emulate authenticators that behave incorrectly because of e.g. some hardware defect or even because of malicious intent.
In theory, this interface can also be implemented for actual WebAuthn hardware authenticators by communicating with their respective drivers or similar.

Method Summary

Modifier and Type	Method and Description
AuthenticatorAssertionData	getAssertion(java.lang.String rpId, byte[] hash, java.util.List<com.yubico.webauthn.data.PublicKeyCredentialDescriptor> allowedCredentialDescriptorList, boolean requireUserVerification, byte[] extensions) Method that will be called by a client platform to create an assertion for an existing credential.
com.yubico.webauthn.data.AuthenticatorAttachment	getAttachment() Returns this authenticator's attachment.
com.upokecenter.cbor.CBORObject	makeCredential(byte[] hash, com.yubico.webauthn.data.RelyingPartyIdentity rpEntity, com.yubico.webauthn.data.UserIdentity userEntity, boolean requireResidentKey, boolean requireUserVerification, java.util.List<com.yubico.webauthn.data.PublicKeyCredentialParameters> credTypesAndPubKeyAlgs, java.util.Set<com.yubico.webauthn.data.PublicKeyCredentialDescriptor> excludeCredentials, boolean enterpriseAttestationPossible, byte[] extensions) Method that will be called by a client platform to create a new credential on this authenticator.
boolean	supportsClientSideDiscoverablePublicKeyCredentialSources() Returns whether this authenticator supports the creation of client-side discoverable credentials, also known as resident keys.
boolean	supportsUserVerification() Returns whether this authenticator can perform user verification.

Method Detail

makeCredential

com.upokecenter.cbor.CBORObject makeCredential(byte[] hash,
                                               com.yubico.webauthn.data.RelyingPartyIdentity rpEntity,
                                               com.yubico.webauthn.data.UserIdentity userEntity,
                                               boolean requireResidentKey,
                                               boolean requireUserVerification,
                                               java.util.List<com.yubico.webauthn.data.PublicKeyCredentialParameters> credTypesAndPubKeyAlgs,
                                               java.util.Set<com.yubico.webauthn.data.PublicKeyCredentialDescriptor> excludeCredentials,
                                               boolean enterpriseAttestationPossible,
                                               byte[] extensions)
                                        throws java.lang.IllegalArgumentException,
                                               java.lang.UnsupportedOperationException,
                                               java.lang.IllegalStateException

Method that will be called by a client platform to create a new credential on this authenticator.

Parameters:

hash - The hash of the serialized client data, provided by the client.

rpEntity - The Relying Party entity

userEntity - The user account's entity, containing the user handle given by the Relying Party.

requireResidentKey - The effective resident key requirement for credential creation, a Boolean value determined by the client.

requireUserVerification - The effective user verification requirement for credential creation, a Boolean value determined by the client.

credTypesAndPubKeyAlgs - A sequence of credential types and algorithms requested by the Relying Party. This sequence is ordered from most preferred to least preferred. The authenticator makes a best-effort to create the most preferred credential that it can.

excludeCredentials - A nullable list of PublicKeyCredentialDescriptor objects provided by the Relying Party with the intention that, if any of these are known to the authenticator, it SHOULD NOT create a new credential. excludeCredentials contains a list of known credentials.

enterpriseAttestationPossible - A Boolean value that indicates that individually-identifying attestation MAY be returned by the authenticator.

extensions - A CBOR map from extension identifiers to their authenticator extension inputs, created by the client based on the extensions requested by the Relying Party, if any.

Returns:

An Attestation object created by the authenticator for the request.

Throws:

java.lang.IllegalArgumentException - If the parameters are malformed in any way.

java.lang.UnsupportedOperationException - If some requirement was requested that this authenticator does not support.

java.lang.IllegalStateException - If the current state of this authenticator prevents it from fulfilling the request.

See Also:

The authenticatorMakeCredential Operation

API Note:

What this method does exactly is up to the authenticator implementation, e.g. an implementation may intentionally choose to deviate from the algorithm described in the WebAuthn specification.

getAssertion

AuthenticatorAssertionData getAssertion(java.lang.String rpId,
                                        byte[] hash,
                                        java.util.List<com.yubico.webauthn.data.PublicKeyCredentialDescriptor> allowedCredentialDescriptorList,
                                        boolean requireUserVerification,
                                        byte[] extensions)
                                 throws java.lang.IllegalArgumentException,
                                        java.util.NoSuchElementException

Method that will be called by a client platform to create an assertion for an existing credential.

Parameters:

rpId - The caller’s RP ID, as determined by the user agent and the client.

hash - The hash of the serialized client data, provided by the client.

allowedCredentialDescriptorList - A nullable list of PublicKeyCredentialDescriptors describing credentials acceptable to the Relying Party (possibly filtered by the client), if any.

requireUserVerification - The effective user verification requirement for assertion, a Boolean value provided by the client.

extensions - A CBOR map from extension identifiers to their authenticator extension inputs, created by the client based on the extensions requested by the Relying Party, if any.

Returns:

The result data of the assertion.

Throws:

java.lang.IllegalArgumentException - If the parameters are malformed in any way.

java.util.NoSuchElementException - If this authenticator cannot find any matching credential.

See Also:

The authenticatorGetAssertion Operation

API Note:

What this method does exactly is up to the authenticator implementation, e.g. an implementation may intentionally choose to deviate from the algorithm described in the WebAuthn specification.

getAttachment

com.yubico.webauthn.data.AuthenticatorAttachment getAttachment()

Returns this authenticator's attachment.

Returns:

the attachment.

supportsClientSideDiscoverablePublicKeyCredentialSources

boolean supportsClientSideDiscoverablePublicKeyCredentialSources()

Returns whether this authenticator supports the creation of client-side discoverable credentials, also known as resident keys.

Returns:

Whether this authenticator can store credentials itself.

See Also:

Credential Storage Modality

supportsUserVerification

boolean supportsUserVerification()

Returns whether this authenticator can perform user verification.

Returns:

Whether user verification is supported.

See Also:

Authentication Factor Capability