Class FinSecurityMediaKeyFile

Abstract base class for all key file based IFinSecurityMedia interface implementations.

Inheritance
object
FinSecurityMediaKeyFile
FinSecurityMediaALF
FinSecurityMediaFST
FinSecurityMediaRDH2
FinSecurityMediaSIZ
Implements
Inherited Members
Namespace: Subsembly.FinTS
Assembly: Subsembly.FinTS.Core.dll
Syntax
public abstract class FinSecurityMediaKeyFile : IFinSecurityMedia
Remarks

This class implements all methods of the IFinSecurityMedia interface, delegating key file specific work to some abstract methods that must be overridden by the derived concrete class.

Constructors

FinSecurityMediaKeyFile()

Declaration
protected FinSecurityMediaKeyFile()

Properties

Capabilities

Declaration
public FinSecurityMediaCaps Capabilities { get; }
Property Value
Type Description
FinSecurityMediaCaps
Remarks

A derived class must call SetCapabilities(FinSecurityMediaCaps) in its constructor in order to change the value returned through this property.

ContactCapacity

Number of contacts that are or may be stored in the key file.

Declaration
public int ContactCapacity { get; }
Property Value
Type Description
int
Remarks

This property actually returns the number of contacts that have been added through AddContact(FinContact). Thus, if the actual key file can grow in order to store more contacts, then an additional empty contact record should be added at the end.

MaxKeyLength

By default returns 96.

Declaration
public int MaxKeyLength { get; }
Property Value
Type Description
int
Remarks

A derived class must override OnGetMaxKeyLength() in order to change the value returned through this property.

PassphraseFlags

By default returns None.

Declaration
public FinSecurityMediaPassphraseFlags PassphraseFlags { get; }
Property Value
Type Description
FinSecurityMediaPassphraseFlags
Remarks

A derived class must call SetPassphraseFlags(FinSecurityMediaPassphraseFlags) in its constructor in order to change the value returned through this property.

PassphraseMaxLength

By default returns 256.

Declaration
public int PassphraseMaxLength { get; }
Property Value
Type Description
int
Remarks

A derived class must call SetPassphraseMaxLength(int) in its constructor in order to change the value returned through this property.

PassphraseMinLength

By default returns 0.

Declaration
public int PassphraseMinLength { get; }
Property Value
Type Description
int
Remarks

A derived class must call SetPassphraseMinLength(int) in its constructor in order to change the value returned through this property.

SecurityMediaID

Provides the security media ID of the currently selected key file.

Declaration
public string SecurityMediaID { get; }
Property Value
Type Description
string

SecurityMediaType

Always returns KeyFile.

Declaration
public FinSecurityMediaType SecurityMediaType { get; }
Property Value
Type Description
FinSecurityMediaType

SecurityProfiles

Declaration
public FinSecurityProfile[] SecurityProfiles { get; }
Property Value
Type Description
FinSecurityProfile[]
Remarks

The default implementation always returns an array with a single RDH-1 element.

State

Indicates the current state of this IFinSecurityMedia implementation.

Declaration
public FinSecurityMediaState State { get; }
Property Value
Type Description
FinSecurityMediaState

Methods

AddContact(FinContact)

Declaration
protected void AddContact(FinContact aContact)
Parameters
Type Name Description
FinContact aContact

AddKey(FinSecureKey)

Add another key to this key store.

Declaration
protected void AddKey(FinSecureKey aKey)
Parameters
Type Name Description
FinSecureKey aKey

Authenticate(string, string)

Declaration
public FinAuthenticateResult Authenticate(string sUserName, string sPassphrase)
Parameters
Type Name Description
string sUserName

Optional UserName.
string sPassphrase
Returns
Type Description
FinAuthenticateResult

AuthenticateAdmin(string, string)

Declaration
public FinAuthenticateResult AuthenticateAdmin(string sUserName, string sAdminPassphrase)
Parameters
Type Name Description
string sUserName
string sAdminPassphrase
Returns
Type Description
FinAuthenticateResult

AuthenticateSecure()

Always just returns AuthenticateSecureNotSupported

Declaration
public FinAuthenticateResult AuthenticateSecure()
Returns
Type Description
FinAuthenticateResult

