Table of Contents

Enum KeyEntryRequest

Namespace
Yubico.YubiKey
Assembly
Yubico.YubiKey.dll

This lists the possible actions or information the caller is requesting.

public enum KeyEntryRequest

Fields

AuthenticatePivManagementKey = 5

Indicates that the SDK is requesting the current PIV management key in order to authenticate.

When the Request is this value, the delegate should collect one management key and submit it using the SubmitValue method.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is false, the KeyEntryData is making the initial request.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is true, the KeyEntryData is reporting that a previous attempt at authenticating the management key failed and the KeyCollector should try again to obtain the value (unless the user decides to cancel).

AuthenticateYubiHsmAuthCredentialPassword = 19

Indicates that the SDK is requesting the YubiHSM Auth credential's password in order to authenticate.

When the Request is AuthenticateYubiHsmAuthCredentialPassword, the delegate should collect the current management key and submit it using SubmitValue(ReadOnlySpan<byte>).

When the Request is AuthenticateYubiHsmAuthCredentialPassword and IsRetry property is false, this is the initial request for the management key.

When the Request is AuthenticateYubiHsmAuthCredentialPassword and IsRetry is true, this means a previous attempt at authenticating the management key failed and the KeyCollector should try again to obtain the value. In this situation, RetriesRemaining will contain additional information.

AuthenticateYubiHsmAuthManagementKey = 17

Indicates that the SDK is requesting the current YubiHSM Auth management key in order to authenticate.

When the Request is this value, the delegate should collect the current management key and submit it using SubmitValue(ReadOnlySpan<byte>).

When the Request is this value and IsRetry property is false, this is the initial request for the management key.

When the Request is this value and IsRetry is true, this means a previous attempt at authenticating the management key failed and the KeyCollector should try again to obtain the value. In this situation, RetriesRemaining will contain additional information.

ChangeFido2Pin = 14

Indicates that the SDK is requesting the current FIDO2 PIN and a new PIN, in order to change the PIN from the current to the new. Collect both the current and new PINs.

ChangePivManagementKey = 6

Indicates that the SDK is requesting the current PIV management key and a new PIV management key, in order to change the key from the current to the new. Collect both the current and a new management key.

When the Request is this value, the delegate should collect two keys and submit them using the SubmitValues method.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is false, the KeyEntryData is making the initial request.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is true, the KeyEntryData is reporting that a previous attempt at changing the management key failed and the KeyCollector should try again to obtain the values (unless the user decides to cancel).

Note that the most likely reason a change will fail is because the current management key was incorrect, but it can also fail if the new management key is not valid (e.g. too short).

ChangePivPin = 2

Indicates that the SDK is requesting the current PIV PIN and a new PIN, in order to change the PIN from the current to the new. Collect both the current and a new PIN.

When the Request is this value, the delegate should collect two PINs and submit them using the SubmitValues method.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is false, the KeyEntryData is making the initial request.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is true, the KeyEntryData is reporting that a previous attempt at changing the PIN failed and the KeyCollector should try again to obtain the values (unless the user decides to cancel).

Note that the most likely reason a change will fail is because the current PIN was incorrect, but it can also fail if the new PIN is not valid (e.g. too short).

ChangePivPuk = 4

Indicates that the SDK is requesting the current PIV PUK and a new PUK, in order to change the PUK from the current to the new. Collect both the current and a new PUK.

When the Request is this value, the delegate should collect two PUKs and submit them using the SubmitValues method.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is false, the KeyEntryData is making the initial request.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is true, the KeyEntryData is reporting that a previous attempt at changing the PUK failed and the KeyCollector should try again to obtain the values (unless the user decides to cancel).

ChangeU2fPin = 11

Indicates that the SDK is requesting the current FIDO U2F PIN and a new PIN, in order to change the PIN from the current to the new. Collect both the current and a new PIN.

ChangeYubiHsmAuthManagementKey = 18

This indicates that the SDK is attempting to change the YubiHSM Auth management key. It is requesting the current YubiHSM Auth management key and a new YubiHSM Auth management key as part of the operation.

When the Request is ChangeYubiHsmAuthManagementKey, the delegate should collect the current management key and submit it using SubmitValues(ReadOnlySpan<byte>, ReadOnlySpan<byte>).

When the Request is ChangeYubiHsmAuthManagementKey and IsRetry property is false, this is the initial request for the management key.

When the Request is ChangeYubiHsmAuthManagementKey and IsRetry istrue, this means a previous attempt at changing the management key failed and the KeyCollector should try again to obtain the value. In this situation, RetriesRemaining will contain additional information.

