PivSession Class

Namespace: Yubico.YubiKey.Piv Assembly: Yubico.YubiKey.dll

Create a session and perform PIV operations within that session.

C#

public sealed class PivSession : Object, IDisposable

Inheritance System.Object PivSession

Implements

System.IDisposable

Remarks

When you need to perform PIV operations, instantiate this class to create a session, then call on the methods in the class.

Generally you will choose the YubiKey to use by building an instance of IYubiKeyDevice. This object will represent the actual hardware.

  IYubiKeyDevice SelectYubiKey()
  {
      IEnumerable<IYubiKeyDevice> yubiKeyList = YubiKey.FindAll();
      foreach (IYubiKeyDevice current in yubiKeyList)
      {
          /* determine which YubiKey to use */
          if(selected)
          {
              return current;
          }
      }
  }

Once you have the YubiKey to use, you will build an instance of this PivSession class to represent the PIV application on the hardware. Because this class implements IDisposable, use the using keyword. For example,

    IYubiKeyDevice yubiKeyToUse = SelectYubiKey();
    using (var piv = new PivSession(yubiKeyToUse))
    {
        /* Perform PIV operations. */
    }

If this class is used as part of a using expression, when the session goes out of scope, the Dispose method will be called to dispose the active PIV session, clearing any authenticated state, and ultimately releasing the connection to the YubiKey.

Note that while a session is open, any management key authentication and PIN verification will be active. That is, you need to authenticate the management key or verify the PIN only once per session. Touch might be needed more than once.

There are some exceptions to the "verify the PIN once per session" rule. For example, to change a PIN, you need to enter the current and new PIN, even if the current PIN has been verified. The documentation for each method in this class will indicate if the PIN is needed, and if so, must it be verified or entered. See also the User's Manual entries on the PIV PIN, PUK, and Management Key and PIV commands access control.

Note that PIN/PUK/Management Key verification or authentication will happen automatically when you call a method that needs it. You can call the TryVerifyPin or TryAuthenticateManagementKey methods if you want, but any method that can be executed only if the PIN and/or management key has been verified or authenticated will determine if the appropriate values have been verified/authenticated, and if not, will make the appropriate calls to do so. The caller must supply a PIN/PUK/management key collector delegate (callback).

This class needs a delegate (callback): a method to enter the PIN, PUK, or management key. Although some operations will not need this delegate, any useful application will almost certainly call one or more methods that do need it. You will need to set the appropriate property after instantiating this class.

  using (var pivSession = new PivSession(yubiKeyToUse))
  {
      KeyCollector = SomeCollectorDelegate;
  };

You supply the delegate as the KeyCollector property. See also the User's Manual entry on delegates in the SDK.

Note that the YubiKey is manufactured with default PIN, PUK, and management key values. This is a requirement of the PIV standard.

   management key (hex): 01 02 03 04 05 06 07 08
                         01 02 03 04 05 06 07 08
                         01 02 03 04 05 06 07 08
PIN (hex): 31 32 33 34 35 36
as an ASCII string, this would be "123456"
PUK (hex): 31 32 33 34 35 36 37 38
as an ASCII string, this would be "12345678"

The PIN, PUK, and management key are supplied as byte arrays. The reason is that they can be binary data (they are not necessarily strings, ASCII or otherwise), and a byte array can be overwritten to limit the contents' exposure. See the User's Manual entries on sensitive data.

This class will also need a random number generator and a Triple-DES encryptor/decryptor. It will get them from CryptographyProviders. That class will return default implementations, unless you replace them. Very few applications will choose to replace the defaults, but if you want to, see the documentation for that class and the User's Manual entry on alternate crypto implementations to learn how to do so.

Constructors

Name	Description
PivSession(IYubiKeyDevice)	Create an instance of PivSession, the object that represents the PIV application on the YubiKey.

Properties

