Table of Contents

Class PivDataObject

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

This abstract class defines the basic properties of a PIV Application Data Object.

public abstract class PivDataObject
Inheritance
object
PivDataObject
Derived

Remarks

Generally you will use one of the ReadObject<T>() methods to get the specified data out of a YubiKey. The formatted data will be parsed and the resulting object will present the data in a more readable form. You can then update the data and call WriteObject(PivDataObject).

Note that if there is no data on the YubiKey stored under the given object, then after calling ReadObject, the resulting PivDataObject will be "empty" (IsEmpty)

You can also create a new instance of a PivDataObject (call the constructor directly, rather than getting the YubiKey's contents), set it, and store it. However, when you store data (by calling WriteObject), you overwrite any data already there. Hence, you will likely want to get any data out first, to decide whether you want to change anything, rather than overwriting any possible contents sight unseen.

This class (and each subclass) implements IDisposable because the data might be sensitive. Upon disposal, any stored data is overwritten.

See also the user's manual entry on PIV data objects.

Properties

DataTag

The value used to specify the storage location.

public int DataTag { get; set; }

Property Value

int

Remarks

Where, on the YubiKey, data is stored is determined by the DataTag. It is a number such as 0x005fC102 or 0x005FFF00.

There are some tag values defined by the PIV standard, and there are others defined by Yubico (see the User's Manual entry on GET DATA and GET vendor data). In addition, some numbers are accepted by a YubiKey even though no one has defined their use or contents. These are the numbers 0x005F0000 through 0x005FFFFF (inclusive) not already specified.

When you instantiate an object that is a subclass of this abstract class, this property will be set with the defined (or sometimes it's called the default) DataTag. However, it is possible to change that tag. See the User's manual entry on PIV data objects for more information on what valid data tags are possible. If you try to change to an unsupported tag, the SDK will throw an exception.

Note that changing the DataTag is not recommended, but it is possible because there are some applications that have a use case for such a feature. See the User's Manual entry on PIV data objects. for a more detailed description of this topic.

IsEmpty

Indicates whether there is any data or not. If this is true, then the contents of any property are meaningless.

public bool IsEmpty { get; protected set; }

Property Value

bool

Remarks

Note that is it possible for some Data Objects to contain data, but all that data is "default" or "nothing". For example, the KeyHistory class contains numbers of certs and a URL. It is possible a YubiKey contains and encoded Key History in the Key History data location, but that data includes no certs and no URL.

Suppose you build a KeyHistory object using the ReadObject<T>() method, and the YubiKey contains data in the Key History storage area, but that data indicates there are no certs and no URL. The resulting object will not be empty (the IsEmpty field will be false). However, the properties describing the contents will be zero and NULL.

If you build the KeyHistory object using the constructor, it will begin as empty, but if you set any properties, even to zero or null, the object will become not empty.

Methods

Decode(ReadOnlyMemory<byte>)

Decode the data given according to the format specified for the data object.

public void Decode(ReadOnlyMemory<byte> encodedData)

Parameters

encodedData ReadOnlyMemory<byte>

The data to parse.

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

If the input is not encoded as expected, this method will throw an exception. 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.

Exceptions

ArgumentException

The data is not properly encoded for the data object.

Dispose()

Releases any unmanaged resources and overwrites any sensitive data.

public void Dispose()

Dispose(bool)

Releases any unmanaged resources and overwrites any sensitive data.

protected virtual void Dispose(bool disposing)

Parameters

disposing bool

Encode()

Build the encoding of the data.

public abstract 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 abstract 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)

Is the given tag valid as an alternate?

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

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