Table of Contents

Class MakeCredentialParameters

Namespace
Yubico.YubiKey.Fido2
Assembly
Yubico.YubiKey.dll

This collects and encodes the information needed to make a FIDO2 credential.

public class MakeCredentialParameters
Inheritance
object
MakeCredentialParameters

Remarks

There are ten elements that are inputs to a FIDO2 credential (see section 6.1 of the FIDO2 standard). Four of them are required and six are optional.

When you need to make a new credential, you will collect all the required along with any optional parameters and build an instance of this class. Then pass that object to the MakeCredential method or command.

Constructors

MakeCredentialParameters(RelyingParty, UserEntity)

Constructs a new instance of MakeCredentialParameters using the default preferred algorithm

public MakeCredentialParameters(RelyingParty relyingParty, UserEntity userEntity)

Parameters

relyingParty RelyingParty

The relying party for which the credential is to be created. This constructor copies a reference to the input object.

userEntity UserEntity

The user for which the credential is to be created. This constructor copies a reference to the input object.

Remarks

Note that a UserEntity is a required element in order to make a credential. The standard specifies that the UserEntity is made up of an ID, a Name, and a DisplayName. The standard also says the Name and DisplayName are optional. It should be possible to make a credential using a UserEntity that contains only an ID. However, YubiKeys prior to version 5.3.0 require a Name in order to make a credential.

One of the required elements of the MakeCredential parameters is a list of supported algorithms (a type and algorithm pair, Algorithms). Hence, you must supply at least one algorithm, which will be the preferred one. Currently the only algorithm supported by the YubiKey is the pair "public-key"/ECDSA with SHA-256. To build this parameters object with that credential type, use this constructor, which will add it by default. If you want to specify something other than the default, use the constructor that takes in an algorithmType and algorithm.

It is possible to add more types later using the method AddAlgorithm(string, CoseAlgorithmIdentifier).

MakeCredentialParameters(RelyingParty, UserEntity, string, CoseAlgorithmIdentifier)

Constructs a new instance of MakeCredentialParameters setting the preferred algorithm to something other than the default.

public MakeCredentialParameters(RelyingParty relyingParty, UserEntity userEntity, string algorithmType, CoseAlgorithmIdentifier algorithm)

Parameters

relyingParty RelyingParty

The relying party for which the credential is to be created. This constructor copies a reference to the input object.

userEntity UserEntity

The user for which the credential is to be created. This constructor copies a reference to the input object.

algorithmType string

The type of type and algorithm that is the caller's preferred choice.

algorithm CoseAlgorithmIdentifier

The algorithm of type and algorithm that is the caller's preferred choice.

Remarks

Note that a UserEntity is a required element in order to make a credential. The standard specifies that the UserEntity is made up of an ID, a Name, and a DisplayName. The standard also says the Name and DisplayName are optional. It should be possible to make a credential using a UserEntity that contains only an ID. However, YubiKeys prior to version 5.3.0 require a Name in order to make a credential.

One of the required elements of the MakeCredential parameters is a list of supported algorithms (a type and algorithm pair, Algorithms). Hence, you must supply at least one algorithm, which will be the preferred one. Currently the only algorithm supported by the YubiKey is the pair "public-key"/ECDSA with SHA-256. To build this parameters object with that credential type, use the constructor that adds it be default. If you want to specify something other than the default, use this constructor.

It is possible to add more types later using the method AddAlgorithm(string, CoseAlgorithmIdentifier).

Properties

Algorithms

The list of supported algorithms for credential generation. This is the "pubKeyCredParams" in the standard (FIDO2 section 6.1).

public IReadOnlyList<Tuple<string, CoseAlgorithmIdentifier>> Algorithms { get; }

Property Value

IReadOnlyList<Tuple<string, CoseAlgorithmIdentifier>>

Remarks

Each entry in the list is a type and algorithm. Neither the type nor algorithm are guaranteed to be unique, although each combination is. Currently, the only type defined is "public-key". The only algorithm the YubiKey supports is ECDSA with SHA-256 using the NIST P-256 curve. This is the pair "public-key"/CoseAlgorithmIdentifier.ES256.

