Package com.yubico.yubikit.fido.ctap

Class Ctap2Session

java.lang.Object

com.yubico.yubikit.core.application.ApplicationSession<CtapSession>

com.yubico.yubikit.fido.ctap.CtapSession

com.yubico.yubikit.fido.ctap.Ctap1Session

com.yubico.yubikit.fido.ctap.Ctap2Session

All Implemented Interfaces:

Closeable, AutoCloseable

public class Ctap2Session
extends Ctap1Session

Implements CTAP 2.3

See Also:

• Client to Authenticator Protocol (CTAP)

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Ctap2Session.AssertionData	Data class holding the result of getAssertion.
static class	Ctap2Session.CredentialData	Data class holding the result of makeCredential.
static class	Ctap2Session.InfoData	Data object containing the information readable form a YubiKey using the getInfo command.

Nested classes/interfaces inherited from class com.yubico.yubikit.fido.ctap.Ctap1Session

Ctap1Session.RegistrationData, Ctap1Session.SignatureData

Constructor Summary

Constructors

Constructor	Description
Ctap2Session(com.yubico.yubikit.core.fido.FidoConnection connection)
Ctap2Session(com.yubico.yubikit.core.smartcard.SmartCardConnection connection)
Ctap2Session(com.yubico.yubikit.core.smartcard.SmartCardConnection connection, @Nullable com.yubico.yubikit.core.smartcard.scp.ScpKeyParams scpKeyParams)
Ctap2Session(com.yubico.yubikit.core.smartcard.SmartCardConnection connection, com.yubico.yubikit.core.Version version)
Ctap2Session(com.yubico.yubikit.core.smartcard.SmartCardConnection connection, com.yubico.yubikit.core.Version version, @Nullable com.yubico.yubikit.core.smartcard.scp.ScpKeyParams scpKeyParams)

Method Summary

Modifier and Type	Method	Description
void	close()
Map<Integer,?>	config(byte subCommand, @Nullable Map<?,?> subCommandParams, @Nullable Integer pinUvAuthProtocol, byte @Nullable [] pinUvAuthParam)	This command is used to configure various authenticator features through the use of its subcommands.
List<Ctap2Session.AssertionData>	getAssertions(String rpId, byte[] clientDataHash, @Nullable List<Map<String,?>> allowList, @Nullable Map<String,?> extensions, @Nullable Map<String,?> options, byte @Nullable [] pinUvAuthParam, @Nullable Integer pinUvAuthProtocol, @Nullable com.yubico.yubikit.core.application.CommandState state)	This method is used by a host to request cryptographic proof of user authentication as well as user consent to a given transaction, using a previously generated credential that is bound to the authenticator and relying party identifier.
Ctap2Session.InfoData	getCachedInfo()
Ctap2Session.InfoData	getInfo()	Using this method, platforms can request that the authenticator report a list of its supported protocol versions and extensions, its AAGUID, and other aspects of its overall capabilities.
com.yubico.yubikit.core.Version	getVersion()	Gets the version of the YubiKey firmware.
Map<Integer,?>	largeBlobs(int offset, @Nullable Integer get, byte @Nullable [] set, @Nullable Integer length, byte @Nullable [] pinUvAuthParam, @Nullable Integer pinUvAuthProtocol)	This command allows a platform to store a larger amount of information associated with a credential.
Ctap2Session.CredentialData	makeCredential(byte[] clientDataHash, Map<String,?> rp, Map<String,?> user, List<Map<String,?>> pubKeyCredParams, @Nullable List<Map<String,?>> excludeList, @Nullable Map<String,?> extensions, @Nullable Map<String,?> options, byte @Nullable [] pinUvAuthParam, @Nullable Integer pinUvAuthProtocol, @Nullable Integer enterpriseAttestation, @Nullable com.yubico.yubikit.core.application.CommandState state)	This method is invoked by the host to request generation of a new credential in the authenticator.
void	reset(@Nullable com.yubico.yubikit.core.application.CommandState state)	Issues a CTAP2 reset, which will delete/invalidate all FIDO credentials.
void	selection(@Nullable com.yubico.yubikit.core.application.CommandState state)	This command allows the platform to let a user select a certain authenticator by asking for user presence.