CanAuthenticateSecure()

Declaration
public bool CanAuthenticateSecure()
Returns
Type Description
bool

CanChangePassphraseSecure()

Declaration
public bool CanChangePassphraseSecure()
Returns
Type Description
bool

Cancel()

Declaration
public void Cancel()

ChangePassphrase(string, string, string)

Declaration
public FinAuthenticateResult ChangePassphrase(string sUserName, string sOldPassphrase, string sNewPassphrase)
Parameters
Type Name Description
string sUserName
string sOldPassphrase
string sNewPassphrase
Returns
Type Description
FinAuthenticateResult

ChangePassphraseSecure()

Always just returns AuthenticateSecureNotSupported

Declaration
public FinAuthenticateResult ChangePassphraseSecure()
Returns
Type Description
FinAuthenticateResult

Create(string, string, string)

Declaration
public void Create(string sSecurityMediaID, string sUserName, string sPassphrase)
Parameters
Type Name Description
string sSecurityMediaID
string sUserName
string sPassphrase
Remarks

The default implementation validates the given parameters and the current object State and then delegates to OnCreateKeyFile(string, string).

CreateContact()

Declaration
public FinContact CreateContact()
Returns
Type Description
FinContact

Decrypt(FinContact, FinSecureKey, FinOperationMode, byte[])

Declaration
public byte[] Decrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbCrypt)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
byte[] vbCrypt
Returns
Type Description
byte[]

ElevateKey(FinContact, FinSecureKey, FinSecureKeyState)

Declaration
public void ElevateKey(FinContact aContact, FinSecureKey aKey, FinSecureKeyState nNewKeyState)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinSecureKeyState nNewKeyState

Encrypt(FinContact, FinSecureKey, FinOperationMode, byte[])

Declaration
public byte[] Encrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbData)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
byte[] vbData
Returns
Type Description
byte[]

EraseContact(int)

Declaration
public void EraseContact(int nContactIndex)
Parameters
Type Name Description
int nContactIndex

EraseKey(FinContact, FinSecureKey)

Declaration
public void EraseKey(FinContact aContact, FinSecureKey aKey)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey

GenerateKey(FinContact, FinSecureKeyType, int, int, int)

Generates ans stores a new key.

Declaration
public FinSecureKey GenerateKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyLength, int nKeyNumber, int nKeyVersion)
Parameters
Type Name Description
FinContact aContact
FinSecureKeyType nKeyType
int nKeyLength
int nKeyNumber
int nKeyVersion
Returns
Type Description
FinSecureKey
Remarks

Any existing key with the same attributes will be replaced.

InitPassphrase(string, string)

Always throws a NotSupportedException.

Declaration
public FinAuthenticateResult InitPassphrase(string sUserName, string sPassphrase)
Parameters
Type Name Description
string sUserName
string sPassphrase
Returns
Type Description
FinAuthenticateResult

ObtainContact(int)

Declaration
public FinContact ObtainContact(int nContactIndex)
Parameters
Type Name Description
int nContactIndex
Returns
Type Description
FinContact

ObtainKey(FinContact, FinSecureKeyType, int, int)

Declaration
public virtual FinSecureKey ObtainKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyNumber, int nKeyVersion)
Parameters
Type Name Description
FinContact aContact
FinSecureKeyType nKeyType
int nKeyNumber
int nKeyVersion
Returns
Type Description
FinSecureKey

OnCancel()

Declaration
protected virtual void OnCancel()

OnChangePassphrase(string)

Declaration
protected virtual FinAuthenticateResult OnChangePassphrase(string sNewPassphrase)
Parameters
Type Name Description
string sNewPassphrase
Returns
Type Description
FinAuthenticateResult

OnCreateKeyFile(string, string)

Override in order to create a new key file instance from scratch.

Declaration
protected virtual void OnCreateKeyFile(string sUserName, string sPassphrase)
Parameters
Type Name Description
string sUserName

Optional UserName parameter.
string sPassphrase

The passphrase to be used in order to protect the key file.
Remarks

The default implementation simply throws NotSupportedException.

OnGetMaxKeyLength()

Declaration
protected virtual int OnGetMaxKeyLength()
Returns
Type Description
int

