Package com.yubico.yubikit.fido.client

Class Ctap2Client

java.lang.Object

com.yubico.yubikit.fido.client.Ctap2Client

All Implemented Interfaces:

WebAuthnClient, Closeable, AutoCloseable

public class Ctap2Client
extends Object
implements WebAuthnClient

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Ctap2Client.UserAgentConfiguration

Constructor Summary

Constructors

Constructor	Description
Ctap2Client(Ctap2Session session)	Create a new Webauthn client.
Ctap2Client(Ctap2Session session, @Nullable List<Extension> extensions)	Create a new Webauthn client.

Method Summary

Modifier and Type	Method	Description
void	changePin(char[] currentPin, char[] newPin)	Change the PIN for an Authenticator which already has a PIN configured.
void	close()
protected List<com.yubico.yubikit.core.util.Pair<Ctap2Session.AssertionData,ClientExtensionResults>>	ctapGetAssertions(byte[] clientDataHash, PublicKeyCredentialRequestOptions options, String effectiveDomain, char @Nullable [] pin, @Nullable com.yubico.yubikit.core.application.CommandState state)	Authenticate an existing WebAuthn credential.
protected com.yubico.yubikit.core.util.Pair<Ctap2Session.CredentialData,ClientExtensionResults>	ctapMakeCredential(byte[] clientDataHash, PublicKeyCredentialCreationOptions options, String effectiveDomain, char @Nullable [] pin, @Nullable Integer enterpriseAttestation, @Nullable com.yubico.yubikit.core.application.CommandState state)	Create a new WebAuthn credential.
PublicKeyCredential	getAssertion(ClientDataProvider clientData, PublicKeyCredentialRequestOptions options, String effectiveDomain, char @Nullable [] pin, @Nullable com.yubico.yubikit.core.application.CommandState state)	Authenticate an existing WebAuthn credential.
CredentialManager	getCredentialManager(char[] pin)	Return an object that provides management of resident key type credentials stored on a YubiKey
Ctap2Session	getSession()
Ctap2Client.UserAgentConfiguration	getUserAgentConfiguration()
boolean	isEnterpriseAttestationSupported()	Check if the Authenticator supports Enterprise Attestation feature.
boolean	isPinConfigured()	Check if the Authenticator has been configured with a PIN.
boolean	isPinSupported()	Check if the Authenticator supports PIN.
PublicKeyCredential	makeCredential(ClientDataProvider clientData, PublicKeyCredentialCreationOptions options, String effectiveDomain, char @Nullable [] pin, @Nullable Integer enterpriseAttestation, @Nullable com.yubico.yubikit.core.application.CommandState state)	Create a new WebAuthn credential.
void	setPin(char[] pin)	Set the PIN for an Authenticator which supports PIN, but doesn't have one configured.
static void	validateExtensionInputs(PublicKeyCredentialCreationOptions options, @Nullable List<Extension> extensions)	Validate the device-independent client extension inputs of a registration request, without a key.
static void	validateExtensionInputs(PublicKeyCredentialRequestOptions options, @Nullable List<Extension> extensions)	Validate the device-independent client extension inputs of an authentication request, without a key.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

Ctap2Client

public Ctap2Client(Ctap2Session session)
            throws IOException,
com.yubico.yubikit.core.application.CommandException

Create a new Webauthn client.

This client will process all extensions.

Parameters:

session - CTAP session

Throws:

IOException - A communication error in the transport layer

com.yubico.yubikit.core.application.CommandException - A communication in the protocol layer

See Also:

• Webauthn client
• Webauthn extensions
• CTAP extensions

Ctap2Client

public Ctap2Client(Ctap2Session session,
 @Nullable List<Extension> extensions)
            throws IOException,
com.yubico.yubikit.core.application.CommandException

Create a new Webauthn client.

This client will only process provided extensions.

Parameters:

session - CTAP2 session

extensions - List of extensions or null to use default extensions

Throws:

IOException - A communication error in the transport layer

com.yubico.yubikit.core.application.CommandException - A communication in the protocol layer

See Also:

• Webauthn client
• Webauthn extensions
• CTAP extensions

Method Details

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Throws:

IOException

getUserAgentConfiguration

public Ctap2Client.UserAgentConfiguration getUserAgentConfiguration()

getSession

public Ctap2Session getSession()

makeCredential