Methods inherited from class com.yubico.yubikit.fido.ctap.Ctap1Session

authenticate, getU2fVersion, register

Methods inherited from class com.yubico.yubikit.core.application.ApplicationSession

require, supports

Methods inherited from class java.lang.Object

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

Constructor Details

Ctap2Session

public Ctap2Session(com.yubico.yubikit.core.smartcard.SmartCardConnection connection)
             throws IOException,
com.yubico.yubikit.core.application.CommandException

Throws:

IOException

com.yubico.yubikit.core.application.CommandException

Ctap2Session

public Ctap2Session(com.yubico.yubikit.core.smartcard.SmartCardConnection connection,
 @Nullable com.yubico.yubikit.core.smartcard.scp.ScpKeyParams scpKeyParams)
             throws IOException,
com.yubico.yubikit.core.application.CommandException

Throws:

IOException

com.yubico.yubikit.core.application.CommandException

Ctap2Session

public Ctap2Session(com.yubico.yubikit.core.smartcard.SmartCardConnection connection,
 com.yubico.yubikit.core.Version version)
             throws IOException,
com.yubico.yubikit.core.application.CommandException

Throws:

IOException

com.yubico.yubikit.core.application.CommandException

Ctap2Session

public Ctap2Session(com.yubico.yubikit.core.smartcard.SmartCardConnection connection,
 com.yubico.yubikit.core.Version version,
 @Nullable com.yubico.yubikit.core.smartcard.scp.ScpKeyParams scpKeyParams)
             throws IOException,
com.yubico.yubikit.core.application.CommandException

Throws:

IOException

com.yubico.yubikit.core.application.CommandException

Ctap2Session

public Ctap2Session(com.yubico.yubikit.core.fido.FidoConnection connection)
             throws IOException,
com.yubico.yubikit.core.application.CommandException

Throws:

IOException

com.yubico.yubikit.core.application.CommandException

Method Details

makeCredential

public Ctap2Session.CredentialData makeCredential(byte[] clientDataHash,
 Map<String,?> rp,
 Map<String,?> user,
 List<Map<String,?>> pubKeyCredParams,
 @Nullable List<Map<String,?>> excludeList,
 @Nullable Map<String,?> extensions,
 @Nullable Map<String,?> options,
 byte @Nullable [] pinUvAuthParam,
 @Nullable Integer pinUvAuthProtocol,
 @Nullable Integer enterpriseAttestation,
 @Nullable com.yubico.yubikit.core.application.CommandState state)
                                           throws IOException,
com.yubico.yubikit.core.application.CommandException

This method is invoked by the host to request generation of a new credential in the authenticator.

Parameters:

clientDataHash - a SHA-256 hash of the clientDataJson

rp - a Map containing the RpEntity data

user - a Map containing the UserEntity data

pubKeyCredParams - a List of Maps containing the supported credential algorithms

excludeList - a List of Maps of already registered credentials

extensions - a Map of CTAP extension inputs

options - a Map of CTAP options

pinUvAuthParam - a byte array derived from a pinToken

pinUvAuthProtocol - the PIN protocol version used for the pinUvAuthParam

enterpriseAttestation - an enterprise attestation request

state - an optional state object to cancel a request and handle keepalive signals

Returns:

a new credential

Throws:

IOException - A communication error in the transport layer.

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

See Also:

• authenticatorMakeCredential

getAssertions

public List<Ctap2Session.AssertionData> getAssertions(String rpId,
 byte[] clientDataHash,
 @Nullable List<Map<String,?>> allowList,
 @Nullable Map<String,?> extensions,
 @Nullable Map<String,?> options,
 byte @Nullable [] pinUvAuthParam,
 @Nullable Integer pinUvAuthProtocol,
 @Nullable com.yubico.yubikit.core.application.CommandState state)
                                               throws IOException,
com.yubico.yubikit.core.application.CommandException

This method is used by a host to request cryptographic proof of user authentication as well as user consent to a given transaction, using a previously generated credential that is bound to the authenticator and relying party identifier.

Parameters:

rpId - the RP ID for the request

clientDataHash - a SHA-256 hash of the clientDataJson