OnGetSecurityProfiles()

Declaration
protected virtual FinSecurityProfile[] OnGetSecurityProfiles()
Returns
Type Description
FinSecurityProfile[]

OnLoadKeyFile(string, string)

Must be overriden in order to fully load a previously selected key file.

Declaration
protected abstract FinAuthenticateResult OnLoadKeyFile(string sUserName, string sPassphrase)
Parameters
Type Name Description
string sUserName

Optional UserName parameter.
string sPassphrase
Returns
Type Description
FinAuthenticateResult

This method is also responsible for checking the passphrase and to return an appropriate FinAuthenticateResult for it.

OnRelease()

Declaration
protected virtual void OnRelease()

OnSaveKeyFile(string)

Declaration
protected virtual void OnSaveKeyFile(string sFileName)
Parameters
Type Name Description
string sFileName

OnSelectKeyFile(string)

Must be overriden in order to select an existing key file.

Declaration
protected abstract FinAuthenticateResult OnSelectKeyFile(string sFileName)
Parameters
Type Name Description
string sFileName

The complete file name including path and file name extension of the key file to be selected by this method.
Returns
Type Description
FinAuthenticateResult

Release()

Declaration
public void Release()

ResetKey(FinContact, FinSecureKey)

Declaration
public void ResetKey(FinContact aContact, FinSecureKey aKey)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey

Select(string)

Declaration
public FinAuthenticateResult Select(string sSecurityMediaID)
Parameters
Type Name Description
string sSecurityMediaID
Returns
Type Description
FinAuthenticateResult

SelectKeyFile(string)

Convenience helper that attempts to detect the type of the given key file and returns a suitable IFinSecurityMedia instance for it.

Declaration
public static IFinSecurityMedia SelectKeyFile(string sFilename)
Parameters
Type Name Description
string sFilename

The name of the key file to select with a suitable IFinSecurityMedia implementation. Must not be null.
Returns
Type Description
IFinSecurityMedia

If the key file was successfully detected and also successfully selected by the IFinSecurityMedia implementation, then a reference to the selected instance is returned. If the key file was not recognized, or selection failed, then null is returned.
Exceptions
Type Condition
ArgumentNullException

The parameter sFilename was null.
ArgumentException

The parameter aFilename was an empty string.

SetCapabilities(FinSecurityMediaCaps)

Declaration
protected void SetCapabilities(FinSecurityMediaCaps nCapabilities)
Parameters
Type Name Description
FinSecurityMediaCaps nCapabilities

SetPassphraseFlags(FinSecurityMediaPassphraseFlags)

Declaration
protected void SetPassphraseFlags(FinSecurityMediaPassphraseFlags nPassphraseFlags)
Parameters
Type Name Description
FinSecurityMediaPassphraseFlags nPassphraseFlags

SetPassphraseMaxLength(int)

Declaration
protected void SetPassphraseMaxLength(int nPassphraseMaxLength)
Parameters
Type Name Description
int nPassphraseMaxLength

SetPassphraseMinLength(int)

Declaration
protected void SetPassphraseMinLength(int nPassphraseMinLength)
Parameters
Type Name Description
int nPassphraseMinLength

SignHash(FinContact, FinSecureKey, FinOperationMode, FinHash, byte[])

Declaration
public byte[] SignHash(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
FinHash nHash
byte[] vbHash
Returns
Type Description
byte[]

StoreContact(int, FinContact)

Declaration
public void StoreContact(int nContactIndex, FinContact aContact)
Parameters
Type Name Description
int nContactIndex
FinContact aContact

StoreKey(FinContact, FinSecureKey)

Declaration
public void StoreKey(FinContact aContact, FinSecureKey aKey)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
Remarks

Any existing key with the same attributes will be replaced.

Verify(FinContact, FinSecureKey, FinOperationMode, FinHash, byte[], byte[])

Declaration
public bool Verify(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash, byte[] vbSignature)
Parameters
Type Name Description
FinContact aContact
FinSecureKey aKey
FinOperationMode nOpMode
FinHash nHash
byte[] vbHash
byte[] vbSignature
Returns
Type Description
bool

Implements