Class FinSecurityMediaVoid

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

Implements a RDH security media that simply stores the secret keys in the associated FinContact instance.

public class FinSecurityMediaVoid : IFinSecurityMedia

Inheritance: object

FinSecurityMediaVoid

Implements: IFinSecurityMedia

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

In order to maintain strong security the key data is thoroughly encrypted before it is stored in the FinContact. The encryption is done based on the given passphrase. The SecurityMediaID is used to store a hash value of the passphrase for quick verification.

Constructors

FinSecurityMediaVoid(FinContact)

Special constructor only.

public FinSecurityMediaVoid(FinContact aContact)

Parameters

aContact FinContact: The FinContact where all data of this security media implementation is stored.

Remarks

Constructs an instance that uses the given FinContact to store all its data. The given FinContact instance must be the same as the one which is passed to the other methods of this class which have a FinContact parameter.

This class does not provide a default contructor and therefore cannot be created like other security media implementations. Whevever a FinContact indicates that it uses the FinSecurityMediaType.Void the FinContact will use this special constructor passing itself as the parameter

Exceptions

ArgumentNullException: The parameter aContact was null.

Properties

Capabilities

Provides the capabilities of this implementation.

public FinSecurityMediaCaps Capabilities { get; }

Property Value

FinSecurityMediaCaps

ContactCapacity

Always 1.

public int ContactCapacity { get; }

Property Value

int

MaxKeyLength

public int MaxKeyLength { get; }

Property Value

int

PassphraseFlags

Provides the attributes of the passphrase.

public FinSecurityMediaPassphraseFlags PassphraseFlags { get; }

Property Value

FinSecurityMediaPassphraseFlags

PassphraseMaxLength

Provides the maximum length that is acceptable for a passphrase for this security media implementation.

public int PassphraseMaxLength { get; }

Property Value

int

PassphraseMinLength

Provides the minimum length that is acceptable for a passphrase for this security media implementation.

public int PassphraseMinLength { get; }

Property Value

int

SecurityMediaID

The currently selected security media ID.

public string SecurityMediaID { get; }

Property Value

string: If the instance is in the Null state, then this property will be null. Otherwise the value is simply the security media ID that was given to Select(string).

SecurityMediaType

Always returns Void.

public FinSecurityMediaType SecurityMediaType { get; }

Property Value

FinSecurityMediaType

SecurityProfiles

public FinSecurityProfile[] SecurityProfiles { get; }

Property Value

FinSecurityProfile[]

State

The current state of this security media instance.

public FinSecurityMediaState State { get; }

Property Value

FinSecurityMediaState

Methods

Authenticate(string, string)

Authenticates the passphrase and switches into the Authenticated State.

public FinAuthenticateResult Authenticate(string sUserName, string sPassphrase)

Parameters

sUserName string: Is completely ignored.
sPassphrase string: The passphrase to authenticate.

Returns

FinAuthenticateResult

If the parameter sPassphrase was null, or the passphrase did not match the PassphraseMinLength or PassphraseMaxLength, then BadPassphrase is returned.

If the passphrase was wrong, then WrongPassphrase is returned. There is no limit on the number of attempts.

If the passphrase was correct, then Success is returned and the instance switches into the Authenticated State.

Exceptions

InvalidOperationException: The current State was neither Selected nor Authenticated.

AuthenticateAdmin(string, string)

Not supported.

public FinAuthenticateResult AuthenticateAdmin(string sUserName, string sAdminPassphrase)

Parameters

sUserName string
sAdminPassphrase string

Returns

FinAuthenticateResult

Exceptions

NotSupportedException: This exception is always thrown when this method is called.

AuthenticateSecure()

Not supported.

public FinAuthenticateResult AuthenticateSecure()

Returns

FinAuthenticateResult: Always returns AuthenticateSecureNotSupported.

CanAuthenticateSecure()

public bool CanAuthenticateSecure()

Returns

bool

CanChangePassphraseSecure()

public bool CanChangePassphraseSecure()

Returns

bool

Cancel()

Cancels the Authenticated state and returns into the Selected state.

public void Cancel()

Exceptions

InvalidOperationException: The current State was neither Selected nor Authenticated.

