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 : AuthenticatorOperationParameters<MakeCredentialParameters>, ICborEncode
Inheritance
object
MakeCredentialParameters
Implements
Inherited Members

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).

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.

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.

AddHmacSecretMcExtension(AuthenticatorInfo, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>?)

Adds the "hmac-secret-mc" extension to the make credential operation, which is used to support HMAC-secret mechanism with backward compatibility. This method specifies the required salt values for the operation.

public void AddHmacSecretMcExtension(AuthenticatorInfo authenticatorInfo, ReadOnlyMemory<byte> salt1, ReadOnlyMemory<byte>? salt2 = null)

Parameters

authenticatorInfo AuthenticatorInfo

The FIDO2 AuthenticatorInfo for the YubiKey being used.

salt1 ReadOnlyMemory<byte>

The first required salt value, which must be exactly 32 bytes in length. If this condition is not met, an exception will be thrown.

salt2 ReadOnlyMemory<byte>?

An optional second salt value, which must also be exactly 32 bytes in length if provided. If this condition is not met, an exception will be thrown.

Remarks

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

ArgumentException

Thrown when the length of either salt1 or salt2 (if provided) does not equal the required 32 bytes.

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.

AddThirdPartyPaymentExtension()

Specify that the credential being created should be designated for third-party payment authentication.

public void AddThirdPartyPaymentExtension()

Remarks

This enables the credential to be used in payment flows initiated by a party other than the Relying Party, as defined by standards like W3C's Secure Payment Confirmation.

CborEncode()

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

public override byte[] CborEncode()

Returns

byte[]

The encoded construct.

Exceptions

InvalidOperationException

The object contains no data.

EncodeHmacSecretExtension(PinUvAuthProtocolBase)

Encode the "hmac-secret" extension. This should be called before issuing the MakeCredentialCommand. The call will be valid only if the AddHmacSecretMcExtension(AuthenticatorInfo, ReadOnlyMemory<byte>, ReadOnlyMemory<byte>?) has been called, and the Encapsulate(CoseKey) method has been successfully called.

Note

If you use MakeCredential(MakeCredentialParameters) you do not need to call this method.

public void EncodeHmacSecretExtension(PinUvAuthProtocolBase authProtocol)

Parameters

authProtocol PinUvAuthProtocolBase

An instance of one of the subclasses of PinUvAuthProtocolBase, for which the Encapsulate method has been called.

Remarks

If the AddHmacSecretMcExtension method has not been called, this method will do nothing. If it has been called, but the authProtocol has not been encapsulated, this method will throw an exception.

The result of this method is returned in the MakeCredentialData AuthenticatorData and can be retrieved using GetHmacSecretExtension(PinUvAuthProtocolBase)

Exceptions

ArgumentNullException

The authProtocol arg is null.

InvalidOperationException

The Encapsulate method for the authProtocol has not been called.

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.