Table of Contents

Class PasswordAuthentication

Namespace
The.Security
Assembly
Instagile.dll

Authenticator plugin based on a username and password.

public class PasswordAuthentication : IAuthentication
Inheritance
PasswordAuthentication
Implements
Inherited Members

Remarks

this authenticator is designed to allow server-initiated encryption using a key-derivation function. it works like this:

  • as usual, a hash is derived from an entered password and randomly generated salt. both are stored on the server
  • the hash (derived key) is not used for server-side verification, but as a temporary symmetric key to encrypt a session key (or something else)
  • the salt (challenge) is sent by the server to the client, which uses it to recreate the hash and decrypt the session key (or something else) this protocol enables key exchange over an unsecured channel by a client who knows a password and a server who knows the password's hash only

Constructors

PasswordAuthentication(IEnumerable<PasswordRule>) 

public PasswordAuthentication(IEnumerable<PasswordRule> rules)

Parameters

rules IEnumerable<PasswordRule>

PasswordAuthentication(params PasswordRule[]) 

public PasswordAuthentication(params PasswordRule[] rules)

Parameters

rules PasswordRule[]

Fields

DIFFICULTY 

public const int DIFFICULTY = 10000

Field Value

int

HASH_KEY 

public const string HASH_KEY = "pbkdf.hash"

Field Value

string

REALM_KEY 

public const string REALM_KEY = "pbkdf"

Field Value

string

SALT_BYTES 

public const int SALT_BYTES = 32

Field Value

int

SALT_KEY 

public const string SALT_KEY = "pbkdf.salt"

Field Value

string

Properties

AllowAutomaticLogin

Whether to allow the user to automatically log in with saved credentials. Requires AllowSavedCredentials=true.

public bool AllowAutomaticLogin { get; set; }

Property Value

bool

AllowChangePassword

Whether to generate a "Change password" menu command.

public bool AllowChangePassword { get; set; }

Property Value

bool

AllowSavedCredentials

Whether to allow the user to save credentials so that they don't have to enter them manually every time.

public bool AllowSavedCredentials { get; set; }

Property Value

bool

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

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.

MinimumPasswordStrengthScore 

public PasswordStrength MinimumPasswordStrengthScore { get; set; }

Property Value

PasswordStrength

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

If not null, causes UseIntegratedLogin to use PasswordOnlyLoginHandler, which will obtain a username from this function.

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

Property Value

Func<string>

Methods

ChangeCurrentUserPasswordAsync(IServices, string, string) 

public static Task ChangeCurrentUserPasswordAsync(IServices services, string currentPassword, string newPassword)

Parameters

services IServices
currentPassword string
newPassword string

Returns

Task

CreateHash(string) 

public static (string salt, string hash) CreateHash(string password)

Parameters

password string

Returns

(string salt, string hash)

CreateHash(string, string) 

public static string CreateHash(string password, string salt)

Parameters

password string
salt string

Returns

string

CreateHash(Credentials) 

public AuthenticationResult<(string salt, string hash)> CreateHash(Credentials credentials)

Parameters

credentials Credentials

Returns

AuthenticationResult<(string salt, string hash)>

DecryptDataAsync(IAlgorithmProvider, Credentials, byte[])

decrypt a message addressed to the supplied credentials

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

Parameters

algorithmProvider IAlgorithmProvider
credentials Credentials
packet byte[]

Returns

Task<AuthenticationResult<byte[]>>

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

EncryptDataAsync(IAlgorithmProvider, IEntityContext, Identity, 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, IEntityContext context, Identity subject, byte[] data)

Parameters

algorithmProvider IAlgorithmProvider
context IEntityContext
subject Identity
data byte[]

Returns

Task<AuthenticationResult<byte[]>>

encrypted message

GetCurrentUsernameAndHashAsync(IServices) 

public static Task<(string username, string hash, string salt)> GetCurrentUsernameAndHashAsync(IServices services)

Parameters

services IServices

Returns

Task<(string username, string hash, string salt)>

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>>

RemoveUsernameAndPasswordAsync(IUserAccount, CancellationToken?) 

public static Task RemoveUsernameAndPasswordAsync(IUserAccount account, CancellationToken? cancellationToken = null)

Parameters

account IUserAccount
cancellationToken CancellationToken?

Returns

Task

SetUsernameAndPasswordAsync(IUserAccount, string, string, CancellationToken?) 

public static Task SetUsernameAndPasswordAsync(IUserAccount account, string username, string password, CancellationToken? cancellationToken = null)

Parameters

account IUserAccount
username string
password string
cancellationToken CancellationToken?

Returns

Task

ValidatePassword(string) 

public string? ValidatePassword(string password)

Parameters

password string

Returns

string

VerifyIdentity(Credentials, string)

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

public AuthenticationResult VerifyIdentity(Credentials credentials, string subject)

Parameters

credentials Credentials
subject 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)