ChangePassphrase(string, string, string)

Change the passphrase and switch into the Authenticated State.

public FinAuthenticateResult ChangePassphrase(string sUserName, string sOldPassphrase, string sNewPassphrase)

Parameters

sUserName string: Is completely ignored.
sOldPassphrase string: The current passphrase is needed for a successful authentication.
sNewPassphrase string: This will become the new passphrase that is assigned to this instance.

Returns

FinAuthenticateResult

Remarks

If one of the passphrase parameters was null, or a passphrase did not match the PassphraseMinLength or PassphraseMaxLength, then BadPassphrase is returned.

Exceptions

InvalidOperationException: The current State was not Selected.

ChangePassphraseSecure()

Not supported.

public FinAuthenticateResult ChangePassphraseSecure()

Returns

FinAuthenticateResult: Always returns AuthenticateSecureNotSupported.

Create(string, string, string)

Creates an all new security media and switch directly into the Authenticated State.

public void Create(string sSecurityMediaID, string sUserName, string sPassphrase)

Parameters

sSecurityMediaID string: As the implementation of this class does not use an external key file in order to store the secret keys, this parameter is largely ignored. However, whatever string will be passed here is stored in the SecurityMediaID property.
sUserName string: Is completely ignored.
sPassphrase string: The new passphrase that shall be used to protect the secret key data which will be stored in the associated contact.

Exceptions

ArgumentNullException: The parameter sPassphrase was null.
ArgumentException: The parameter sPassphrase did not match the required PassphraseMinLength or PassphraseMaxLength.
InvalidOperationException: The current State was not Null.

CreateContact()

Not supported!

public FinContact CreateContact()

Returns

FinContact

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

public byte[] Decrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbCrypt)

Parameters

aContact FinContact: The contact for which to compute the signature. This must be the same as the FinContact instance that was passed to the constructor.
aKey FinSecureKey
nOpMode FinOperationMode
vbCrypt byte[]

Returns

byte[]

Exceptions

ArgumentNullException: One of the parameters aContact, aKey, or vbCrypt was null.
InvalidOperationException: The given aContact was not the same instance as the FinContact that was passed to the constructor; or the current State was not Authenticated.

ElevateKey(FinContact, FinSecureKey, FinSecureKeyState)

public void ElevateKey(FinContact aContact, FinSecureKey aKey, FinSecureKeyState nNewKeyState)

Parameters

aContact FinContact: The contact for which to retrieve the key. This must be the same as the FinContact instance that was passed to the constructor.
aKey FinSecureKey
nNewKeyState FinSecureKeyState

Exceptions

ArgumentNullException: The parameter aContact or aKey was null.
ArgumentException: The type of the given keys was none of the supported user key types.
InvalidOperationException: The given aContact was not the same instance as the FinContact that was passed to the constructor; or the current State was not Authenticated; or the new key state was less than the current key state of the key.

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

Not supported.

public byte[] Encrypt(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, byte[] vbData)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
vbData byte[]

Returns

byte[]: Returns always null.

EraseContact(int)

Not supported!

public void EraseContact(int nContactIndex)

Parameters

nContactIndex int

EraseKey(FinContact, FinSecureKey)

public void EraseKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact: The contact for which to retrieve the key. This must be the same as the FinContact instance that was passed to the constructor.
aKey FinSecureKey: The key to be erased.

Exceptions

ArgumentNullException: The parameter aContact or aKey was null.
ArgumentException: The key type was none of the supported user key types.
InvalidOperationException: The given aContact was not the same instance as the FinContact that was passed to the constructor; or the current State was not Authenticated.

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

Generates a new public/private key pair.

public FinSecureKey GenerateKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyLength, int nKeyNumber, int nKeyVersion)

Parameters

aContact FinContact: The contact for which to retrieve the key. This must be the same as the FinContact instance that was passed to the constructor.
nKeyType FinSecureKeyType
nKeyLength int
nKeyNumber int
nKeyVersion int

Returns

FinSecureKey

Exceptions

