AdminData Class

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

Use this class to process the Admin Data.

public sealed class AdminData : PivDataObject

Inheritance object PivDataObject AdminData

Remarks

Admin consists of three values:

Bit field: PUK blocked? Mgmt Key stored in protected area? (optional)
Salt (optional)
PIN last updated (optional)

The AdminData is used to store information about "PIN-only" modes of a YubiKey. See the User's Manual entry on setting the YubiKey to be PIN only.

If the YubiKey is PIN-derived, the PUK should be blocked, and there will be a salt. Hence, the PukBlocked property should be true and the Salt should contain the salt used to derive the management key.

If the YubiKey is PIN-protected, the PUK should be blocked, so both the PinProtected and PukBlocked properties should be true.

Note that the YubiKey will not "automatically" set the Admin Data to the appropriate values if the management key is set to one of the PIN-only modes. That is the responsibility of the code that sets the PIN-only mode. In other words, if you write code that sets a YubiKey to one of the PIN-only modes, then you must also write code to correctly set the Admin Data. The PivSession methods that set a YubiKey to PIN-only will store the appropriate Admin Data information, so you should call those methods to set a YubiKey to PIN-only, rather than writing the code yourself.

The salt is used by the code that computes a PIN-derived management key. The management key is derived from the PIN and salt. It must be exactly 16 bytes. This class will accept either no salt (mgmt key is not PIN-derived) or a 16-byte salt. If you want to use the Admin Data storage area to store something other than a 16-byte salt, you will have to write your own implementation.

The PIN last updated element is the date the PIN was changed. It is not mandatory to set this value when the PIN is changed, but the SDK code that changes the PIN will check the ADMIN DATA. If the YubiKey contains ADMIN DATA, the SDK will update the time when the PIN is changed. If there is no ADMIN DATA, the SDK will not create ADMIN DATA when the PIN is changed.

Upon instantiation of this class, it is empty. If you set any of the properties (PukBlocked, (PinProtected, Salt, and PinLastUpdated), the object will no longer be empty. That is the case even if you set the PukBlocked and/or the PinProtected to false, or the other two to null. In this case, the encoding of the Admin Data is

80 03
   81 01
      00
The salt and PinLastUpdated are optional, so
they are not encoded when absent. The bit field
is also optional, so it could be absent, but
this class exercises the option and writes it.

If an object is not empty, you can call the WriteObject(PivDataObject) method, which will call the Encode() method. This class will encode whatever data it is given, even if it is "wrong". For example, if a management key is PIN-derived, then the PUK blocked bit and the Salt should be set. However, if, for example, the PUK blocked bit is set, but not the Salt, this class will encode anyway. It will generate an encoding, not throw an exception. It is the responsibility of the caller to make sure the data in an object is correct for the situation.

Constructors

Name	Description
AdminData()	Build a new object. This will not get the Admin Data from any YubiKey, it will only build an "empty" object.

Properties

Name	Description
PinLastUpdated	The date the PIN was last updated. If this is not being used, it will be null.
PinProtected	Set this to `true` if the YubiKey's management key is PIN-protected. If you set a YubiKey to PIN-protected, then the PUK should be blocked as well.
PukBlocked	Set this to `true` if the PUK is blocked. If you set a YubiKey to PIN-only, then the PUK should be blocked.
Salt	The salt used to derive the management key. If there is no salt, this will be null.

Methods

Name	Description
Dispose(bool)	Releases any unmanaged resources and overwrites any sensitive data.
Encode()	Build the encoding of the data.
GetDefinedDataTag()	Get the defined data tag. This is the data tag that the PIV standard or Yubico defines to specify the given data object.
SetSalt(ReadOnlyMemory<byte>)	Set the `Salt` property with the given value. If the input argument `Length` is 0, this will set the `Salt` to be null. Otherwise, it must be exactly 16 bytes. If not, this method will throw an exception.
TryDecode(ReadOnlyMemory<byte>)	Try to decode the data given according to the format specified for the data object. If successful, return `true`, otherwise, return `false`.