To add an entry to the list, call AddAlgorithm(string, CoseAlgorithmIdentifier).

ClientDataHash

The original clientDataHash that was provided by the client. It contains the challenge. This is a required element.

public ReadOnlyMemory<byte> ClientDataHash { get; set; }

Property Value

ReadOnlyMemory<byte>

EnterpriseAttestation

Specifies whether an enterprise attestation is to be returned along with the credential, and if so, which kind. This is an optional parameter, so it is can be null.

public EnterpriseAttestation? EnterpriseAttestation { get; set; }

Property Value

EnterpriseAttestation?

Remarks

See also the documentation for EnterpriseAttestation.

Not all authenticators support enterprise attestation (check the Options property of AuthenticatorInfo). If a YubiKey does not support this option, setting this property (even setting it to None) will generate an error return.

Furthermore, if an authenticator supports only vendor-facilitated attestation, the standard allows treating a request for platform-managed attestation as a request for vendor-facilitated.

ExcludeList

The list of credentialIds for which the authenticator should not create a new credential. This is an optional parameter, so it can be null.

public IReadOnlyList<CredentialId>? ExcludeList { get; }

Property Value

IReadOnlyList<CredentialId>

Remarks

To add an entry to the list, call ExcludeCredential(CredentialId).

Extensions

The list of extensions. This is an optional parameter, so it can be null.

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

Property Value

IReadOnlyDictionary<string, byte[]>

Remarks

To add an entry to the list, call AddExtension(string, byte[]).

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 encode 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 encoded following CBOR rules. The result of the encoding the value is what is stored in this dictionary.

Options

The list of authenticator options. Each standard-defined option is a key/value pair, where the key is a string and the value is a boolean. This is an optional parameter, so it can be null.

public IReadOnlyDictionary<string, bool>? Options { get; }

Property Value

IReadOnlyDictionary<string, bool>

Remarks

To add options, call AddOption(string, bool).

PinUvAuthParam

The result of calling the PinProtocol's method AuthenticateUsingPinToken(byte[], byte[]) using the PIN token as the key and the client data hash as the message. This is an optional parameter, so it can be null.

public ReadOnlyMemory<byte>? PinUvAuthParam { get; set; }

Property Value

ReadOnlyMemory<byte>?

Remarks

In order to obtain the pinUvAuthParam, choose a protocol and build the appropriate PinUvAuthProtocolBase object. Obtain the YubiKey's Key Agreement public key and call the protocol object's Encapsulate method. Next obtain the PIN token. Finally, call the protocol object's AuthenticateUsingPinToken(byte[], byte[]) method using the ClientDataHash as the message to authenticate. Note that the first argument in this call is the PIN token, which is an encrypted value. Do not decrypt the PIN token. The result of that authentication operation is the PinUvAuthParam

Protocol

The protocol chosen by the platform. This is an optional parameter, so it can be null.

public PinUvAuthProtocol? Protocol { get; set; }

Property Value

PinUvAuthProtocol?

RelyingParty

The relying party's ID, along with an optional descriptive string. This is a required element.

public RelyingParty RelyingParty { get; set; }

Property Value

RelyingParty

UserEntity

The user's ID, along with optional descriptive strings. This is a required element.

public UserEntity UserEntity { get; set; }

Property Value

UserEntity

Remarks

Note that a UserEntity is a required element in order to make a credential. The standard specifies that the UserEntity is made up of an ID, a Name, and a DisplayName. The standard also says the Name and DisplayName are optional. It should be possible to make a credential using a UserEntity that contains only an ID. However, YubiKeys prior to version 5.3.0 require a Name in order to make a credential.

Methods

AddAlgorithm(string, CoseAlgorithmIdentifier)

Add an entry to Algorithms.

public void AddAlgorithm(string algorithmType, CoseAlgorithmIdentifier algorithm)

Parameters

algorithmType string
algorithm CoseAlgorithmIdentifier

AddCredBlobExtension(byte[], AuthenticatorInfo)

Add the "credBlob" extension. Note that the credBlob extension is valid only for discoverable credentials.

