Package com.yubico.yubikit.piv

Class PivSession

java.lang.Object

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

com.yubico.yubikit.piv.PivSession

All Implemented Interfaces:

Closeable, AutoCloseable

public class PivSession
extends com.yubico.yubikit.core.application.ApplicationSession<PivSession>

Personal Identity Verification (PIV) interface specified in NIST SP 800-73 document "Cryptographic Algorithms and Key Sizes for PIV".

This enables you to perform RSA or ECC sign/decrypt operations using a private key stored on the smart card, through common transports like PKCS#11.

Field Summary

Fields

Modifier and Type	Field	Description
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_AES_KEY	Support for AES management keys.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_ATTESTATION	Support for Attestation of generated keys.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_CV25519	Support for the curve 25519 keys.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_METADATA	Support for getting PIN/PUK/Management key and private key metadata.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_MOVE_KEY	Support for moving and deleting keys.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_P384	Support for the NIST P-348 elliptic curve.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_RSA_GENERATION	Support for generating RSA keys.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_RSA3072_RSA4096	Support for larger RSA key sizes.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_SERIAL	Support for reading the YubiKey serial number.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_TOUCH_CACHED	Support for the CACHED Touch policy.
static final com.yubico.yubikit.core.application.Feature<PivSession>	FEATURE_USAGE_POLICY	Support for custom PIN or Touch policy.

Constructor Summary

Constructors

Constructor	Description
PivSession(com.yubico.yubikit.core.smartcard.SmartCardConnection connection)	Create new instance of PivSession and selects the application for use
PivSession(com.yubico.yubikit.core.smartcard.SmartCardConnection connection, @Nullable com.yubico.yubikit.core.smartcard.scp.ScpKeyParams scpKeyParams)	Create new instance of PivSession and selects the application for use

Method Summary

Modifier and Type	Method	Description
X509Certificate	attestKey(Slot slot)	Creates an attestation certificate for a private key which was generated on the YubiKey.
void	authenticate(byte[] managementKey)	Authenticate with the Management Key.
byte[]	calculateSecret(Slot slot, com.yubico.yubikit.core.keys.PublicKeyValues peerPublicKeyValues)	Perform an ECDH operation with a given public key to compute a shared secret.
void	changePin(char[] oldPin, char[] newPin)	Change PIN.
void	changePuk(char[] oldPuk, char[] newPuk)	Change PUK.
void	checkKeySupport(KeyType keyType, PinPolicy pinPolicy, TouchPolicy touchPolicy, boolean generate)	Checks if a given firmware version of YubiKey supports a specific key type with given policies.
void	close()
void	deleteCertificate(Slot slot)	Deletes a certificate from the YubiKey.
void	deleteKey(Slot slot)	Delete key from slot.
com.yubico.yubikit.core.keys.PublicKeyValues	generateKeyValues(Slot slot, KeyType keyType, PinPolicy pinPolicy, TouchPolicy touchPolicy)	Generates a new key pair within the YubiKey.
BioMetadata	getBioMetadata()	Reads metadata specific to YubiKey Bio multi-protocol.
X509Certificate	getCertificate(Slot slot)	Reads the X.509 certificate stored in a slot.
ManagementKeyMetadata	getManagementKeyMetadata()	Reads metadata about the card management key.
ManagementKeyType	getManagementKeyType()	Get card management key type.
byte[]	getObject(int objectId)	Read a data object from the YubiKey.
int	getPinAttempts()	Receive number of attempts left for PIN from YubiKey
PinMetadata	getPinMetadata()	Reads metadata about the PIN, such as total number of retries, attempts left, and if the PIN has been changed from the default value.
PinMetadata	getPukMetadata()	Reads metadata about the PUK, such as total number of retries, attempts left, and if the PUK has been changed from the default value.
int	getSerialNumber()	Get the serial number from the YubiKey.
SlotMetadata	getSlotMetadata(Slot slot)	Reads metadata about the private key stored in a slot.
com.yubico.yubikit.core.Version	getVersion()	Get the PIV application version from the YubiKey.
void	moveKey(Slot sourceSlot, Slot destinationSlot)	Move key from one slot to another.
void	putCertificate(Slot slot, X509Certificate certificate)	Writes an uncompressed X.509 certificate to a slot on the YubiKey.
void	putCertificate(Slot slot, X509Certificate certificate, boolean compress)	Writes an X.509 certificate to a slot on the YubiKey.
KeyType	putKey(Slot slot, com.yubico.yubikit.core.keys.PrivateKeyValues key, PinPolicy pinPolicy, TouchPolicy touchPolicy)	Import a private key into a slot.
void	putObject(int objectId, byte @Nullable [] objectData)	Write a data object to the YubiKey.
byte[]	rawSignOrDecrypt(Slot slot, KeyType keyType, byte[] payload)	Performs a private key operation on the given payload.
void	reset()	Resets the application to just-installed state.
void	setManagementKey(ManagementKeyType keyType, byte[] managementKey, boolean requireTouch)	Change management key This method requires authentication authenticate(byte[]).
void	setPinAttempts(int pinAttempts, int pukAttempts)	Set the number of retries available for PIN and PUK entry.
void	unblockPin(char[] puk, char[] newPin)	Reset a blocked PIN to a new value using the PUK.
void	verifyPin(char[] pin)	Authenticate with pin 0 - PIN authentication blocked.
void	verifyTemporaryPin(byte[] pin)	Authenticate YubiKey Bio multi-protocol with temporary PIN.
byte @Nullable []	verifyUv(boolean requestTemporaryPin, boolean checkOnly)	Authenticate with YubiKey Bio multi-protocol capabilities.

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

