Class AuthenticatorData

Namespace

Yubico.YubiKey.Fido2

Assembly

Yubico.YubiKey.dll

Contains information about the credential, assertion, or the authenticator itself after making a credential or getting an assertion.

public class AuthenticatorData

Inheritance

object

AuthenticatorData

Remarks

When a new credential is made, or a credential is used to get an assertion, the YubiKey returns data about that operation. When making a credential, this includes information about the authenticator itself, such as the aaguid.

The authenticator data object defined in the FIDO2 standard is encoded but not following the rules of CBOR or DER or any other standard encoding scheme. The encoding is defined in the W3C standard.

Constructors

AuthenticatorData(ReadOnlyMemory<byte>)

Build a new instance of AuthenticatorData based on the given encoding.

public AuthenticatorData(ReadOnlyMemory<byte> encodedData)

Parameters

encodedData ReadOnlyMemory<byte>

The authenticator data, encoded following the definition in the W3C standard.

Remarks

The overall encoding does not follow any standard encoding scheme but is defined in the W3C standard, although two of the elements are CBOR-encoded structures.

This constructor will copy the input data, not just a reference.

Exceptions

ArgumentException

The encodedData is not a correct encoding for FIDO2 authenticator data.

Properties

Aaguid

The authenticator's AAGUID. This is an optional value and can be null.

public ReadOnlyMemory<byte>? Aaguid { get; }

Property Value

ReadOnlyMemory<byte>?

Remarks

When making a credential, this information will be provided, when getting an assertion, it will not.

CredentialId

The CredentialId. This is an optional value and can be null.

public CredentialId? CredentialId { get; }

Property Value

CredentialId

Remarks

When making a credential, this information will be provided, when getting an assertion, it will not.

CredentialPublicKey

The Credential's public key. This is an optional value and can be null.

public CoseKey? CredentialPublicKey { get; }

Property Value

CoseKey

Remarks

When making a credential, this information will be provided, when getting an assertion, it will not.

EncodedAuthenticatorData

The encoded authenticator data is used to verify the attestation statement (make credential) or assertion signature (get assertion).

public ReadOnlyMemory<byte> EncodedAuthenticatorData { get; }

Property Value

ReadOnlyMemory<byte>

Extensions

The list of extensions. This is an optional value and can be null.

public IReadOnlyDictionary<string, byte[]>? Extensions { get; }

Property Value

IReadOnlyDictionary<string, byte[]>

Remarks

Each extension is a key/value pair. All keys are strings, but each extension has its own definition of a value. It could be an int, or it could be a map containing a string and a boolean,. It is the caller's responsibility to decode the value.

For each value, the standard (or the vendor in the case of vendor-defined extensions) will define the structure of the value. From that structure the value can be decoded following CBOR rules. The encoded value is what is stored in this dictionary.

RelyingPartyIdHash

The digest of the relying party ID. It is the SHA-256 digest of the Id property of the RelyingParty class passed to the MakeCredential method or command as part of the MakeCredentialParameters.

public ReadOnlyMemory<byte> RelyingPartyIdHash { get; }

Property Value

ReadOnlyMemory<byte>

SignatureCounter

The count the authenticator returns. This should be an increasing value for each time GetAssertion is called and is returned to the relying party, which can verify that it is greater than the previous value (to help thwart authenticator cloning).

public int SignatureCounter { get; }

Property Value

int

UserPresence

If true, a test of user presence indicates a user is indeed present before making the credential (e.g. the YubiKey was touched). Otherwise it will be false.

public bool UserPresence { get; }

Property Value

bool

UserVerification

If true, a test of user verification operation indicates the user has indeed been verified. Note that this can be biometric verification, as well as touch plus PIN, or password. Otherwise it will be false.

public bool UserVerification { get; }

Property Value

bool

Methods

GetCredBlobExtension()

Get the value of the "credBlob" extension. This returns the decoded value.

public byte[] GetCredBlobExtension()

Returns

byte[]

A byte array containing the decoded "credBlob" extension.

Remarks

Because this extension is used more often, a dedicated method is provided as a convenience. There is no need for the caller to CBOR-decode the value for the key "credBlob".

If there is no "credBlob" extension, this method will return an empty byte array.

GetCredProtectExtension()

Get the value of the "credProtect" extension. This returns the decoded value.

public CredProtectPolicy GetCredProtectExtension()

Returns

CredProtectPolicy

The CredProtectPolicy enum describing the value of the "credProtect" extension.

Remarks

Because this extension is used more often, a dedicated method is provided as a convenience. There is no need for the caller to CBOR-decode the value for the key "credProtect".

Exceptions

Ctap2DataException

If the value of the extension is not a valid CredProtect policy.

GetHmacSecretExtension(PinUvAuthProtocolBase)

Get the value of the "hmac-secret" extension. This returns the decoded and decrypted value or values.

public byte[] GetHmacSecretExtension(PinUvAuthProtocolBase authProtocol)

Parameters

authProtocol PinUvAuthProtocolBase

An instance of one of the subclasses of PinUvAuthProtocolBase, which was used to get the assertion.

Returns

byte[]

A byte array containing the decoded "hmac-secret" extension.

Remarks

Because this extension is used more often, a dedicated method is provided as a convenience. There is no need for the caller to CBOR-decode the value for the key "hmac-secret".

There are possibly two values to return. Both will be 32 bytes long. If there is only one secret value returned, this method will return a 32-byte long array. If there are two values returned, this method will return a 64-byte long array, where "output1" is the first 32 bytes and "output2" is the second 32 bytes.

The caller must supply the PinUvAuthProtocolBase used to create the GetAssertion parameters.

If you are getting assertions using GetAssertions(GetAssertionParameters), you can use the AuthProtocol property.

var gaParams = new GetAssertionParameters(relyingParty, clientDataHash);
gaParams.RequestHmacSecretExtension(salt);
IReadOnlyList<GetAssertionData> assertions = fido2.GetAssertions(gaParams);
byte[] hmacSecret = assertions[0].AuthenticatorData.GetHmacSecretExtension(
fido2Session.AuthProtocol);

If the "hmac-secret" extension was not specified when making the credential, then the YubiKey will simply not return anything. It is not an error. In that case, this method will return an empty byte array.

Exceptions

ArgumentNullException

If the "hmac-key" is in the extensions, and the authProtocol argument is null.

GetMinPinLengthExtension()

Get the value of the "minPinLength" extension. This returns the decoded value.

public int? GetMinPinLengthExtension()

Returns

int?

An int that is the decoded "minPinLength" extension.

Remarks

Because this extension is used more often, a dedicated method is provided as a convenience. There is no need for the caller to CBOR-decode the value for the key "minPinLength".

If there is no "minPinLength" extension, this method will return null.