TryAddCredential Method
TryAddCredential(ReadOnlyMemory<Byte>, CredentialWithSecrets, out Nullable<Int32>)
Add a credential.
public bool TryAddCredential(ReadOnlyMemory<byte> managementKey, CredentialWithSecrets credentialWithSecrets, out Nullable<int> managementKeyRetries)Parameters
| Type | Name | Description |
|---|---|---|
| System.ReadOnlyMemory<System.Byte> | managementKey | The secret used to authenticate to the application prior to adding or removing credentials. It must be exactly 16 bytes long (see ValidManagementKeyLength). |
| CredentialWithSecrets | credentialWithSecrets | The credential to be added. |
| System.Nullable<System.Int32> | managementKeyRetries | When the command fails to authenticate the management key, this value gives the number of retries remaining. |
Returns
True, when the credential has been added successfully. False,
when authentication with the management key failed.
When this method returns false, managementKeyRetries
gives the number of retries remaining to authenticate with the
management key.
Exceptions
| Type | Condition |
|---|---|
| System.InvalidOperationException | Either a credential with that label already exists, or there is no space to add the credential. |
Remarks
There is a limit of 8 attempts to authenticate with the management key before the management key is blocked. Once the management key is blocked, the application must be reset before performing operations which require authentication with the management key (such as adding credentials, deleting credentials, and changing the management key). To reset the application, see ResetApplication(). Supplying the correct management key before the management key is blocked will reset the retry counter to 8.
TryAddCredential(CredentialWithSecrets)
Add a credential. This method uses the KeyCollector to retrieve the management key and will retry authentication while there are retries remaining.
public bool TryAddCredential(CredentialWithSecrets credentialWithSecrets)Parameters
| Type | Name | Description |
|---|---|---|
| CredentialWithSecrets | credentialWithSecrets | The credential to be added. |
Returns
True when the credential was successfully added.
False when the KeyCollector returns false
(usually indicating user cancellation).
Remarks
Compared to TryAddCredential(ReadOnlyMemory<Byte>, CredentialWithSecrets, out Nullable<Int32>) and AddCredential(ReadOnlyMemory<Byte>, CredentialWithSecrets) which only attempt authentication once, this method automatically retries authentication while there are retries remaining.
The management key is used to authenticate to the application prior to operations such as adding or removing credentials. It must be exactly 16 bytes long (see ValidManagementKeyLength). There is a limit of 8 attempts to authenticate with the management key before the management key is blocked. Once the management key is blocked, the application must be reset before performing operations which require authentication with the management key (such as adding credentials, deleting credentials, and changing the management key). To reset the application, see ResetApplication(). Supplying the correct management key before the management key is blocked will reset the retry counter to 8.
When the management key is needed, the KeyCollector is
called with Request set to
AuthenticateYubiHsmAuthManagementKey.
The KeyCollector gets the management key from the user,
saves it using SubmitValue(ReadOnlySpan<Byte>),
and returns true. If the command succeeds (the credential is
removed), this method returns true.
If authentication fails and there are retries remaining, the
KeyCollector will be called again with the same Request,
but IsRetry will be true and
RetriesRemaining will be set appropriately.
When there are no retries remaining, a System.Security.SecurityException
will be thrown.
The only time this method returns false is when the
KeyCollector cancels the operation by returning false.
Cancellation usually happens when the user has clicked a "Cancel"
button.
In all situations, when this method ends, it will tell the
KeyCollector it is done by calling it with the Request
set to Release.