Class PivDataObject
This abstract class defines the basic properties of a PIV Application Data Object.
public abstract class PivDataObject
- Inheritance
-
objectPivDataObject
- 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
intThe 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.