ArgumentNullException: The parameter aContact was null.
ArgumentOutOfRangeException: The key length, or the key number, or the key version was outside the supported range.
ArgumentException: The key type was none of the supported user key types.
InvalidOperationException: The given aContact was not the same instance as the FinContact that was passed to the constructor; or the current State was not Authenticated.

InitPassphrase(string, string)

Not supported.

public FinAuthenticateResult InitPassphrase(string sUserName, string sPassphrase)

Parameters

sUserName string
sPassphrase string

Returns

FinAuthenticateResult

Exceptions

NotSupportedException: This exception is always thrown when this method is called.

ObtainContact(int)

Not supported!

public FinContact ObtainContact(int nContactIndex)

Parameters

nContactIndex int

Returns

FinContact

ObtainKey(FinContact, FinSecureKeyType, int, int)

Find and obtain reference to crypto key from security media.

public FinSecureKey ObtainKey(FinContact aContact, FinSecureKeyType nKeyType, int nKeyNumber, int nKeyVersion)

Parameters

aContact FinContact: The contact for which to retrieve the key. This must be the same as the FinContact instance that was passed to the constructor.
nKeyType FinSecureKeyType: Must be either UserCipheringKey or UserAuthenticationKey.
nKeyNumber int: Is ignored.
nKeyVersion int: Is ignored.

Returns

FinSecureKey: Returns the requested key, or null if the key is not available, or the key type is not supported.

Exceptions

ArgumentNullException: The parameter aContact was null.
InvalidOperationException: The given aContact was not the same instance as the FinContact that was passed to the constructor; or the current State was not Authenticated.

Release()

Release security media and all its resources and return into the Null state.

public void Release()

ResetKey(FinContact, FinSecureKey)

public void ResetKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact: The contact for which to retrieve the key. This must be the same as the FinContact instance that was passed to the constructor.
aKey FinSecureKey

Exceptions

ArgumentNullException: The parameter aContact or aKey was null.
ArgumentException: The type of the given keys was none of the supported user key types.
InvalidOperationException: The given aContact was not the same instance as the FinContact that was passed to the constructor; or the current State was not Authenticated; or the new key state was less than the current key state of the key.

Select(string)

Select the security media ID and switch into the Selected State.

public FinAuthenticateResult Select(string sSecurityMediaID)

Parameters

sSecurityMediaID string: The security media ID to select.

Returns

FinAuthenticateResult: This implementation never fails and therefore always returns Success.

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

Compute user signature for given hash value.

public byte[] SignHash(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash)

Parameters

aContact FinContact: The contact for which to compute the signature. This must be the same as the FinContact instance that was passed to the constructor.
aKey FinSecureKey
nOpMode FinOperationMode
nHash FinHash
vbHash byte[]

Returns

byte[]

Exceptions

ArgumentNullException: One of the parameters aContact, aKey, or vbHash was null.
InvalidOperationException: The given aContact was not the same instance as the FinContact that was passed to the constructor; or the current State was not Authenticated.

StoreContact(int, FinContact)

Not supported!

public void StoreContact(int nContactIndex, FinContact aContact)

Parameters

nContactIndex int
aContact FinContact

StoreKey(FinContact, FinSecureKey)

Stores the given key in this security media.

public void StoreKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact: The contact for which to store the key. This must be the same as the FinContact instance that was passed to the constructor.
aKey FinSecureKey: The key to be stored. This must be one of the supported user key types.

Remarks

The implementation of this method is very special, and is different from the semantics defined for this method by the IFinSecurityMedia interface. Instead of using this method in order to store bank keys, this implementation supports storing user keys.

The very special nature of this method makes it possible to copy user keys from a key file into this security media.

Exceptions

ArgumentNullException: The parameter aContact was null.
ArgumentException: The type of the given key was not one of the supported user key types.
InvalidOperationException: The given aContact was not the same instance as the FinContact that was passed to the constructor; or the current State was not Authenticated.

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

Not supported.

public bool Verify(FinContact aContact, FinSecureKey aKey, FinOperationMode nOpMode, FinHash nHash, byte[] vbHash, byte[] vbSignature)

Parameters

aContact FinContact
aKey FinSecureKey
nOpMode FinOperationMode
nHash FinHash
vbHash byte[]
vbSignature byte[]

Returns

bool: Returns always false.