public void AddCredBlobExtension(byte[] credBlobValue, AuthenticatorInfo authenticatorInfo)

Parameters

credBlobValue byte[]

The data to add as the "credBlob" extension.

authenticatorInfo AuthenticatorInfo

The FIDO2 AuthenticatorInfo for the YubiKey being used.

Remarks

Because this extension is used more often, a dedicated method is provided as a convenience. There is no need for the caller to encode the credBlobValue. That is, this is essentially the same as calling AddExtension, except this method will verify the YubiKey supports the extension, verify the data length, use the appropriate extensionString, and encode the value.

The caller supplies the AuthenticatorInfo for the YubiKey, obtained by calling the GetInfoCommand or providing the AuthenticatorInfo property.

This method will determine from the authenticatorInfo whether the YubiKey supports this extension, and whether the data provided is within the YubiKey's range for "credBlob". The standard specifies that the maximum credBlob length is at least 32 bytes. The AuthenticatorInfo contains the property MaximumCredentialBlobLength, which is the length the YubiKey supports. If the YubiKey does not support the "credBlob" extension, or the data is too long, this method will throw an exception.

The caller supplies the un-encoded credBlobValue. This method will encode it.

The credBlob data will be returned when the credential is used to get an assertion. When building the GetAssertion parameters, the caller must specify that the YubiKey return the credBlob. See RequestCredBlobExtension(). The assertion returned will contain the credBlob. The data will be returned in the AuthenticatorData and can be retrieved using GetCredBlobExtension()

Exceptions

ArgumentNullException

The credBlobValue or authenticatorInfo arg is null.

ArgumentException

The YubiKey does not support this extension, or the value's length was invalid.

AddCredProtectExtension(CredProtectPolicy, bool, AuthenticatorInfo)

Add the "credProtect" extension, specifying the protection policy the YubiKey is to use when getting assertions.

public void AddCredProtectExtension(CredProtectPolicy credProtectPolicy, bool enforceCredProtectPolicy, AuthenticatorInfo authenticatorInfo)

Parameters

credProtectPolicy CredProtectPolicy

The "credProtect" policy the YubiKey is to follow when making the credential.

enforceCredProtectPolicy bool

Determines the behavior taken when the authenticator does not support the requested credProtect extension. Throws NotSupportedException when true, returns silently without adding the extension when false.

authenticatorInfo AuthenticatorInfo

The FIDO2 AuthenticatorInfo for the YubiKey being used.

Remarks

Section 12.1 of the FIDO2 CTAP 2.1 standard specifies this extension. There are two parts: what the relying party communicates to the client, and what the client communicates to the authenticator. This class, MakeCredentialParameters, builds the parameters for the message from the client to the authenticator. Hence, this method will build the extension in the structure specified by the standard in the message from the client to the YubiKey.

Note that the standard specifies that the the message from RP to client contains the same information as the message from the client to the authenticator, just in a different format. Furthermore, the message from the RP to the client contains extra information, namely a boolean indicating the RP's request on how to handle the case where the authenticator does not support user verification (UV). That boolean is not passed down to the YubiKey and it is the responsibility of the client to handle that logic.

Because this extension is used more often, a dedicated method is provided as a convenience. There is no need for the caller to encode the credProtectPolicy. That is, this is essentially the same as calling AddExtension, except this method will verify the YubiKey supports the extension, verify the data, use the appropriate >extensionString, and encode the value.

The caller supplies the AuthenticatorInfo for the YubiKey, obtained by calling the GetInfoCommand or providing the AuthenticatorInfo property.

This method will determine from the authenticatorInfo whether the YubiKey supports this extension, and whether the data provided is correct for the YubiKey's support for "credProtect".

The standard defines three policies: 

UserVerificationOptional
UserVerificationOptionalWithCredentialIDList
UserVerificationRequired
The SDK provides for one more option: None.

The policy UserVerificationOptionalWithCredentialIDList means that the authenticator may or may not enforce UV if the request for an assertion is accompanied by a credential ID (see the allowList in GetAssertionParameters). If there is no credential ID (no allowList), then UV is required to get an assertion.