Name	Description
Connection	The object that represents the connection to the YubiKey. Most applications will ignore this, but it can be used to call Commands directly.
KeyCollector	The Delegate this class will call when it needs a PIN, PUK, or management key.
ManagementKeyAlgorithm	This specifies the algorithm of the management key.
ManagementKeyAuthenticated	This indicates whether the management key is authenticated or not.
ManagementKeyAuthenticationResult	This reports the result of the latest management key authentication attempt.
PinVerified	This indicates the current state of the PIN verification.

Methods

Name	Description
AuthenticateManagementKey(Boolean)	Authenticate the management key, throw an exception if the user cancels.
ChangeManagementKey(PivTouchPolicy)	Change the management key, throw an exception if the user cancels. The new key will be Triple-DES.
ChangeManagementKey(PivTouchPolicy, PivAlgorithm)	Change the management key, throw an exception if the user cancels. The new key will be of the specified algorithm.
ChangePin()	Change the PIN, throw an exception if the user cancels.
ChangePinAndPukRetryCounts(Byte, Byte)	Change the retry counts for the PIN and PUK. Warning This will reset the PIN and PUK to their default values as well as set the retry counts.
ChangePuk()	Change the PUK (PIN Unblocking Key), throw an exception if the user cancels.
CreateAttestationStatement(Byte)	Create an attestation statement for the private key in the given slot. Note In version 1.0.0 of the SDK, it was not possible to get an attestation statement for keys in slots 82 - 95 (retired key slots). However, beginning with SDK 1.0.1, it is possible to get attestation statements for keys in those slots.
Decrypt(Byte, ReadOnlyMemory<Byte>)	Decrypt the given data using the key in the given slot.
DeleteMsroots()	Delete any contents stored in the MSROOTS data objects.
Dispose()	When the PivSession object goes out of scope, this method is called. It will close the session. The most important function of closing a session is to "un-authenticate" the management key and "un-verify" the PIN.
GenerateKeyPair(Byte, PivAlgorithm, PivPinPolicy, PivTouchPolicy)	Generate a new key pair in the given slot.
GetAttestationCertificate()	Get the attestation certificate.
GetCertificate(Byte)	Get the certificate in the given slot.
GetMetadata(Byte)	Get information about the specified slot.
GetPinOnlyMode()	Return an enum indicating the PIN-only mode, if any, for which the YubiKey PIV application is configured.
ImportCertificate(Byte, X509Certificate2)	Import a certificate into the given slot.
ImportPrivateKey(Byte, PivPrivateKey, PivPinPolicy, PivTouchPolicy)	Import a private key into the given slot.
KeyAgree(Byte, PivPublicKey)	Perform Phase 2 of EC Diffie-Hellman Key Agreement using the private key in the given slot, and the corresponding party's public key.
ReadMsroots()	Returns the contents of the MSROOTS data objects.
ReadMsrootsStream()	Returns the contents of the MSROOTS data objects as a Stream.
ReadObject<T>()	Read the data at the storage location specified by the defined data tag for the PivDataObject T, storing and returning this data in a new object of type T.
ReadObject<T>(Int32)	Read the data at the storage location specified by the given dataTag, storing and returning this data in a new object of type T.
ReplaceAttestationKeyAndCertificate(PivPrivateKey, X509Certificate2)	Replace the attestation key and certificate.
ResetApplication()	Reset the PIV application to the default state.
ResetPin()	Reset the PIN, using the PUK (PIN Unblocking Key), throw an exception if the user cancels.
SetPinOnlyMode(PivPinOnlyMode)	Set the YubiKey's PIV application to be PIN-only with a PIN-derived and/or PIN-Protected Triple-DES management key . This sets the YubiKey to either PivPinOnlyMode.PinProtected PivPinOnlyMode.PinDerived PivPinOnlyMode.PinProtected | PivPinOnlyMode.PinDerived PivPinOnlyMode.None If the YubiKey is set to PinProtected, PinDerived, or both, the PUK will also be blocked. Warning You should not set a YubiKey for PIN-derived, this feature is provided only for backwards compatibility.
SetPinOnlyMode(PivPinOnlyMode, PivAlgorithm)	Set the YubiKey's PIV application to be PIN-only with a PIN-derived and/or PIN-Protected management key of the specified algorithm. This sets the YubiKey to either PivPinOnlyMode.PinProtected PivPinOnlyMode.PinDerived PivPinOnlyMode.PinProtected | PivPinOnlyMode.PinDerived PivPinOnlyMode.None If the YubiKey is set to PinProtected, PinDerived, or both, the PUK will also be blocked. Warning You should not set a YubiKey for PIN-derived, this feature is provided only for backwards compatibility.
Sign(Byte, ReadOnlyMemory<Byte>)	Create a digital signature using the key in the given slot.
TryAuthenticateManagementKey(Boolean)	Try to authenticate the management key.
TryAuthenticateManagementKey(ReadOnlyMemory<Byte>, Boolean)	Try to authenticate the management key. This method will use the key data provided, rather than the KeyCollector.
TryChangeManagementKey(ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, PivTouchPolicy)	Try to change the management key. This method will use the currentKey and newKey provided. The new key's algorithm will be Triple-DES.
TryChangeManagementKey(ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, PivTouchPolicy, PivAlgorithm)	Try to change the management key. This method will use the currentKey and newKey provided. The new key's algorithm will be as specified.
TryChangeManagementKey(PivTouchPolicy)	Try to change the management key. This will assume the new key is to be Triple-DES.
TryChangeManagementKey(PivTouchPolicy, PivAlgorithm)	Try to change the management key. The new key will be the specified algorithm.
TryChangePin()	Try to change the PIN.
TryChangePin(ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, out Nullable<Int32>)	Try to change the PIN. This method will use the currentPin and newPin provided.
TryChangePinAndPukRetryCounts(ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, Byte, Byte, out Nullable<Int32>)	Try to change the retry counts for both the PIN and PUK. This method will use the managementKey and pin provided. Warning This will reset the PIN and PUK to their default values as well as set the retry counts.
TryChangePuk()	Try to change the PUK (PIN Unblocking Key).
TryChangePuk(ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, out Nullable<Int32>)	Try to change the PUK. This method will use the currentPuk and newPuk provided.
TryReadObject<T>(out T)	Try to read the data at the storage location specified by the defined data tag for the PivDataObject T, storing and returning this data in a new object of type T.
TryReadObject<T>(Int32, out T)	Try to read the data at the storage location specified by the defined data tag for the PivDataObject T, storing and returning this data in a new object of type T.
TryRecoverPinOnlyMode()	Try to recover the PIN-only state. If successful, this will authenticate the management key and reset the ADMIN DATA and or PRINTED storage locations. Warning This can overwrite the contents of ADMIN DATA and/or PRINTED. If some other application relies on that data it will be lost.
TryResetPin()	Try to reset the PIN, using the PUK (PIN Unblocking Key).
TryResetPin(ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, out Nullable<Int32>)	Try to reset the PIN using the PUK (PIN Unblocking Key). This method will use the puk and pin provided.
TryVerifyPin()	Try to verify the PIN. If the user cancels, return false
TryVerifyPin(ReadOnlyMemory<Byte>, out Nullable<Int32>)	Try to verify the PIN. This method will use the PIN provided, rather than the KeyCollector.
VerifyPin()	Verify the PIN, throw an exception if the user cancels.
WriteMsroots(ReadOnlySpan<Byte>)	Write contents to the MSROOTS data objects. This will replace any data already stored in the MSROOTS data objects.
WriteMsrootsStream(Stream)	Write contents to the MSROOTS data objects. This will replace any data already stored in the MSROOTS data objects.
WriteObject(PivDataObject)	Write the contents of the given object to the storage location specified by the DataTag property.