Class PivMetadata

Namespace

Yubico.YubiKey.Piv

Assembly

Yubico.YubiKey.dll

This class parses the response data from the PIV Get Metadata command. It holds data about the key in a slot.

public class PivMetadata

Inheritance

object

PivMetadata

Remarks

The response to the GetMetadataCommand is GetMetadataResponse. Call the GetData method in the response object to get the metadata. An instance of this class will be returned.

There are six possible elements of metadata:

Metadata element	Description
Algorithm
Policy	PIN and Touch policy
Origin	imported or generated by the YubiKey
Public Key
Default value	Is the key in the slot the default value?
Retries	How many wrong values can be entered before the YubiKey is locked, and how many retries remain? (See the user's manual entry on PIV PIN and PUK.)

Not all metadata information applies to all keys in all slots. For example, slot 9A holds a private key. Getting metadata for this slot will return Algorithm, Policy, Origin, and Public Key. But slot 9B holds the management key, which is a symmetric key. The metadata for this slot is Algorithm, Policy, and Default value.

The properties in this class are reporting the metadata. Check a property to see the result. However, for some elements, the property will specify None, Unknown, or in the case of the public key, an empty list.

Metadata element	PivMetadata property
Algorithm	Algorithm (PivAlgorithm)
Policy	PinPolicy (PivPinPolicy) and TouchPolicy (PivTouchPolicy)
Origin	KeyStatus (PivKeyStatus)
Public Key	PublicKey (Yubico.YubiKey.Piv.PivPublicKey)
Default value	KeyStatus (PivKeyStatus)
Retries	RetryCount and RetriesRemaining (See the user's manual entry on PIV PIN and PUK)

The public key in this object is a "byte array". If it is an RSA key, the data will be two successive TLVs, the modulus followed by the public exponent.

81 || length || modulus || 82 || length || publicExponent
where the length is DER length octets.
For example:
81 82 01 00 F1 50 ... E9 82 03 01 00 01
Or to see it parsed,
81 82 01 00
   F1 50 ... 50
82 03
   01 00 01

If the public key is an ECC key, the data will be a single TLV, the public point.

86 || length || publicPoint
where the length is DER length octets and the public point is 04 || x || y
For example:
86 41 04 C4 17 ... 26
Or to see it parsed,
86 41
   04 C4 17 ... 26

To learn about how to use the public key data, see the User's Manual entry on public keys.

Constructors

PivMetadata(ReadOnlyMemory<byte>, byte)

The constructor that takes in the metadata encoding returned by the YubiKey in response to the Get metadata command, along with the slot.

public PivMetadata(ReadOnlyMemory<byte> responseData, byte slotNumber)

Parameters

responseData ReadOnlyMemory<byte>

The data portion of the response APDU, this is the encoded metadata.

slotNumber byte

The slot from which the metadata was retrieved.

Exceptions

ArgumentException

The specified slot is not valid for PIV metadata.

InvalidOperationException

The data supplied is not valid PIV metadata.

Properties

Algorithm

The algorithm of the key in the specified slot.
Note that if a slot is empty, the Algorithm will be
PivAlgorithm.None.

public PivAlgorithm Algorithm { get; }

Property Value

PivAlgorithm

KeyStatus

If the key is PIN, PUK, or management, is it the default value?
If the key is asymmetric, is it the imported or generated?
If the slot is empty, the status will be Unknown.

public PivKeyStatus KeyStatus { get; }

Property Value

PivKeyStatus

PinPolicy

The policy for requiring the PIN before operations using the key in the given slot.

public PivPinPolicy PinPolicy { get; }

Property Value

PivPinPolicy

PublicKeyParameters

The public key associated with the private key in the given slot.

public IPublicKey? PublicKeyParameters { get; }

Property Value

IPublicKey

RetriesRemaining

How many PIN or PUK retries remain before the PIN or PUK will be locked. If the slot is not PIN or PUK, this value will be -1, indicating the count is unknown.

public int RetriesRemaining { get; }

Property Value

int

RetryCount

The total number of wrong PINs or PUKs that can be entered before the PIN or PUK will be locked. If the slot is not PIN or PUK, this value will be -1, indicating the count is unknown.

public int RetryCount { get; }

Property Value

int

Slot

The slot for the metadata listed in this instance.

public int Slot { get; }

Property Value

int

TouchPolicy

The policy for requiring touch before operations using the key in the given slot.

public PivTouchPolicy TouchPolicy { get; }

Property Value

PivTouchPolicy