Field Details

FEATURE_P384

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_P384

Support for the NIST P-348 elliptic curve.

FEATURE_USAGE_POLICY

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_USAGE_POLICY

Support for custom PIN or Touch policy.

FEATURE_TOUCH_CACHED

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_TOUCH_CACHED

Support for the CACHED Touch policy.

FEATURE_ATTESTATION

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_ATTESTATION

Support for Attestation of generated keys.

FEATURE_SERIAL

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_SERIAL

Support for reading the YubiKey serial number.

FEATURE_METADATA

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_METADATA

Support for getting PIN/PUK/Management key and private key metadata.

FEATURE_AES_KEY

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_AES_KEY

Support for AES management keys.

FEATURE_RSA_GENERATION

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_RSA_GENERATION

Support for generating RSA keys.

FEATURE_MOVE_KEY

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_MOVE_KEY

Support for moving and deleting keys.

FEATURE_CV25519

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_CV25519

Support for the curve 25519 keys.

FEATURE_RSA3072_RSA4096

public static final com.yubico.yubikit.core.application.Feature<PivSession> FEATURE_RSA3072_RSA4096

Support for larger RSA key sizes.

Constructor Details

PivSession

public PivSession(com.yubico.yubikit.core.smartcard.SmartCardConnection connection)
           throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.ApplicationNotAvailableException

Create new instance of PivSession and selects the application for use

Parameters:

connection - connection with YubiKey

Throws:

IOException - in case of communication error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.ApplicationNotAvailableException - if the application is missing or disabled

PivSession

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

Create new instance of PivSession and selects the application for use

Parameters:

connection - connection with YubiKey

Throws:

IOException - in case of communication error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.ApplicationNotAvailableException - if the application is missing or disabled

Method Details

close

public void close()
           throws IOException

Throws:

IOException

getVersion

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

Get the PIV application version from the YubiKey. For YubiKey 4 and later this will match the YubiKey firmware version.

Specified by:

getVersion in class com.yubico.yubikit.core.application.ApplicationSession<PivSession>

Returns:

application version

getSerialNumber

public int getSerialNumber()
                    throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Get the serial number from the YubiKey. NOTE: This requires the SERIAL_API_VISIBLE flag to be set on one of the YubiOTP slots (it is set by default).

This functionality requires support for FEATURE_SERIAL, available on YubiKey 5 or later.

Returns:

The YubiKey's serial number

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

reset

public void reset()
           throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Resets the application to just-installed state.

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

authenticate

public void authenticate(byte[] managementKey)
                  throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.BadResponseException

Authenticate with the Management Key.

Parameters:

