The Yubikey ISO7816 commands base class. Based on https://docs.yubico.com/yesdk/users-manual/application-oath/oath-commands.html / https://developers.yubico.com/OATH/YKOATH_Protocol.html for OATH and https://docs.yubico.com/yesdk/users-manual/application-otp/otp-commands.html for OTP. For FIPS-201 PIV features, please use FIPS201Commands instead. More...

#include <yubikeyiso7816commands.hpp>

Inheritance diagram for logicalaccess::YubikeyISO7816Commands:

Public Member Functions
	YubikeyISO7816Commands ()
	Constructor.

	YubikeyISO7816Commands (std::string ct)

virtual	~YubikeyISO7816Commands ()
	Destructor.

YubikeySelectResponse	selectYubikeyOATH () override
	Select the Yubikey OATH application.

ByteVector	selectYubikeyOTP () override
	Select the old Yubikey OTP application.

ByteVector	otp_getResponse (YubikeySlot slot, const ByteVector &challenge) override
	Challenge/Response operation.

ByteVector	otp_getSerialNumber () override
	Reads the serial number of the YubiKey if it is allowed by the configuration. Note that certain keys, such as the Security Key by Yubico, do not have serial numbers.

std::vector< TLVPtr >	otp_getDeviceInfo () override
	Reads configuration and metadata information about the YubiKey. Similar commands exist in other applications. The Command APDU may be different, however the data in the Response APDU will be of identical format.

bool	otp_queryFIPSMode () override
	Determines whether or not the device is loaded with FIPS capable firmware, as well as if the key is currently in a FIPS compliant state.

void	oath_put (const ByteVector &name, YubikeyHMAC algorithm, uint8_t digits, const ByteVector &key, YubikeyProperty property=PROP_NONE, const ByteVector &imf=ByteVector()) override
	Adds a new (or overwrites) OATH credential.

void	oath_delete (const ByteVector &name) override
	Deletes an existing credential.

void	oath_setCode (YubikeyHMAC algorithm, const ByteVector &key, const ByteVector &challenge) override
	Configures Authentication. If length 0 is sent, authentication is removed. The key to be set is expected to be a user-supplied UTF-8 encoded password passed through 1000 rounds of PBKDF2 with the ID from select used as salt. 16 bytes of that are used. When configuring authentication you are required to send an 8 byte challenge and one authentication-response with that key, in order to confirm that the application and the host software can calculate the same response for that key.

std::vector< YubikeyListItem >	oath_list () override
	Lists configured credentials.

void	oath_reset () override
	Resets the application to just-installed state.

YubikeyCalculateResponse	oath_calculate (const ByteVector &name, const ByteVector &challenge, bool truncate=false) override
	Performs CALCULATE for one named credential.

ByteVector	oath_validate (const ByteVector &challenge, const ByteVector &response) override
	Validates authentication (mutually). The challenge for this comes from the SELECT command. The response if computed by performing the correct HMAC function of that challenge with the correct key. A new challenge is then sent to the application, together with the response. The application will then respond with a similar calculation that the host software can verify.

std::vector< YubikeyCalculateResponse >	oath_calculateAll (const ByteVector &challenge, bool truncate) override
	Performs CALCULATE for all available credentials, returns name + response for TOTP and just name for HOTP and credentials requiring touch.

ByteVector	oath_sendRemainingInstruction () override
	Gets remaining data if everything didn’t fit in previous response (response code was 61xx).

std::shared_ptr< ISO7816Commands >	getISO7816Commands () const override

std::shared_ptr< ISO7816ReaderCardAdapter >	getISO7816ReaderCardAdapter () const
	Get the ISO7816 reader/card adapter.

Public Member Functions inherited from logicalaccess::YubikeyCommands
	YubikeyCommands ()
	Constructor.

	YubikeyCommands (std::string cmdtype)
	Constructor.

virtual YubikeySelectResponse	selectYubikeyOATH ()=0
	Select the Yubikey OATH application.

virtual ByteVector	selectYubikeyOTP ()=0
	Select the old Yubikey OTP application.

virtual ByteVector	otp_getResponse (YubikeySlot slot, const ByteVector &challenge)=0
	Challenge/Response operation.

virtual ByteVector	otp_getSerialNumber ()=0
	Reads the serial number of the YubiKey if it is allowed by the configuration. Note that certain keys, such as the Security Key by Yubico, do not have serial numbers.

