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

  • 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

      @Deprecated public void authenticate(ManagementKeyType keyType, byte[] managementKey) throws IOException, com.yubico.yubikit.core.smartcard.ApduException, com.yubico.yubikit.core.application.BadResponseException
      Deprecated.
      Replaced by authenticate(byte[])
      Authenticate with the Management Key.
      Parameters:
      keyType - the algorithm used for the management key The default key uses TDES
      managementKey - management key as byte array The default 3DES/AES192 management key (9B) is 010203040506070801020304050607080102030405060708.
      Throws:
      IllegalArgumentException - in case of wrong keyType
      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

    • 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

    • sign

      @Deprecated public byte[] sign(Slot slot, KeyType keyType, byte[] message, Signature algorithm) throws IOException, com.yubico.yubikit.core.smartcard.ApduException, com.yubico.yubikit.core.application.BadResponseException, NoSuchAlgorithmException
      Deprecated.
      Create a signature for a given message.

      The algorithm must be compatible with the given key type.

      DEPRECATED: Use the PivProvider JCA Security Provider instead.

      Parameters:
      slot - the slot containing the private key to use
      keyType - the type of the key stored in the slot
      message - the message to hash
      algorithm - the signing algorithm to use
      Returns:
      the signature
      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 - if the algorithm isn't supported

    • 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

    • decrypt

      @Deprecated public byte[] decrypt(Slot slot, byte[] cipherText, Cipher algorithm) throws IOException, com.yubico.yubikit.core.smartcard.ApduException, com.yubico.yubikit.core.application.BadResponseException, NoSuchAlgorithmException, NoSuchPaddingException, BadPaddingException
      Deprecated.
      Decrypt an RSA-encrypted message.

      DEPRECATED: Use the PivProvider JCA Security Provider instead.

      Parameters:
      slot - the slot containing the RSA private key to use
      cipherText - the encrypted payload to decrypt
      algorithm - the algorithm used for encryption
      Returns:
      the decrypted plaintext
      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
      NoSuchPaddingException - in case the padding algorithm isn't supported
      NoSuchAlgorithmException - in case the algorithm isn't supported
      BadPaddingException - in case of a padding error

    • calculateSecret

      @Deprecated public byte[] calculateSecret(Slot slot, ECPublicKey peerPublicKey) throws IOException, com.yubico.yubikit.core.smartcard.ApduException, com.yubico.yubikit.core.application.BadResponseException
      Deprecated.
      Perform an ECDH operation with a given public key to compute a shared secret.
      Parameters:
      slot - the slot containing the private EC key
      peerPublicKey - the peer public key 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

    • calculateSecret

      @Deprecated public byte[] calculateSecret(Slot slot, ECPoint peerPublicKey) throws IOException, com.yubico.yubikit.core.smartcard.ApduException, com.yubico.yubikit.core.application.BadResponseException
      Deprecated.
      Perform an ECDH operation with a given public key to compute a shared secret.
      Parameters:
      slot - the slot containing the private EC key
      peerPublicKey - the peer public key 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

    • 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(com.yubico.yubikit.piv.ManagementKeyType, 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, 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
      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

      @Nullable public byte[] 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
      InvalidPinException - in case of unsuccessful match
      IllegalArgumentException - in case of invalid key configuration
      UnsupportedOperationException - in case bio specific verification is not supported
      com.yubico.yubikit.core.application.InvalidPinException

    • 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
      InvalidPinException - in case of unsuccessful match
      IllegalArgumentException - in case of invalid key configuration
      UnsupportedOperationException - in case bio specific verification is not supported
      com.yubico.yubikit.core.application.InvalidPinException

    • 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, 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
      InvalidPinException - in case if pin is invalid

    • changePuk

      public void changePuk(char[] oldPuk, char[] newPuk) throws IOException, com.yubico.yubikit.core.smartcard.ApduException, 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
      InvalidPinException - in case if puk is invalid

    • unblockPin

      public void unblockPin(char[] puk, char[] newPin) throws IOException, com.yubico.yubikit.core.smartcard.ApduException, 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
      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(com.yubico.yubikit.piv.ManagementKeyType, 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

    • 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(com.yubico.yubikit.piv.ManagementKeyType, 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(com.yubico.yubikit.piv.ManagementKeyType, 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(com.yubico.yubikit.piv.ManagementKeyType, byte[]) This method requires key to be generated on slot generateKey(Slot, KeyType, PinPolicy, TouchPolicy)

      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(com.yubico.yubikit.piv.ManagementKeyType, 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(com.yubico.yubikit.piv.ManagementKeyType, 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

    • generateKey

      @Deprecated public PublicKey generateKey(Slot slot, KeyType keyType, PinPolicy pinPolicy, TouchPolicy touchPolicy) throws IOException, com.yubico.yubikit.core.smartcard.ApduException, com.yubico.yubikit.core.application.BadResponseException
      Deprecated.
      use generateKeyValues instead, which will replace this method in the next major version release
      Generates a new key pair within the YubiKey. This method requires verification with pin verifyPin(char[])} and authentication with management key authenticate(com.yubico.yubikit.piv.ManagementKeyType, 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.

      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(com.yubico.yubikit.piv.ManagementKeyType, 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

    • putKey

      @Deprecated public KeyType putKey(Slot slot, PrivateKey key, PinPolicy pinPolicy, TouchPolicy touchPolicy) throws IOException, com.yubico.yubikit.core.smartcard.ApduException
      Deprecated.
      use putKey(Slot, PrivateKeyValues, PinPolicy, TouchPolicy) instead
      Import a private key into a slot. This method requires authentication authenticate(com.yubico.yubikit.piv.ManagementKeyType, 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(com.yubico.yubikit.piv.ManagementKeyType, 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:

    • 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(com.yubico.yubikit.piv.ManagementKeyType, byte[]).
      Parameters:
      slot - Slot to delete key from. It is not possible to delete key from Slot.ATTESTATION
      Throws:
      IOException - in case of connection error
      com.yubico.yubikit.core.smartcard.ApduException - in case of an error response from the YubiKey
      See Also:

    • 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, @Nullable byte[] 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