Class PinProtectedData
Use this class to process a specific set of PIN-protected data stored in the PRINTED data object.
public sealed class PinProtectedData : PivDataObject
- Inheritance
-
objectPinProtectedData
- 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
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.
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.