You can see the "credProtect" policy in the MakeCredentialData.AuthenticatorData.Extensions property once the credential has been made. See GetCredProtectExtension().

Note that while the "credProtect" policy refers to how the credential is protected when getting an assertion, the "credProtect" policy is not returned by the YubiKey in the GetAssertionData.AuthenticatorData.Extensions.

If you pass None as the credProtectPolicy, this method will do nothing and return. The "credProtect" policy of the credential will be the YubiKey's default.

Exceptions

ArgumentNullException

The authenticatorInfo arg is null.

NotSupportedException

The YubiKey does not support this extension, or the input values were not correct.

AddCredProtectExtension(CredProtectPolicy, AuthenticatorInfo)

Add the "credProtect" extension, specifying the protection policy the YubiKey is to use when getting assertions.

public void AddCredProtectExtension(CredProtectPolicy credProtectPolicy, AuthenticatorInfo authenticatorInfo)

Parameters

credProtectPolicy CredProtectPolicy

The "credProtect" policy the YubiKey is to follow when making the credential.

authenticatorInfo AuthenticatorInfo

The FIDO2 AuthenticatorInfo for the YubiKey being used.

Remarks

Section 12.1 of the FIDO2 CTAP 2.1 standard specifies this extension. There are two parts: what the relying party communicates to the client, and what the client communicates to the authenticator. This class, MakeCredentialParameters, builds the parameters for the message from the client to the authenticator. Hence, this method will build the extension in the structure specified by the standard in the message from the client to the YubiKey.

Note that the standard specifies that the the message from RP to client contains the same information as the message from the client to the authenticator, just in a different format. Furthermore, the message from the RP to the client contains extra information, namely a boolean indicating the RP's request on how to handle the case where the authenticator does not support user verification (UV). That boolean is not passed down to the YubiKey and it is the responsibility of the client to handle that logic.

Because this extension is used more often, a dedicated method is provided as a convenience. There is no need for the caller to encode the credProtectPolicy. That is, this is essentially the same as calling AddExtension, except this method will verify the YubiKey supports the extension, verify the data, use the appropriate >extensionString, and encode the value.

The caller supplies the AuthenticatorInfo for the YubiKey, obtained by calling the GetInfoCommand or providing the AuthenticatorInfo property.

This method will determine from the authenticatorInfo whether the YubiKey supports this extension, and whether the data provided is correct for the YubiKey's support for "credProtect".

The standard defines three policies: 

UserVerificationOptional
UserVerificationOptionalWithCredentialIDList
UserVerificationRequired
The SDK provides for one more option: None.

The policy UserVerificationOptionalWithCredentialIDList means that the authenticator may or may not enforce UV if the request for an assertion is accompanied by a credential ID (see the allowList in GetAssertionParameters). If there is no credential ID (no allowList), then UV is required to get an assertion.

You can see the "credProtect" policy in the MakeCredentialData.AuthenticatorData.Extensions property once the credential has been made. See GetCredProtectExtension().

Note that while the "credProtect" policy refers to how the credential is protected when getting an assertion, the "credProtect" policy is not returned by the YubiKey in the GetAssertionData.AuthenticatorData.Extensions.

If you pass None as the credProtectPolicy, this method will do nothing and return. The "credProtect" policy of the credential will be the YubiKey's default.

Exceptions

ArgumentNullException

The authenticatorInfo arg is null.

NotSupportedException

The YubiKey does not support this extension, or the input values were not correct.

AddExtension(string, byte[])

Add an entry to the extensions list.

public void AddExtension(string extensionKey, byte[] encodedValue)

Parameters

extensionKey string

The key of key/value to add.

encodedValue byte[]

The CBOR-encoded value of key/value to add.

Remarks

If there is no list yet when this method is called, one will be created. That is, even if the Extensions is null, you can call the method to add an entry.

Each extension is a key/value pair. For each extension the key is a string (such as "credProtect" or "hmac-secret"). However, each value is different. There will be a definition of the value that accompanies each key. It will be possible to encode that definition using the rules of CBOR. The caller supplies the key and the encoded value. This method copies a reference to the byte array value.

