Class PKIAuthentication

Namespace

The.Security.PKI

Assembly

Instagile.dll

authenticates users using public/private key cryptography

public class PKIAuthentication : IAuthentication

Inheritance

object

PKIAuthentication

Implements

IAuthentication

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Constructors

PKIAuthentication(IAnonymousKeyProvider)

use a key provider both for "current" user and to look up named users

public PKIAuthentication(IAnonymousKeyProvider keyProvider)

Parameters

keyProvider IAnonymousKeyProvider

PKIAuthentication(IKeyProvider)

use a key provider only to look up named users

public PKIAuthentication(IKeyProvider keyProvider)

Parameters

keyProvider IKeyProvider

Properties

CanEncrypt

true if the authenticator supports secured key exchange

public bool CanEncrypt { get; }

Property Value

bool

Remarks

this is used to establish shared secrets. implementations could be based on public key cryptography, diffie-helmann, or out of band methods

CanLookup

true if the authenticator supports looking up an IUserAccount for an authenticator-specific username

public bool CanLookup { get; }

Property Value

bool

CanSign

true if the authenticator supports digital signatures (not necessarily cryptographic)

public bool CanSign { get; }

Property Value

bool

Remarks

signature doesn't have to be based on the operation; it can use some other capability like ambient windows logon

IsAuthoritative

If true, the returned identity should be accepted without server verification

public bool IsAuthoritative { get; }

Property Value

bool

Remarks

May depend on ambient state - don't cache the result. As well as enabling automatic login, this is used by SecurityService to decide whether it's ok to perform purely-local authentication without calling IEntityStore.Connect.

LookupAccountByUsername

Whether to look up user accounts by their username, or by their PKI key name claim (see REALM_CLAIM).

public bool LookupAccountByUsername { get; init; }

Property Value

bool

Remarks

Set this to true on the backend when clients are using UsernameProvider.

Realm

Describes identities within the purview of this authenticator

public string Realm { get; }

Property Value

string

RequiresCredentials

Expects non-empty Credentials in order to perform client-side identity operations

public bool RequiresCredentials { get; }

Property Value

bool

UsernameProvider

Overrides the identity returned by GetIdentity(Credentials), which would normally return the default key name from IAnonymousKeyProvider.

public Func<string>? UsernameProvider { get; init; }

Property Value

Func<string>

Remarks

The authentication on the backend should set LookupAccountByUsername to true when this property has been set.

Methods

CheckSignatureAsync(IEntityContext, Identity, byte[], byte[])

check a signature by the specified identity (which may be from various realms)

public Task<AuthenticationResult> CheckSignatureAsync(IEntityContext context, Identity subject, byte[] operation, byte[] token)

Parameters

context IEntityContext

subject Identity

operation byte[]

token byte[]

Returns

Task<AuthenticationResult>

(signature found for user, null/reason for failure)

CreateKeyPairInteractive()

public AuthenticationResult CreateKeyPairInteractive()

Returns

AuthenticationResult

CreateSignatureAsync(Credentials, byte[])

sign a message using the supplied credentials

public Task<AuthenticationResult<byte[]>> CreateSignatureAsync(Credentials credentials, byte[] operation)

Parameters

credentials Credentials

operation byte[]

Returns

Task<AuthenticationResult<byte[]>>

opaque signature

DecryptDataAsync(IAlgorithmProvider, Credentials, byte[])

decrypt a message addressed to the supplied credentials

public Task<AuthenticationResult<byte[]>> DecryptDataAsync(IAlgorithmProvider algorithmProvider, Credentials credentials, byte[] ciphertext)

Parameters

algorithmProvider IAlgorithmProvider

credentials Credentials

ciphertext byte[]

Returns

Task<AuthenticationResult<byte[]>>

(decrypted message/null, null/reason for failure)

EncryptDataAsync(IAlgorithmProvider, object?, byte[])

create an encrypted message which can only be decrypted by the specified subject (which will be an account username if CanLookup)

public Task<AuthenticationResult<byte[]>> EncryptDataAsync(IAlgorithmProvider algorithmProvider, object? state, byte[] data)

Parameters

algorithmProvider IAlgorithmProvider

state object

data byte[]

Returns

Task<AuthenticationResult<byte[]>>

encrypted message

GetIdentity(Credentials)

Extract a subject from the environment or the supplied credentials.

public AuthenticationResult<string> GetIdentity(Credentials credentials)

Parameters

credentials Credentials

Returns

AuthenticationResult<string>

subject name, unverified - from local knowledge only

LookupAccount(IEntityContext, string)

public AuthenticationResult<string> LookupAccount(IEntityContext context, string subject)

Parameters

context IEntityContext

subject string

Returns

AuthenticationResult<string>

LookupAccountAsync(IEntityContext, string)

Find the username of an IUserAccount for a username produced by this authenticator.

public Task<AuthenticationResult<string>> LookupAccountAsync(IEntityContext context, string subject)

Parameters

context IEntityContext

subject string

Returns

Task<AuthenticationResult<string>>

PrepareSessionAsync(IEntityContext, Identity)

Prepare an encrypted session with the specified subject by looking up their account and retrieving authentication state.

public Task<AuthenticationResult<Handshake<object?>>> PrepareSessionAsync(IEntityContext context, Identity subject)

Parameters

context IEntityContext

subject Identity

Returns

Task<AuthenticationResult<Handshake<object>>>

A handshake containing the session type and associated state for use in subsequent encryption operations.

VerifyIdentity(Credentials, string)

Verify that the subject matches the supplied credentials. Available synchronously only if IsAuthoritative returns true.

public AuthenticationResult VerifyIdentity(Credentials credentials, string subjectOrError)

Parameters

credentials Credentials

subjectOrError string

Returns

AuthenticationResult

(true/false for authentication state, null/reason for failure)

VerifyIdentityAsync(Credentials, IEntityContext, string)

verify that the subject matches the supplied credentials

public Task<AuthenticationResult> VerifyIdentityAsync(Credentials credentials, IEntityContext context, string subject)

Parameters

credentials Credentials

context IEntityContext

subject string

Returns

Task<AuthenticationResult>

(true/false for authentication state, null/reason for failure)