Package com.yubico.yubikit.fido.client

Class BasicWebAuthnClient

java.lang.Object
com.yubico.yubikit.fido.client.BasicWebAuthnClient
All Implemented Interfaces:
Closeable, AutoCloseable
public class BasicWebAuthnClient extends Object implements Closeable
A "basic" WebAuthn client implementation which wraps a YubiKeySession.

Provides the following functionality:

  • MakeCredential: Registers a new credential. If a PIN is needed, it is passed to this method.
  • GetAssertion: Authenticate an existing credential. If a PIN is needed, it is passed to this method.
  • PIN Management: Set or change the PIN code of an Authenticator, or see its state.
  • Credential Management: List or delete resident credentials of an Authenticator.
The timeout parameter in the request options is ignored. To cancel a request pass a CommandState instance to the call and use its cancel method.

No support for Extensions. Any Extensions provided will be ignored.

  • Constructor Details

    • BasicWebAuthnClient

      public BasicWebAuthnClient(Ctap2Session session) throws IOException, com.yubico.yubikit.core.application.CommandException
      Throws:
      IOException
      com.yubico.yubikit.core.application.CommandException

  • Method Details

    • close

      public void close() throws IOException
      Specified by:
      close in interface AutoCloseable
      Specified by:
      close in interface Closeable
      Throws:
      IOException

    • getUserAgentConfiguration

      public BasicWebAuthnClient.UserAgentConfiguration getUserAgentConfiguration()

    • makeCredential

      public PublicKeyCredential makeCredential(byte[] clientDataJson, PublicKeyCredentialCreationOptions options, String effectiveDomain, @Nullable char[] pin, @Nullable Integer enterpriseAttestation, @Nullable com.yubico.yubikit.core.application.CommandState state) throws IOException, com.yubico.yubikit.core.application.CommandException, ClientError
      Create a new WebAuthn credential.

      PIN is always required if a PIN is configured.

      Parameters:
      clientDataJson - The UTF-8 encoded ClientData JSON object.
      options - The options for creating the credential.
      effectiveDomain - The effective domain for the request, which is used to validate the RP ID against.
      pin - If needed, the PIN to authorize the credential creation.
      state - If needed, the state to provide control over the ongoing operation
      Returns:
      A WebAuthn public key credential.
      Throws:
      IOException - A communication error in the transport layer
      com.yubico.yubikit.core.application.CommandException - A communication in the protocol layer
      ClientError - A higher level error

    • getAssertion

      public PublicKeyCredential getAssertion(byte[] clientDataJson, PublicKeyCredentialRequestOptions options, String effectiveDomain, @Nullable char[] pin, @Nullable com.yubico.yubikit.core.application.CommandState state) throws MultipleAssertionsAvailable, IOException, com.yubico.yubikit.core.application.CommandException, ClientError
      Authenticate an existing WebAuthn credential. PIN is required if UV is "required", or if UV is "preferred" and a PIN is configured. If no allowCredentials list is provided (which is the case for a passwordless flow) the Authenticator may contain multiple discoverable credentials for the given RP. In such cases MultipleAssertionsAvailable will be thrown, and can be handled to select an assertion.
      Parameters:
      clientDataJson - The UTF-8 encoded ClientData JSON object.
      options - The options for authenticating the credential.
      effectiveDomain - The effective domain for the request, which is used to validate the RP ID against.
      pin - If needed, the PIN to authorize the credential creation.
      state - If needed, the state to provide control over the ongoing operation
      Returns:
      Webauthn public key credential with assertion response data.
      Throws:
      MultipleAssertionsAvailable - In case of multiple assertions, catch this to make a selection and get the result.
      IOException - A communication error in the transport layer
      com.yubico.yubikit.core.application.CommandException - A communication in the protocol layer
      ClientError - A higher level error

    • isPinSupported

      public boolean isPinSupported()
      Check if the Authenticator supports external PIN.
      Returns:
      If PIN is supported.

    • isPinConfigured

      public boolean isPinConfigured()
      Check if the Authenticator has been configured with a PIN.
      Returns:
      If a PIN is configured.

    • isEnterpriseAttestationSupported

      public boolean isEnterpriseAttestationSupported()
      Check if the Authenticator supports Enterprise Attestation feature.
      Returns:
      true if the authenticator is enterprise attestation capable and enterprise attestation is enabled.
      See Also:

    • setPin

      public void setPin(char[] pin) throws IOException, com.yubico.yubikit.core.application.CommandException, ClientError
      Set the PIN for an Authenticator which supports PIN, but doesn't have one configured.
      Parameters:
      pin - The PIN to set.
      Throws:
      IOException - A communication error in the transport layer.
      com.yubico.yubikit.core.application.CommandException - A communication in the protocol layer.
      ClientError - A higher level error.

    • changePin

      public void changePin(char[] currentPin, char[] newPin) throws IOException, com.yubico.yubikit.core.application.CommandException, ClientError
      Change the PIN for an Authenticator which already has a PIN configured.
      Parameters:
      currentPin - The current PIN, to authorize the action.
      newPin - The new PIN to set.
      Throws:
      IOException - A communication error in the transport layer.
      com.yubico.yubikit.core.application.CommandException - A communication in the protocol layer.
      ClientError - A higher level error.

    • getCredentialManager

      public CredentialManager getCredentialManager(char[] pin) throws IOException, com.yubico.yubikit.core.application.CommandException, ClientError
      Return an object that provides management of resident key type credentials stored on a YubiKey
      Parameters:
      pin - The configured PIN
      Returns:
      Credential manager
      Throws:
      IOException - A communication error in the transport layer.
      com.yubico.yubikit.core.application.CommandException - A communication in the protocol layer.
      ClientError - A higher level error.

    • ctapMakeCredential

      protected Ctap2Session.CredentialData ctapMakeCredential(byte[] clientDataHash, PublicKeyCredentialCreationOptions options, String effectiveDomain, @Nullable char[] pin, @Nullable Integer enterpriseAttestation, @Nullable com.yubico.yubikit.core.application.CommandState state) throws IOException, com.yubico.yubikit.core.application.CommandException, ClientError
      Create a new WebAuthn credential.

      This method is used internally in YubiKit and is not part of the public API. It may be changed or removed at any time.

      PIN is always required if a PIN is configured.

      Parameters:
      clientDataHash - Hash of client data.
      options - The options for creating the credential.
      effectiveDomain - The effective domain for the request, which is used to validate the RP ID against.
      pin - If needed, the PIN to authorize the credential creation.
      state - If needed, the state to provide control over the ongoing operation
      Returns:
      A WebAuthn public key credential.
      Throws:
      IOException - A communication error in the transport layer
      com.yubico.yubikit.core.application.CommandException - A communication in the protocol layer
      ClientError - A higher level error

    • ctapGetAssertions

      protected List<Ctap2Session.AssertionData> ctapGetAssertions(byte[] clientDataHash, PublicKeyCredentialRequestOptions options, String effectiveDomain, @Nullable char[] pin, @Nullable com.yubico.yubikit.core.application.CommandState state) throws IOException, com.yubico.yubikit.core.application.CommandException, ClientError
      Authenticate an existing WebAuthn credential.

      This method is used internally in YubiKit and is not part of the public API. It may be changed or removed at any time.

      PIN is required if UV is "required", or if UV is "preferred" and a PIN is configured. If no allowCredentials list is provided (which is the case for a passwordless flow) the Authenticator may contain multiple discoverable credentials for the given RP. In such cases MultipleAssertionsAvailable will be thrown, and can be handled to select an assertion.

      Parameters:
      clientDataHash - Hash of client data.
      options - The options for authenticating the credential.
      effectiveDomain - The effective domain for the request, which is used to validate the RP ID against.
      pin - If needed, the PIN to authorize the credential creation.
      state - If needed, the state to provide control over the ongoing operation
      Returns:
      Webauthn public key credential with assertion response data.
      Throws:
      IOException - A communication error in the transport layer
      com.yubico.yubikit.core.application.CommandException - A communication in the protocol layer
      ClientError - A higher level error