Exceptions

ArgumentNullException

The extensionKey or encodedValue arg is null.

AddHmacSecretExtension(AuthenticatorInfo)

Add the "hmac-secret" extension, meaning the YubiKey will generate a secret value to be associated with the credential made. When getting an assertion, it will be possible to get the secret value. Note that the hmac-secret extension is valid for both discoverable and non-discoverable credentials.

public void AddHmacSecretExtension(AuthenticatorInfo authenticatorInfo)

Parameters

authenticatorInfo AuthenticatorInfo

The FIDO2 AuthenticatorInfo for the YubiKey being used.

Remarks

Because this extension is used more often, a dedicated method is provided as a convenience. There is no need for the caller to encode the hmacSecretValue. That is, this is essentially the same as calling AddExtension, except this method will verify the YubiKey supports the extension, and encode the value.

The caller supplies the AuthenticatorInfo for the YubiKey, obtained by calling the GetInfoCommand or providing the AuthenticatorInfo property.

This method will determine from the authenticatorInfo whether the YubiKey supports this extension.

The hmac-secret data will be returned when the credential is used to get an assertion. When building the GetAssertion parameters, the caller must specify that the YubiKey return the hmac-secret. See RequestHmacSecretExtension(ReadOnlyMemory<byte>, ReadOnlyMemory<byte>?). The assertion returned will contain the hmac-secret output. The result will be returned in the AuthenticatorData and can be retrieved using GetHmacSecretExtension(PinUvAuthProtocolBase)

Exceptions

ArgumentNullException

The authenticatorInfo arg is null.

ArgumentException

The YubiKey does not support this extension.

AddMinPinLengthExtension(AuthenticatorInfo)

Specify that the YubiKey should return the minimum PIN length with the credential.

public void AddMinPinLengthExtension(AuthenticatorInfo authenticatorInfo)

Parameters

authenticatorInfo AuthenticatorInfo

The FIDO2 AuthenticatorInfo for the YubiKey being used.

Remarks

Because this extension is used more often, a dedicated method is provided as a convenience. Note that the minimum PIN length is visible to only those RPs who have permission. See the documentation for TrySetPinConfig(int?, IReadOnlyList<string>?, bool?) and the User's Manual entry on the minimum PIN length.

When the YubiKey makes the credential, it will be sent to the relying party. At that point, the relying party can reject it. One reason an RP might reject a credential is if the minimum PIN length is too short.

If the RP for which the credential is being built is not allowed to see the minimum PIN length, the YubiKey will simply not return the minimum PIN length. This is not an error. The credential will be made, but it will not contain the minimum PIN length.

If the minimum PIN length is returned with the credential, it will be in the AuthenticatorData and can be retrieved using GetMinPinLengthExtension()

The caller supplies the AuthenticatorInfo for the YubiKey, obtained by calling the GetInfoCommand or providing the AuthenticatorInfo property. This method will determine from the authenticatorInfo whether the YubiKey supports this extension.

AddOption(string, bool)

Add an entry to the list of options.

public void AddOption(string optionKey, bool optionValue)

Parameters

optionKey string

The option to add. This is the key of the option key/value pair.

optionValue bool

The value this option will possess.

Remarks

If the Options list already contains an entry with the given optionKey, this method will replace it.

Note that the standard specifies valid option keys. Currently they are "rk", "up", and "uv". This method will accept any key given and pass it to the YubiKey. If an invalid key is used, the YubiKey will return an error.

Exceptions

ArgumentNullException

The optionKey arg is null.

CborEncode()

Return a new byte array that is the object encoded following the FIDO2/CBOR standard.

public byte[] CborEncode()

Returns

byte[]

The encoded construct.

Exceptions

InvalidOperationException

The object contains no data.

ExcludeCredential(CredentialId)

Add an entry to the exclude list.

public void ExcludeCredential(CredentialId credentialId)

Parameters

credentialId CredentialId

The credentialId to add.

Remarks

If there is no list yet when this method is called, one will be created. That is, even if the ExcludeList is null, you can call the method to add an entry.

Exceptions

ArgumentNullException

The credentialId arg is null.