virtual std::vector< TLVPtr >	otp_getDeviceInfo ()=0
	Reads configuration and metadata information about the YubiKey. Similar commands exist in other applications. The Command APDU may be different, however the data in the Response APDU will be of identical format.

virtual bool	otp_queryFIPSMode ()=0
	Determines whether or not the device is loaded with FIPS capable firmware, as well as if the key is currently in a FIPS compliant state.

virtual void	oath_put (const ByteVector &name, YubikeyHMAC algorithm, uint8_t digits, const ByteVector &key, YubikeyProperty property=PROP_NONE, const ByteVector &imf=ByteVector())=0
	Adds a new (or overwrites) OATH credential.

virtual void	oath_delete (const ByteVector &name)=0
	Deletes an existing credential.

virtual void	oath_setCode (YubikeyHMAC algorithm, const ByteVector &key, const ByteVector &challenge)=0
	Configures Authentication. If length 0 is sent, authentication is removed. The key to be set is expected to be a user-supplied UTF-8 encoded password passed through 1000 rounds of PBKDF2 with the ID from select used as salt. 16 bytes of that are used. When configuring authentication you are required to send an 8 byte challenge and one authentication-response with that key, in order to confirm that the application and the host software can calculate the same response for that key.

virtual std::vector< YubikeyListItem >	oath_list ()=0
	Lists configured credentials.

virtual void	oath_reset ()=0
	Resets the application to just-installed state.

virtual YubikeyCalculateResponse	oath_calculate (const ByteVector &name, const ByteVector &challenge, bool truncate=false)=0
	Performs CALCULATE for one named credential.

virtual ByteVector	oath_validate (const ByteVector &challenge, const ByteVector &response)=0
	Validates authentication (mutually). The challenge for this comes from the SELECT command. The response if computed by performing the correct HMAC function of that challenge with the correct key. A new challenge is then sent to the application, together with the response. The application will then respond with a similar calculation that the host software can verify.

virtual std::vector< YubikeyCalculateResponse >	oath_calculateAll (const ByteVector &challenge, bool truncate=false)=0
	Performs CALCULATE for all available credentials, returns name + response for TOTP and just name for HOTP and credentials requiring touch.

virtual ByteVector	oath_sendRemainingInstruction ()=0
	Gets remaining data if everything didn’t fit in previous response (response code was 61xx).

virtual std::shared_ptr< ISO7816Commands >	getISO7816Commands () const =0

Public Member Functions inherited from logicalaccess::Commands
	Commands ()=delete
	Constructor.

virtual	~Commands ()

std::shared_ptr< Chip >	getChip () const override
	Get the chip.

virtual void	setChip (std::shared_ptr< Chip > chip)
	Set the chip.

std::shared_ptr< ReaderCardAdapter >	getReaderCardAdapter () const override
	Get the reader/card adapter.

virtual void	setReaderCardAdapter (std::shared_ptr< ReaderCardAdapter > adapter)
	Set the reader/card adapter.

virtual const std::string &	getCmdType () const
	Get the cmd name.

virtual void	setCmdType (const std::string &command_type)
	Set the cmd name.

Public Member Functions inherited from logicalaccess::ICommands
virtual	~ICommands ()=default

virtual std::shared_ptr< Chip >	getChip () const =0
	Get the chip.

virtual std::shared_ptr< ReaderCardAdapter >	getReaderCardAdapter () const =0
	Get the reader/card adapter.

Additional Inherited Members
Protected Member Functions inherited from logicalaccess::Commands
	Commands (std::string commandtype)
	Constructor.

Protected Attributes inherited from logicalaccess::Commands
std::shared_ptr< ReaderCardAdapter >	d_readerCardAdapter
	The reader/card adapter.

std::weak_ptr< Chip >	d_chip
	The chip.

std::string	d_commandtype
	The command type.

Detailed Description

The Yubikey ISO7816 commands base class. Based on https://docs.yubico.com/yesdk/users-manual/application-oath/oath-commands.html / https://developers.yubico.com/OATH/YKOATH_Protocol.html for OATH and https://docs.yubico.com/yesdk/users-manual/application-otp/otp-commands.html for OTP. For FIPS-201 PIV features, please use FIPS201Commands instead.

