PivSession Class

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

Create a session and perform PIV operations within that session.

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