EnrollFingerprint = 20

Indicates that the SDK is requesting the user provide a fingerprint sample.

When enrolling a fingerprint, the process will generally require several samples. It is also likely you will want to display different messages based on whether this is the first call for a sample, and whether it is a later, "repeat" sample used to "reinforce" the original sample. Hence, when the Request property is EnrollFingerprint, look at the LastBioEnrollSampleResult property. If it is null, this is the first call, and if it is not null, this is a subsequent call.

Release = 0

Indicates that the SDK has successfully used the element(s) requested and the caller can now release any resources related to obtaining the data.

Note that a delegate MUST NEVER throw an exception if the Request is Release. The Release is called from inside a finally block, and it is a bad idea to throw exceptions from inside finally.

ResetPivPinWithPuk = 3

Indicates that the SDK is requesting the PIV PUK and a new PIN. This is the first call. This is used to recover the PIN using the PUK. Collect both the current PUK and a new PIN.

After collecting the PUK and a new PIN, submit them using the SubmitValues method, with the PUK as the currentValue and the PIN as the newValue.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is false, the KeyEntryData is making the initial request.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is true, the KeyEntryData is reporting that a previous attempt at resetting the PIN failed and the KeyCollector should try again to obtain the values (unless the user decides to cancel).

Note that the most likely reason a reset will fail is because the PUK was incorrect, but it can also fail if the new PIN is not valid (e.g. too short).

SetFido2Pin = 13

Indicates that the SDK is setting the FIDO2 PIN. The YubiKey is not set with a FIDO2 PIN yet, so only collect a new PIN.

SetOathPassword = 8

Indicates that the SDK is requesting a new password. Collect a new password.

When the Request is this value, the delegate should collect a password and submit it using the SubmitValues method.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is false, the KeyEntryData is making the initial request.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is true, the KeyEntryData is reporting that a previous attempt at setting the password failed and the KeyCollector should try again to obtain the values (unless the user decides to cancel).

SetU2fPin = 10

Indicates that the SDK is setting the FIDO U2F PIN. The YubiKey is not set with a U2F PIN yet, so collect only a new PIN.

TouchRequest = 9

The YubiKey is requesting touch for user presence verification. See the User's Manual entry on how to handle a touch notification in a key collector.

When the Request is this value, the delegate does not need to collect any passwords or keys. This is simply used as a means to alert the application that the YubiKey is awaiting a touch. Typically, you will want to respond to this request by alerting your user that they need to physically touch the YubiKey.

In addition, when the SDK calls a KeyCollector with this request, it will ignore the return value. That is, it is not possible to cancel this request. However, every YubiKey operation that requires touch has a timeout, so simply not touching will eventually cancel an operation.

Ideally, you should not block this call. However, to ensure the proper function of the SDK, this request will be issued on a separate thread from the one that originated this call.

VerifyFido2Pin = 15

Indicates that the SDK is verifying the FIDO2 PIN. Collect the current PIN.

VerifyFido2Uv = 16

Indicates that the SDK and YubiKey are waiting for user verification. This usually means touching the biometric sensor on the YubiKey. Nothing to collect, this is an informative request.

VerifyOathPassword = 7

Indicates that the SDK is requesting the OATH password to verify.

When the Request is this value, the delegate should collect one password and submit it using the SubmitValue method.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is false, the KeyEntryData is making the initial request.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is true, the KeyEntryData is reporting that a previous attempt at verifying the password failed and the KeyCollector should try again to obtain the value (unless the user decides to cancel).

VerifyPivPin = 1

Indicates that the SDK is requesting the PIV PIN to verify.

When the Request is this value, the delegate should collect one PIN and submit it using the SubmitValue method.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is false, the KeyEntryData is making the initial request.

When the KeyEntryData.Request is this value and the KeyEntryData.IsRetry property is true, the KeyEntryData is reporting that a previous attempt at verifying the PIN failed and the KeyCollector should try again to obtain the value (unless the user decides to cancel).

VerifyU2fPin = 12

Indicates that the SDK is verifying the FIDO U2F PIN. Collect the current PIN.

Remarks

This is used in conjunction with the KeyEntryData class. When the SDK needs a key, PIN, password, or some other user-supplied secret element, it will call the application-supplied, key-collecting delegate. Inside the KeyEntryData class is a property indicating what the SDK is requesting the delegate to collect.

This enum is the list of possible elements the SDK can request of the delegate.