Constructor & Destructor Documentation

◆ YubikeyISO7816Commands() [1/2]

logicalaccess::YubikeyISO7816Commands::YubikeyISO7816Commands ( )

Constructor.

◆ YubikeyISO7816Commands() [2/2]

logicalaccess::YubikeyISO7816Commands::YubikeyISO7816Commands ( std::string ct )

explicit

◆ ~YubikeyISO7816Commands()

logicalaccess::YubikeyISO7816Commands::~YubikeyISO7816Commands ( )

virtual

Destructor.

Member Function Documentation

◆ getISO7816Commands()

std::shared_ptr< ISO7816Commands > logicalaccess::YubikeyISO7816Commands::getISO7816Commands ( ) const

inlineoverridevirtual

Implements logicalaccess::YubikeyCommands.

◆ getISO7816ReaderCardAdapter()

std::shared_ptr< ISO7816ReaderCardAdapter > logicalaccess::YubikeyISO7816Commands::getISO7816ReaderCardAdapter ( ) const

inline

Get the ISO7816 reader/card adapter.

Returns: The ISO7816 reader/card adapter.

◆ oath_calculate()

YubikeyCalculateResponse logicalaccess::YubikeyISO7816Commands::oath_calculate	(	const ByteVector &	name,
		const ByteVector &	challenge,
		bool	truncate = `false`
	)

overridevirtual

Performs CALCULATE for one named credential.

Parameters

name	The credential name.
challenge	The challenge.
truncate	Truncate the response, full response otherwise.

Returns: The calculate response.

Implements logicalaccess::YubikeyCommands.

◆ oath_calculateAll()

std::vector< YubikeyCalculateResponse > logicalaccess::YubikeyISO7816Commands::oath_calculateAll	(	const ByteVector &	challenge,
		bool	truncate
	)

overridevirtual

Performs CALCULATE for all available credentials, returns name + response for TOTP and just name for HOTP and credentials requiring touch.

Parameters

challenge	The challenge.
truncate	Truncate the response, full response otherwise.

Returns: The calculate responses.

Implements logicalaccess::YubikeyCommands.

◆ oath_delete()

void logicalaccess::YubikeyISO7816Commands::oath_delete ( const ByteVector & name )

overridevirtual

Deletes an existing credential.

Parameters

name	The credential name to delete.

Implements logicalaccess::YubikeyCommands.

◆ oath_list()

std::vector< YubikeyListItem > logicalaccess::YubikeyISO7816Commands::oath_list ( )

overridevirtual

Lists configured credentials.

Returns: The credentials lists.

Implements logicalaccess::YubikeyCommands.

◆ oath_put()

void logicalaccess::YubikeyISO7816Commands::oath_put	(	const ByteVector &	name,
		YubikeyHMAC	algorithm,
		uint8_t	digits,
		const ByteVector &	key,
		YubikeyProperty	property = `PROP_NONE`,
		const ByteVector &	imf = `ByteVector()`
	)

overridevirtual

Adds a new (or overwrites) OATH credential.

Parameters

name	The credential name.
algorithm	The HMAC algorithm.
digits	Number of digits in OATH code.
key	The HMAC key.
property	OATH properties.
imf	IMF (only valid for HOTP).

Implements logicalaccess::YubikeyCommands.

◆ oath_reset()

void logicalaccess::YubikeyISO7816Commands::oath_reset ( )

overridevirtual

Resets the application to just-installed state.

Implements logicalaccess::YubikeyCommands.

◆ oath_sendRemainingInstruction()

ByteVector logicalaccess::YubikeyISO7816Commands::oath_sendRemainingInstruction ( )

overridevirtual

Gets remaining data if everything didn’t fit in previous response (response code was 61xx).

Returns: Continued data where previous command left off.

Implements logicalaccess::YubikeyCommands.

◆ oath_setCode()

void logicalaccess::YubikeyISO7816Commands::oath_setCode	(	YubikeyHMAC	algorithm,
		const ByteVector &	key,
		const ByteVector &	challenge
	)

overridevirtual

Configures Authentication. If length 0 is sent, authentication is removed. The key to be set is expected to be a user-supplied UTF-8 encoded password passed through 1000 rounds of PBKDF2 with the ID from select used as salt. 16 bytes of that are used. When configuring authentication you are required to send an 8 byte challenge and one authentication-response with that key, in order to confirm that the application and the host software can calculate the same response for that key.