public PublicKeyCredential makeCredential(ClientDataProvider clientData,
 PublicKeyCredentialCreationOptions options,
 String effectiveDomain,
 char @Nullable [] 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.

Specified by:

makeCredential in interface WebAuthnClient

Parameters:

clientData - The ClientDataProvider instance supplying client data for the request

options - The options for creating the credential

effectiveDomain - The effective domain for the request, used to validate the RP ID

pin - If needed, the PIN to authorize the credential creation (CTAP2 only)

enterpriseAttestation - Enterprise attestation parameter (CTAP2 only)

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(ClientDataProvider clientData,
 PublicKeyCredentialRequestOptions options,
 String effectiveDomain,
 char @Nullable [] 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.

Specified by:

getAssertion in interface WebAuthnClient

Parameters:

clientData - The ClientDataProvider instance supplying client data for the request. If a provider that only supplies the hash is passed, the resulting credential will contain an empty clientDataJSON in the response.

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 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:

• Enterprise Attestation

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 com.yubico.yubikit.core.util.Pair<Ctap2Session.CredentialData,ClientExtensionResults> ctapMakeCredential(byte[] clientDataHash,
 PublicKeyCredentialCreationOptions options,
 String effectiveDomain,
 char @Nullable [] 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 pair of credential data and client extension results.

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<com.yubico.yubikit.core.util.Pair<Ctap2Session.AssertionData,ClientExtensionResults>> ctapGetAssertions(byte[] clientDataHash,
 PublicKeyCredentialRequestOptions options,
 String effectiveDomain,
 char @Nullable [] 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:

List of pairs containing assertion response data and client extension results.

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

validateExtensionInputs

public static void validateExtensionInputs(PublicKeyCredentialCreationOptions options,
 @Nullable List<Extension> extensions)
                                    throws ClientError

Validate the device-independent client extension inputs of a registration request, without a key.

Runs each extension's Extension.validateCreateInputs(com.yubico.yubikit.fido.webauthn.PublicKeyCredentialCreationOptions) and surfaces any failure as the same ClientError makeCredential(com.yubico.yubikit.fido.client.clientdata.ClientDataProvider, com.yubico.yubikit.fido.webauthn.PublicKeyCredentialCreationOptions, java.lang.String, char[], java.lang.Integer, com.yubico.yubikit.core.application.CommandState) would throw for it. This lets a caller reject a request that can never succeed before connecting to (or prompting for) an authenticator — matching a browser's synchronous NotSupportedError/SyntaxError.

This is an optional fast-path: the same checks run inside makeCredential(com.yubico.yubikit.fido.client.clientdata.ClientDataProvider, com.yubico.yubikit.fido.webauthn.PublicKeyCredentialCreationOptions, java.lang.String, char[], java.lang.Integer, com.yubico.yubikit.core.application.CommandState), so a caller that skips this still gets identical errors, just later. It only covers request-shape checks; capability checks that need the authenticator's info (e.g. largeBlob support:"required", credProtect enforce) are not performed here.

Coverage is per-extension: only extensions that override Extension.validateCreateInputs(com.yubico.yubikit.fido.webauthn.PublicKeyCredentialCreationOptions)/Extension.validateGetInputs(com.yubico.yubikit.fido.webauthn.PublicKeyCredentialRequestOptions) participate (currently largeBlob). An extension whose hard-failures are only raised once the authenticator's support is known (e.g. prf/hmac-secret, whose evalByCredential checks sit behind a support gate in makeCredential(com.yubico.yubikit.fido.client.clientdata.ClientDataProvider, com.yubico.yubikit.fido.webauthn.PublicKeyCredentialCreationOptions, java.lang.String, char[], java.lang.Integer, com.yubico.yubikit.core.application.CommandState)/getAssertion(com.yubico.yubikit.fido.client.clientdata.ClientDataProvider, com.yubico.yubikit.fido.webauthn.PublicKeyCredentialRequestOptions, java.lang.String, char[], com.yubico.yubikit.core.application.CommandState)) is intentionally not pre-validated here — doing so would reject a request the device path would accept by ignoring the extension. Such requests still surface their error on the device path.

Parameters:

options - the registration request to validate

extensions - the extensions to check, or null for the default set

Throws:

ClientError - if a requested extension input cannot be satisfied

validateExtensionInputs

public static void validateExtensionInputs(PublicKeyCredentialRequestOptions options,
 @Nullable List<Extension> extensions)
                                    throws ClientError

Validate the device-independent client extension inputs of an authentication request, without a key. The authentication counterpart of validateExtensionInputs(PublicKeyCredentialCreationOptions, List); see it for semantics.

Parameters:

options - the authentication request to validate

extensions - the extensions to check, or null for the default set

Throws:

ClientError - if a requested extension input cannot be satisfied