Table of Contents

Class PinProtectedData

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

Use this class to process a specific set of PIN-protected data stored in the PRINTED data object.

public sealed class PinProtectedData : PivDataObject
Inheritance
object
PinProtectedData
Inherited Members

Remarks

Some Data Objects are retrievable only in a session where the PIN has been verified. Hence, that data is PIN-protected. This class will be able to process data stored in one such Data Object. The data this class can process is specified by its properties.

See the User's Manual entry on PIV data objects for a description of the details of how this class works.

This class specifies the DefinedDataTag to be 0x005FC109 which is the data tag for the PRINTED storage area. The reason is that the PRINTED area requires the PIN to read. The data is stored in this object and when it is needed, simply retrieve it and use it. In order to retrieve, though, PIN verification is required, so in this way the data is PIN-protected.

This class does not allow changing the DataTag. That is, it is possible to store the data in this set only in the PRINTED area.

This class is different from other PivDataObjects. Most such classes store information encoded as the PIV standard defines it. However, this class stores the elements specified by PinProtectedDataType following a definition that is not the PIV standard for PRINTED.

Note that this object can accept or decode only elements for which there is a property.

Constructors

PinProtectedData()

Build a new object. This will not get the PIN-protected data from the YubiKey, it will only build an "empty" object.

public PinProtectedData()

Properties

ManagementKey

The management key that will be PIN-protected. If there is no management key, this will be null.

public ReadOnlyMemory<byte>? ManagementKey { get; }

Property Value

ReadOnlyMemory<byte>?

Methods

Dispose(bool)

Releases any unmanaged resources and overwrites any sensitive data.

protected override void Dispose(bool disposing)

Parameters

disposing bool

Encode()

Build the encoding of the data.

public override byte[] Encode()

Returns

byte[]

A new byte array containing the encoded data object.

Remarks

Each data object has a defined format. See the User's Manual entry on GET DATA and GET vendor data for descriptions of the formats. This method will build a new byte array containing the data set in the object. This data will generally then be stored on the YubiKey.

Note that this method returns a new byte array, not a reference to an array inside the object. If this array contains any sensitive data, make sure you overwrite it when done with it.

If the object is empty (IsEmpty is true), then this method will return the encoding of no data, which is 0x53 00.

GetDefinedDataTag()

Get the defined data tag. This is the data tag that the PIV standard or Yubico defines to specify the given data object.

public override int GetDefinedDataTag()

Returns

int

The data tag defined for the data object.

Remarks

This is also called the default data tag. This method will always return the defined tag, regardless of what the DataTag property returns. That is, even if you change the DataTag this method will still return the original, defined tag.

IsValidAlternateTag(int)

Override the base class. This class does not allow alternate DataTags. The only allowed tag is the defined.

protected override bool IsValidAlternateTag(int dataTag)

Parameters

dataTag int

The data tag the caller wants to use as an alternate.

Returns

bool

A boolean, true is the given tag can be used as an alternate, false otherwise.

SetManagementKey(ReadOnlyMemory<byte>)

Set the ManagementKey property with the specified value.

public void SetManagementKey(ReadOnlyMemory<byte> managementKey)

Parameters

managementKey ReadOnlyMemory<byte>

Remarks

The caller supplies an argument of Length zero, 16, 24, or 32. Any other input will cause an exception.

An empty array (Length = zero) means there is no management key stored in the PRINTED object on the given YubiKey. A caller can set the management key to empty in order to "convert" a YubiKey from PIN-protected to normal (the application/user must supply the management key for authentication).

If there is a management key already in this object, this method will overwrite it.

This method will copy the data, it will not copy a reference.

Exceptions

ArgumentException

The data Length is not 0, 16, 24, or 32 bytes.

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.

public override bool TryDecode(ReadOnlyMemory<byte> encodedData)

Parameters

encodedData ReadOnlyMemory<byte>

The data to parse.

Returns

bool

A boolean, true if the method successfully decodes, false otherwise.

Remarks

This will parse the encoding and set local properties with the data. The encodedData generally was retrieved from the YubiKey.

This will replace any data in the object.

If there is no data (encodedData.Length is 0) this method will set the object to the empty state (IsEmpty will be true and the contents of any data properties will be meaningless) and return true.

If the input is not encoded as expected, this method will set the object to the empty state and return false. This includes the fixed values. That is, there are some values in some data objects that are fixed for every YubiKey, and this method will expect the contents of the encodedData to contain those fixed values.

If the input is encoded as expected, yet the data in that encoding is invalid (e.g. some element is not the correct length), this method will return false.

Exceptions

ArgumentException

The data is not properly encoded for the data object.