managementKey - management key as byte array The default 3DES/AES192 management key (9B) is 010203040506070801020304050607080102030405060708.

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.BadResponseException - in case of incorrect YubiKey response

rawSignOrDecrypt

public byte[] rawSignOrDecrypt(Slot slot,
 KeyType keyType,
 byte[] payload)
                        throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.BadResponseException

Performs a private key operation on the given payload. Any hashing and/or padding required should already be done prior to calling this method.

More commonly, the JCA classes provided should be used instead of directly calling this.

Parameters:

slot - the slot containing the private key to use

keyType - the type of the key stored in the slot

payload - the data to operate on

Returns:

the result of the operation

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.BadResponseException - in case of incorrect YubiKey response

calculateSecret

public byte[] calculateSecret(Slot slot,
 com.yubico.yubikit.core.keys.PublicKeyValues peerPublicKeyValues)
                       throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.BadResponseException,
NoSuchAlgorithmException

Perform an ECDH operation with a given public key to compute a shared secret.

Parameters:

slot - the slot containing the private EC key

peerPublicKeyValues - the peer public key values for the operation

Returns:

the shared secret, comprising the x-coordinate of the ECDH result point.

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.BadResponseException - in case of incorrect YubiKey response

NoSuchAlgorithmException - in case of unsupported PublicKey type

setManagementKey

public void setManagementKey(ManagementKeyType keyType,
 byte[] managementKey,
 boolean requireTouch)
                      throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Change management key This method requires authentication authenticate(byte[]).

Thi setting requireTouch=true requires support for FEATURE_USAGE_POLICY, available on YubiKey 4 or later.

Parameters:

managementKey - new value of management key

requireTouch - true to require touch for authentication

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

verifyPin

public void verifyPin(char[] pin)
               throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.InvalidPinException

Authenticate with pin 0 - PIN authentication blocked. Note: that 15 is the highest value that will be returned even if remaining tries is higher.

Parameters:

pin - string with pin (UTF-8) The default PIN code is 123456.

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.InvalidPinException - in case if pin is invalid

getBioMetadata

public BioMetadata getBioMetadata()
                           throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Reads metadata specific to YubiKey Bio multi-protocol.

Returns:

metadata about a slot

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

UnsupportedOperationException - in case the metadata cannot be retrieved

verifyUv

public byte @Nullable [] verifyUv(boolean requestTemporaryPin,
 boolean checkOnly)
                           throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.InvalidPinException

Authenticate with YubiKey Bio multi-protocol capabilities.

Before calling this method, clients must verify that the authenticator is bio-capable and not blocked for bio matching.

Parameters:

requestTemporaryPin - after successful match generate a temporary PIN

checkOnly - check verification state of biometrics, don't perform UV

Returns:

temporary pin if requestTemporaryPin is true, otherwise null.

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.InvalidPinException - in case of unsuccessful match

IllegalArgumentException - in case of invalid key configuration

UnsupportedOperationException - in case bio specific verification is not supported

verifyTemporaryPin

public void verifyTemporaryPin(byte[] pin)
                        throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.InvalidPinException

Authenticate YubiKey Bio multi-protocol with temporary PIN.

The PIN has to be generated by calling verifyUv(boolean, boolean) and is valid only for operations during this session and depending on slot PinPolicy.

Before calling this method, clients must verify that the authenticator is bio-capable and not blocked for bio matching.

Parameters:

pin - temporary pin

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.InvalidPinException - in case of unsuccessful match

IllegalArgumentException - in case of invalid key configuration

UnsupportedOperationException - in case bio specific verification is not supported

getPinAttempts

public int getPinAttempts()
                   throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Receive number of attempts left for PIN from YubiKey

NOTE: If this command is run in a session where the correct PIN has already been verified, the correct value will not be retrievable, and the value returned may be incorrect if the number of total attempts has been changed from the default.

Returns:

number of attempts left

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

changePin

public void changePin(char[] oldPin,
 char[] newPin)
               throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.InvalidPinException

Change PIN.

Parameters:

oldPin - old pin for verification

newPin - new pin to set

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.InvalidPinException - in case if pin is invalid

changePuk

public void changePuk(char[] oldPuk,
 char[] newPuk)
               throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.InvalidPinException

