KeyHistory Class
Namespace: Yubico.YubiKey.Piv.Objects Assembly: Yubico.YubiKey.dllUse this class to process the Key History data.
public sealed class KeyHistory : PivDataObject, IDisposableImplements
Remarks
A Key History consists of three values:
- Number of keys with on-card certificates
- Number of keys with off-card certificates
- Off-card certificate URL (if off-card or on-card certs value is greater than zero)
The YubiKey will not automatically set the number of on-card certs value. For example, suppose you call the method ImportCertificate(Byte, X509Certificate2) for a slot that has no cert. There is now one more key with an on-card cert. However, the YubiKey will not increment the value in the Key History storage area. If you want the Key History to reflect the number of keys with certs on the card, you must set this data object yourself.
The Off-card certificate URL is where the off-card certs can be found. This should be set if the number of off-card certs is greater than zero. If there are no off-card certs, this is generally null. However, the PIV standard allows for a non-null URL if either or both the number of on-card and off-card certs is not zero. That is, if the number of off-card certs is zero, but the number of on-card certs is not zero, then it is permissible to have an off-card cert URL.
This class will not check to make sure the values you set for the numbers
of certificates matches the YubiKey contents. For example, suppose you
have a YubiKey with only four private keys. Hence, the maximum
OnCardCertificates is four. But there is nothing stopping you from
creating a KeyHistory object and setting OnCardCertificates
to 20, 30, or even 255.
If you create an instance of KeyHistory, it will be empty
(IsEmpty will be true). Once you set one of the properties
(OnCardCertificates or OffCardCertificates), the object
will no longer be empty, even if you set those values to zero. If a
PivDataObject is empty, the PivSession.WriteObject method
will not write anything to the YubiKey. If the Data Object is not empty,
the WriteObject method will write to the YubiKey. So if you want
to write a Key History to the YubiKey that contains the information that
there are no certs and no URL, then create a new KeyHistory object,
set one of the properties to zero, and call the Write method.
If you create a new KeyHistory object by calling the constructor
directly, then set the properties and call PivSession.WriteObject,
that will, of course, overwrite the Key History 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
| Name | Description |
|---|---|
| KeyHistory() | Build a new object. This will not get the Key History from any YubiKey, it will only build an "empty" object. |
Properties
| Name | Description |
|---|---|
| OffCardCertificates | Number of Keys with Off-Card Certificates. If you set this to zero,
and the |
| OffCardCertificateUrl | The URL where the Off-Card Certificates can be found. If there are no On-Card or Off-Card Certs, it can only be set to null. |
| OnCardCertificates | Number of Keys with On-Card Certificates. If you set this to zero,
and the |
Methods
| Name | Description |
|---|---|
| Dispose(Boolean) | Releases any unmanaged resources and overwrites any sensitive data. |
| Encode() | Build the encoding of the data. |
| GetDefinedDataTag() | Get the defined data tag. This is the data tag that the PIV standard or Yubico defines to specify the given data object. |
| TryDecode(ReadOnlyMemory<Byte>) | Try to decode the data given according to the format specified for
the data object. If successful, return |