Authenticate Method

Authenticate(ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, ReadOnlyMemory<Byte>, TimeSpan, Boolean)

Authenticates a credential. Throw an exception if the method is not able to perform the operation.

public AuthenticationData Authenticate(ReadOnlyMemory<byte> applicationId, ReadOnlyMemory<byte> clientDataHash, ReadOnlyMemory<byte> keyHandle, TimeSpan timeout, bool requireProofOfPresence = true)

Parameters

Type	Name	Description
System.ReadOnlyMemory<System.Byte>	applicationId	Also known as the origin data. A SHA-256 hash of the UTF-8 encoding of the application or service requesting the authentication. See the user's manual article on How Fido U2F works for more information.
System.ReadOnlyMemory<System.Byte>	clientDataHash	A SHA-256 hash of the client data, a stringified JSON data structure that the caller prepares. Among other things, the client data contains the challenge from the relying party (the application or service that this registration is for). See the user's manual article on How Fido U2F works for more information.
System.ReadOnlyMemory<System.Byte>	keyHandle	The key handle the YubiKey returned during registration. That value was sent to the relying party and now is being returned to the YubiKey (via the client).
System.TimeSpan	timeout	The amount of time this method will wait for user touch. The recommended timeout is 5 seconds. The minimum is 1 second and the maximum is 30 seconds. If the input is greater than 30 seconds, this method will set the timeout to 30. If the timeout is greater than 0 but less than one second, the method will set the timeout to 1 second. If the timeout is zero, this method will set no timeout and wait for touch indefinitely (zero timeout means no timeout).
System.Boolean	requireProofOfPresence	If `true`, then the user must provide proof of presence in order to complete the authentication. If `false`, proof of presence is not necessary. The default is `true` so if no value is given for this argument, it will be `true`. With the YubiKey proof of user presence is touch.

Returns

AuthenticationData

A structure containing the results of the credential authentication, including the signature.

Exceptions

Type	Condition
System.TimeoutException	The user presence check timed out.
System.InvalidOperationException	The input data was invalid (e.g. the appId was not 32 bytes) or else the key handle was not correct for the appId.

Remarks

The client gets the key handle along with the challenge from the relying party, and computes the application ID (origin data) and the client data hash using the challenge. The client then sends the relevant data to the YubiKey. If the YubiKey can build a private key from the key handle, it will sign the appId and client data hash. This is how the YubiKey authenticates to the relying party.

The YubiKey will also be able to use the key handle to verify it is talking to a relying party with which it is registered. If the key handle can be "converted" into an actual key matching the origin data, then the YubiKey will compute a signature. If not, the YubiKey will reject the key handle and this method will throw an exception (with the message "The request was rejected due to an invalid key handle.").

The application ID is a SHA-256 hash of the UTF-8 encoding of the application or service (the relying party) requesting the registration. This is also known as the origin data. For a website, this is typically the https address of the primary domain, not including the final slash. For example, https://fido.example.com/myApp. If there are multiple addresses than can be associated with this credential, the application ID should refer to a single trusted facet list. This is a JSON structure that contains a list of URI / IDs that the client should accept.

Non-websites may use FIDO U2F. Therefore their applicationId will most likely not be a URL. Android and iOS have their own special encodings based on their application package metadata. Clients on Linux, macOS, and Windows have fewer guidelines and can usually be defined by the application. See the How FIDO U2f works page in the user's manual for more information.

The U2F standard specifies that a client can call on the token to authenticate and require proof of user presence or not. That is, the client can ask the token to authenticate directly with no further user interaction. This argument is true by default, meaning proof of presence is required. With the YubiKey, proof of user presence is touch. Note that if this argument is false, then this method will ignore the timeout argument.

A version 4 FIPS YubiKey can have a PIN set on the U2F application. That PIN applies to registration only. A PIN is never needed to perform authentication.