Class CardholderUniqueId
Use this class to process the CHUID (CardHolder Unique Identifier) data.
public sealed class CardholderUniqueId : PivDataObject
- Inheritance
-
objectCardholderUniqueId
- Inherited Members
Remarks
A CHUID consists of five values:
- FASC-N (Federal Agency SmartCredential Number)
- GUID (Global Unique Identifier)
- Expiration Date
- Issuer Asymmetric Signature
- LRC (error code)
For the YubiKey, the FASC-N and Expiration Date are fixed. That is, the FASC-N and Expiration Date are the same for all YubiKeys.
The YubiKey does not use the signature value, and the PIV standard does not use the LRC. Hence, those two values are "empty".
You can set the GUID to any 16-byte value you want, but it is generally a random value. That is so each YubiKey has a different GUID.
You will generally get the current CHUID for a YubiKey using one of the
PivSession.ReadObject
methods. Upon manufacture, the CHUID is
"empty", so the CardHolderUniqueId
object will be empty as well
(the IsEmpty property will be true
).
You can then set the GUID (or have a random GUID generated for you) and
then store the CHUID using the PivSession.WriteObject
method.
It is also possible the CHUID is already set on the YubiKey. In that
case, call one of the PivSession.ReadObject
methods and the
resulting object will have IsEmpty
set to false
and you can
see the GUID that is on the YubiKey.
Finally, you can create a new CardholderUniqueId
object by calling
the constructor directly, then set the GUID and call
PivSession.WriteObject
. That will, of course, overwrite the CHUID
on the YubiKey, if there is one. Because that might not be something you
want to do, this is the most dangerous option.
See also the user's manual entry on PIV data objects.
Constructors
CardholderUniqueId()
Build a new object. This will not get a CHUID from any YubiKey, it will only build an "empty" object.
public CardholderUniqueId()
Remarks
To read the CHUID data out of a YubiKey, call the ReadObject<T>() method.
Properties
ExpirationDate
The PIV card's expiration date. This is a fixed value for every YubiKey: Jan 1, 2030.
public DateTime ExpirationDate { get; }
Property Value
- DateTime
FascNumber
The "Federal Agency Smart Credential Number" (FASC-N). This is a fixed 25-byte value for every YubiKey, and is a Non-Federal Issuer number.
public ReadOnlyMemory<byte> FascNumber { get; }
Property Value
- ReadOnlyMemory<byte>
GuidValue
The "Global Unique Identifier" (GUID). If there is no CHUID, this is "empty" (Guid.Length will be 0). This is a 16-byte value.
public ReadOnlyMemory<byte> GuidValue { 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.
SetGuid(ReadOnlySpan<byte>)
Set the Guid with the given value. If the array is not exactly 16 bytes, this method will throw an exception.
public void SetGuid(ReadOnlySpan<byte> guidValue)
Parameters
guidValue
ReadOnlySpan<byte>The GUID to use.
Remarks
If there is a GUID value already in this object, this method will overwrite it.
Exceptions
- ArgumentException
The data is not exactly 16 bytes.
SetRandomGuid()
Set the Guid with a random, 16-byte value.
public void SetRandomGuid()
Remarks
This method will use the random number generator built by CryptographyProviders to generate 16 random bytes as the new GUID.
If there is a GUID value already in this object, this method will overwrite it.
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.