Table of Contents

Class CardholderUniqueId

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

Use this class to process the CHUID (CardHolder Unique Identifier) data.

public sealed class CardholderUniqueId : PivDataObject
Inheritance
object
CardholderUniqueId
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.