allowList - a List of Maps of already registered credentials

extensions - a Map of CTAP extension inputs

options - a Map of CTAP options

pinUvAuthParam - a byte array derived from a pinToken

pinUvAuthProtocol - the PIN protocol version used for the pinUvAuthParam

state - used to cancel a request and handle keepalive signals

Returns:

a List of available assertions

Throws:

IOException - A communication error in the transport layer.

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

See Also:

• authenticatorGetAssertion
• authenticatorGetNextAssertion

getInfo

public Ctap2Session.InfoData getInfo()
                              throws IOException,
com.yubico.yubikit.core.application.CommandException

Using this method, platforms can request that the authenticator report a list of its supported protocol versions and extensions, its AAGUID, and other aspects of its overall capabilities. Platforms should use this information to tailor their command parameters choices.

Returns:

an InfoData object with information about the YubiKey

Throws:

IOException - A communication error in the transport layer.

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

See Also:

• authenticatorGetInfo

reset

public void reset(@Nullable com.yubico.yubikit.core.application.CommandState state)
           throws IOException,
com.yubico.yubikit.core.application.CommandException

Issues a CTAP2 reset, which will delete/invalidate all FIDO credentials.

NOTE: Over USB this command must be sent within a few seconds of plugging the YubiKey in, and it requires touch confirmation.

Parameters:

state - if needed, the state to provide control over the ongoing operation

Throws:

IOException - A communication error in the transport layer.

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

See Also:

• authenticatorReset

selection

public void selection(@Nullable com.yubico.yubikit.core.application.CommandState state)
               throws IOException,
com.yubico.yubikit.core.application.CommandException

This command allows the platform to let a user select a certain authenticator by asking for user presence.

Throws:

IOException - A communication error in the transport layer.

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

See Also:

• authenticatorSelection

largeBlobs

public Map<Integer,?> largeBlobs(int offset,
 @Nullable Integer get,
 byte @Nullable [] set,
 @Nullable Integer length,
 byte @Nullable [] pinUvAuthParam,
 @Nullable Integer pinUvAuthProtocol)
                          throws IOException,
com.yubico.yubikit.core.application.CommandException

This command allows a platform to store a larger amount of information associated with a credential.

Parameters:

offset - the byte offset at which to read/write

get - the number of bytes requested to read, must not be present if set is present

set - a fragment to write, must not be present if get is present

length - the total length of a write operation, present if, and only if, set is present and offset is zero

pinUvAuthParam - first 16 bytes of HMAC-SHA-256 of contents using pinUvAuthToken

pinUvAuthProtocol - PIN/UV protocol version chosen by the platform

Throws:

IOException - A communication error in the transport layer.

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

See Also:

• authenticatorLargeBlobs

config

public Map<Integer,?> config(byte subCommand,
 @Nullable Map<?,?> subCommandParams,
 @Nullable Integer pinUvAuthProtocol,
 byte @Nullable [] pinUvAuthParam)
                      throws IOException,
com.yubico.yubikit.core.application.CommandException

This command is used to configure various authenticator features through the use of its subcommands.

Note: Platforms MUST NOT invoke this command unless the authnrCfg option ID is present and true in the response to an authenticatorGetInfo command.

Parameters:

subCommand - the subCommand currently being requested

subCommandParams - a map of subCommands parameters

pinUvAuthProtocol - PIN/UV protocol version chosen by the platform

pinUvAuthParam - first 16 bytes of HMAC-SHA-256 of contents using pinUvAuthToken

Throws:

IOException - A communication error in the transport layer.

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

See Also:

• authenticatorConfig

close

public void close()
           throws IOException

Specified by:

close in interface AutoCloseable

Specified by:

close in interface Closeable

Overrides:

close in class Ctap1Session

Throws:

IOException

getVersion

public com.yubico.yubikit.core.Version getVersion()

Description copied from class: Ctap1Session

Gets the version of the YubiKey firmware.

For USB connections, this returns the version from the HID device. For NFC connections, version information is not available and returns 0.0.0.

Overrides:

getVersion in class Ctap1Session

Returns:

the YubiKey firmware version

getCachedInfo

public Ctap2Session.InfoData getCachedInfo()