Parameters

algorithm	The HMAC algorithm to use.
key	The HMAC key.
challenge	The challenge.

Implements logicalaccess::YubikeyCommands.

◆ oath_validate()

ByteVector logicalaccess::YubikeyISO7816Commands::oath_validate	(	const ByteVector &	challenge,
		const ByteVector &	response
	)

overridevirtual

Validates authentication (mutually). The challenge for this comes from the SELECT command. The response if computed by performing the correct HMAC function of that challenge with the correct key. A new challenge is then sent to the application, together with the response. The application will then respond with a similar calculation that the host software can verify.

Parameters

challenge	The challenge.
challenge	The host calculated response.

Returns: The calculate response.

Implements logicalaccess::YubikeyCommands.

◆ otp_getDeviceInfo()

std::vector< TLVPtr > logicalaccess::YubikeyISO7816Commands::otp_getDeviceInfo ( )

overridevirtual

Reads configuration and metadata information about the YubiKey. Similar commands exist in other applications. The Command APDU may be different, however the data in the Response APDU will be of identical format.

Returns: The device information.

Implements logicalaccess::YubikeyCommands.

◆ otp_getResponse()

ByteVector logicalaccess::YubikeyISO7816Commands::otp_getResponse	(	YubikeySlot	slot,
		const ByteVector &	challenge
	)

overridevirtual

Challenge/Response operation.

Parameters

slot	Target slot.
challenge	Challenge to transmit.

Returns: The response.

Implements logicalaccess::YubikeyCommands.

◆ otp_getSerialNumber()

ByteVector logicalaccess::YubikeyISO7816Commands::otp_getSerialNumber ( )

overridevirtual

Reads the serial number of the YubiKey if it is allowed by the configuration. Note that certain keys, such as the Security Key by Yubico, do not have serial numbers.

Returns: The Yubikey serial number.

Implements logicalaccess::YubikeyCommands.

◆ otp_queryFIPSMode()

bool logicalaccess::YubikeyISO7816Commands::otp_queryFIPSMode ( )

overridevirtual

Determines whether or not the device is loaded with FIPS capable firmware, as well as if the key is currently in a FIPS compliant state.

Returns: True if FIPS compliant, false otherwise.

Remarks: Just because a key may be branded FIPS or have FIPS capable firmware loaded, does not mean that the YubiKey is FIPS compliant. Configurations on the key need to be locked or otherwise protected in order to claim compliant behavior.

Implements logicalaccess::YubikeyCommands.

◆ selectYubikeyOATH()

YubikeySelectResponse logicalaccess::YubikeyISO7816Commands::selectYubikeyOATH ( )

overridevirtual

Select the Yubikey OATH application.

Returns: A challenge is returned if the authentication object is set. In that case an authentication is required for all commands except VALIDATE and RESET.

Implements logicalaccess::YubikeyCommands.

◆ selectYubikeyOTP()

ByteVector logicalaccess::YubikeyISO7816Commands::selectYubikeyOTP ( )

overridevirtual

Select the old Yubikey OTP application.

Returns: A challenge is returned.

Implements logicalaccess::YubikeyCommands.

The documentation for this class was generated from the following files:

C:/dev/lla/liblogicalaccess/plugins/logicalaccess/plugins/readers/iso7816/commands/yubikeyiso7816commands.hpp
C:/dev/lla/liblogicalaccess/plugins/logicalaccess/plugins/readers/iso7816/commands/yubikeyiso7816commands.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ YubikeyISO7816Commands() [1/2]

◆ YubikeyISO7816Commands() [2/2]

◆ ~YubikeyISO7816Commands()

Member Function Documentation

◆ getISO7816Commands()

◆ getISO7816ReaderCardAdapter()

◆ oath_calculate()

◆ oath_calculateAll()

◆ oath_delete()

◆ oath_list()

◆ oath_put()

◆ oath_reset()

◆ oath_sendRemainingInstruction()

◆ oath_setCode()

◆ oath_validate()

◆ otp_getDeviceInfo()

◆ otp_getResponse()

◆ otp_getSerialNumber()

◆ otp_queryFIPSMode()

◆ selectYubikeyOATH()

◆ selectYubikeyOTP()