Change PUK.

Parameters:

oldPuk - old puk for verification

newPuk - new puk to set

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.InvalidPinException - in case if puk is invalid

unblockPin

public void unblockPin(char[] puk,
 char[] newPin)
                throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.InvalidPinException

Reset a blocked PIN to a new value using the PUK.

Parameters:

puk - puk for verification The default PUK code is 12345678.

newPin - new pin to set

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.InvalidPinException - in case if puk is invalid

setPinAttempts

public void setPinAttempts(int pinAttempts,
 int pukAttempts)
                    throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Set the number of retries available for PIN and PUK entry.

This method requires authentication authenticate(byte[]) and verification with pin verifyPin(char[])}.

Parameters:

pinAttempts - the number of attempts to allow for PIN entry before blocking the PIN

pukAttempts - the number of attempts to allow for PUK entry before blocking the PUK

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

getPinMetadata

public PinMetadata getPinMetadata()
                           throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Reads metadata about the PIN, such as total number of retries, attempts left, and if the PIN has been changed from the default value.

This functionality requires support for FEATURE_METADATA, available on YubiKey 5.3 or later.

Returns:

metadata about the PIN

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

getPukMetadata

public PinMetadata getPukMetadata()
                           throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Reads metadata about the PUK, such as total number of retries, attempts left, and if the PUK has been changed from the default value.

This functionality requires support for FEATURE_METADATA, available on YubiKey 5.3 or later.

Returns:

metadata about the PUK

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

getManagementKeyMetadata

public ManagementKeyMetadata getManagementKeyMetadata()
                                               throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Reads metadata about the card management key.

This functionality requires support for FEATURE_METADATA, available on YubiKey 5.3 or later.

Returns:

metadata about the card management key, such as the Touch policy and if the default value has been changed

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

getManagementKeyType

public ManagementKeyType getManagementKeyType()

Get card management key type.

getSlotMetadata

public SlotMetadata getSlotMetadata(Slot slot)
                             throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Reads metadata about the private key stored in a slot.

This functionality requires support for FEATURE_METADATA, available on YubiKey 5.3 or later.

Parameters:

slot - the slot to read metadata about

Returns:

metadata about a slot

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

getCertificate

public X509Certificate getCertificate(Slot slot)
                               throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.BadResponseException

Reads the X.509 certificate stored in a slot.

Parameters:

slot - Key reference '9A', '9C', '9D', or '9E'. Slot.

Returns:

certificate instance

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.BadResponseException - in case of incorrect YubiKey response or if a compressed certificate failed to decompress

putCertificate

public void putCertificate(Slot slot,
 X509Certificate certificate,
 boolean compress)
                    throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Writes an X.509 certificate to a slot on the YubiKey. This method requires authentication authenticate(byte[]).

Parameters:

slot - Key reference '9A', '9C', '9D', or '9E'. Slot.

certificate - certificate to write

compress - If true the certificate will be compressed before being stored on the YubiKey

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

putCertificate

public void putCertificate(Slot slot,
 X509Certificate certificate)
                    throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Writes an uncompressed X.509 certificate to a slot on the YubiKey. This method requires authentication authenticate(byte[]).

Parameters:

slot - Key reference '9A', '9C', '9D', or '9E'. Slot.

certificate - certificate to write

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

attestKey

public X509Certificate attestKey(Slot slot)
                          throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.BadResponseException

Creates an attestation certificate for a private key which was generated on the YubiKey.

This functionality requires support for FEATURE_ATTESTATION, available on YubiKey 4.3 or later.

A high level description of the thinking and how this can be used can be found at https://developers.yubico.com/PIV/Introduction/PIV_attestation.html Attestation works through a special key slot called "f9" this comes pre-loaded from factory with a key and cert signed by Yubico, but can be overwritten. After a key has been generated in a normal slot it can be attested by this special key

This method requires authentication authenticate(byte[]) This method requires key to be generated on slot.

Parameters:

slot - Key reference '9A', '9C', '9D', or '9E'. Slot.

Returns:

an attestation certificate for the key in the given slot

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.BadResponseException - in case of incorrect YubiKey response

deleteCertificate

