AddPermissions Method
AddPermissions(PinUvAuthTokenPermissions, String)
Obtain a PinUvAuthToken that possesses the given permissions along with the current permissions. This is generally called early in a session to specify which set of permissions you expect to need for the operations you will be calling.
public void AddPermissions(PinUvAuthTokenPermissions permissions, string relyingPartyId = null)
Parameters
Type | Name | Description |
---|---|---|
PinUvAuthTokenPermissions | permissions | An OR of all the permissions you expect to be needed during the session. |
System.String | relyingPartyId | If needed or wanted, how to specify the relying party in question. The default for this parameter is null, so if no arg is given, then there will be no relying party specified. |
Exceptions
Type | Condition |
---|---|
System.ArgumentException | The connected YubiKey does not support the permissions given, or a relying party was specified but no permissions were specified. |
System.InvalidOperationException | The permission requires a relyingPartyId and none is given. |
Remarks
See the User's Manual entry for a deeper discussion of FIDO2 authentication and how AuthTokens, PinTokens, permissions, PIN/UV, and AuthParams fit together.
See also the User's Manual entry
on the SDK's AuthToken logic. That article goes into greater detail
how this method, as well as other operations, perform "automatic"
AuthToken retrieval based on the version of the connected YubiKey,
the state of the Fido2 application on the YubiKey, the input, and the
state of the Fido2Session
.
This method will use the KeyCollector to obtain the PIN
or prompt for user verification (fingerprint on YubiKey Bio). If no
KeyCollector
is loaded, then this method will throw an
exception.
If the connected YubiKey does not support the option
pinUvAuthToken
, then there is likely no need to call this
method. But if you do, the relyingPartyId
arg must be null and
the permissions
arg must be None
. To know if the
YubiKey supports it, make this call.
IYubiKeyDevice yubiKeyToUse = SelectYubiKey();
using (var fido2Session = new Fido2Session(yubiKeyToUse))
{
if (fido2Session.AuthenticatorInfo.GetOptionValue(
AuthenticatorOptions.pinUvAuthToken) == OptionValue.True)
{
fido2Session.AddPermissions(
PinUvAuthTokenPermissions.GetAssertion | PinUvAuthTokenPermissions.CredentialManagement,
relyingPartyIdOfInterest);
}
}
Generally, YubiKeys that support only FIDO2 version 2.0 will not
support pinUvAuthToken
and YubiKeys that support FIDO2 version
2.1, will support it. See also the
User's Manual entry
on the SDK's AuthToken logic for more details on using this method
with a YubiKey that supports only FIDO2 version 2.0.
If the YubiKey does support pinUvAuthToken
, then you can still
call this method with no permissions (None
) and a null
relyingPartyId
. In this case, the SDK will build a PinToken.
See this User's Manual entry for
a deeper discussion of PinTokens on YubiKey that supports
PinUvAuthTokens. If you call with no permissions but with a relying
party ID, then this method will throw an exception.
Note that if you pass in permissions of None
, this method will
obtain an AuthToken that has the same permission set currently set in
the property PinUvAuthTokenPermissions, if there are
any.
If the YubiKey supports PinUvAuthTokens, and this is called with permissions, then this method will determine if the YubiKey has UV capabilities, and if so, whether any bio verification has been enrolled. On the YubiKey, if there is a fingerprint enrolled, this method will first try to authenticate using UV, and if that fails, try to authenticate using PIN (see the FIDO2 standard, sections 6.5.5.7 and 6.5.5.7.3 step 3.10.3).
Calling this method will make sure that the AuthToken property in this class possesses the requested permissions along with any permissions specified in the AuthTokenPermissions property. To do so, this method will always obtain a new AuthToken, even if there is an AuthToken already in the object. More details are in the User's Manual entry on the SDK's AuthToken logic.
The MakeCredential
and GetAssertion
permissions require
a relying party ID. That is, an AuthToken can be used to make a
credential or get an assertion only for a specific relying party. If
the permissions
arg does not include MakeCredential
or
GetAssertion
, then the relyingPartyId
arg can be null.
More details are in the
User's Manual entry
on the SDK's AuthToken logic.
It is not necessary to call this method at the beginning. However, if you do not make this call, then each time the SDK needs an AuthToken, it will obtain one with only one permission. That means that if you perform more than one operation, you might be called upon to obtain the PIN from the user, or require the user to perform user verification several times during this session.
An alternative to this method and the "automatic" AuthToken
collection the SDK performs is to call
TryVerifyPin(ReadOnlyMemory<Byte>, Nullable<PinUvAuthTokenPermissions>, String, out Nullable<Int32>, out Nullable<Boolean>),
TryVerifyUv(PinUvAuthTokenPermissions, String) or
some other verification method directly. However, because AuthTokens
"expire" (see the User's Manual entry
on AuthTokens), it is possible you will need to re-verify during a
session. Hence, if you want to avoid this method or not build a
KeyCollector
, then you must write your code so that it calls,
if needed, the appropriate Verify
method before performing an
operation. That is, you must then write your code so that it adheres
to the permissions and expriy logic of FIDO2.