public void deleteCertificate(Slot slot)
                       throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Deletes a certificate from the YubiKey. This method requires authentication authenticate(byte[])

Note: This does NOT delete any corresponding private key.

Parameters:

slot - Key reference '9A', '9C', '9D', or '9E'. Slot.

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

checkKeySupport

public void checkKeySupport(KeyType keyType,
 PinPolicy pinPolicy,
 TouchPolicy touchPolicy,
 boolean generate)

Checks if a given firmware version of YubiKey supports a specific key type with given policies.

Parameters:

keyType - the type of key to check

pinPolicy - the PIN policy to check

touchPolicy - the touch policy to check

generate - true to check if key generation is supported, false to check key import.

generateKeyValues

public com.yubico.yubikit.core.keys.PublicKeyValues generateKeyValues(Slot slot,
 KeyType keyType,
 PinPolicy pinPolicy,
 TouchPolicy touchPolicy)
                                                               throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.BadResponseException

Generates a new key pair within the YubiKey. This method requires verification with pin verifyPin(char[])} and authentication with management key authenticate(byte[]).

RSA key types require FEATURE_RSA_GENERATION, available on YubiKeys OTHER THAN 4.2.6-4.3.4. KeyType P348 requires FEATURE_P384, available on YubiKey 4 or later. PinPolicy or TouchPolicy other than default require FEATURE_USAGE_POLICY, available on YubiKey 4 or later. TouchPolicy.CACHED requires FEATURE_TOUCH_CACHED, available on YubiKey 4.3 or later.

NOTE: YubiKey FIPS does not allow RSA1024 nor PinProtocol.NEVER. NOTE: This method will be renamed to generateKey in the next major version release of this library.

Parameters:

slot - Key reference '9A', '9C', '9D', or '9E'. Slot.

keyType - which algorithm is used for key generation KeyType

pinPolicy - the PIN policy for using the private key

touchPolicy - the touch policy for using the private key

Returns:

the public key of the generated key pair

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.BadResponseException - in case of incorrect YubiKey response

putKey

public KeyType putKey(Slot slot,
 com.yubico.yubikit.core.keys.PrivateKeyValues key,
 PinPolicy pinPolicy,
 TouchPolicy touchPolicy)
               throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Import a private key into a slot. This method requires authentication authenticate(byte[]).

KeyType P348 requires FEATURE_P384, available on YubiKey 4 or later. PinPolicy or TouchPolicy other than default require FEATURE_USAGE_POLICY, available on YubiKey 4 or later.

NOTE: YubiKey FIPS does not allow RSA1024 nor PinProtocol.NEVER.

Parameters:

slot - Key reference '9A', '9C', '9D', or '9E'. Slot.

key - the private key to import

pinPolicy - the PIN policy for using the private key

touchPolicy - the touch policy for using the private key

Returns:

the KeyType value of the imported key

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

moveKey

public void moveKey(Slot sourceSlot,
 Slot destinationSlot)
             throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Move key from one slot to another. The source slot must not be Slot.ATTESTATION and the destination slot must be empty. This method requires authentication with management key authenticate(byte[]).

Parameters:

sourceSlot - Slot to move the key from

destinationSlot - Slot to move the key to

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

See Also:

• Slot

deleteKey

public void deleteKey(Slot slot)
               throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Delete key from slot. This method requires authentication with management key authenticate(byte[]).

Parameters:

slot - Slot to delete key from.

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

See Also:

• Slot

getObject

public byte[] getObject(int objectId)
                 throws IOException,
com.yubico.yubikit.core.smartcard.ApduException,
com.yubico.yubikit.core.application.BadResponseException

Read a data object from the YubiKey.

Parameters:

objectId - the ID of the object to read, see ObjectId.

Returns:

the stored data object contents

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey

com.yubico.yubikit.core.application.BadResponseException - in case of incorrect YubiKey response

putObject

public void putObject(int objectId,
 byte @Nullable [] objectData)
               throws IOException,
com.yubico.yubikit.core.smartcard.ApduException

Write a data object to the YubiKey.

Parameters:

objectId - the ID of the object to write, see ObjectId.

objectData - the data object contents to write

Throws:

IOException - in case of connection error

com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey