Interface IFinSecurityMedia

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

This generic interface provides access to the security media when using the RDH or RAH security procedure.

public interface IFinSecurityMedia

Remarks

For each security media type that shall be supported there must be a corresponding implementation of this interface. Currently the following implementations exist:

FinSecurityMediaRDH	Implements this interface for RDH security based on classic DDBAC RDH key files supporting the RDH-1 profile only.
FinSecurityMediaSIZ	Implements this interface for RDH security based on classic SIZ (StarMoney) key files supporting the RDH-1 profile only.
FinSecurityMediaFST	Implements this interface for RDH security based on FST (Bankverlag) key files supporting the RDH-1 profile only.
FinSecurityMediaGDM
FinSecurityMediaVRN	Implements this interface for the first generation VR-NetWorld-Cards that are based on Starcos.
FinSecurityMediaZKA	Implements this interface for the SECCOS based ZKA smart cards such as the second generation VR-NetWorld-Cards.
FinSecurityMediaVoid	Implements this interface for RDH security storing the encrypted secret key data in a FinContact instance that must be passed to a special constructor.
FinSecurityMediaALF	Implements this interface for RDH security based on key files generated by the ALF BanCo software. The implementation supports the old style ALF RDH-1 key files and the new RDH-2 and RDH-10 key files.
FinSecurityMediaRDH2	Implements this interface for RDH security based on key files according to the PPI RDH-2 and RDH-10 key file specifications. This implementation supports RDH-1, RDH-2, and RDH-10 with both (old and new) key file formats.

Properties

Capabilities

Provides information about the capabilities of the security media implementation.

FinSecurityMediaCaps Capabilities { get; }

Property Value

FinSecurityMediaCaps

Remarks

This property can always be queried, regardless of whether the security media is currently authenticated. Usually an implementation only returns a constant value through this property.

ContactCapacity

Provides the number of contact records that can be stored on the security media.

int ContactCapacity { get; }

Property Value

int: The value zero is returned when the security media cannot store any contact information at all. In this case the methods ObtainContact(int), StoreContact(int, FinContact), and EraseContact(int) must not be called.

Remarks

Although this property can always be queried, the real contact capacity may only become available after the security media is authenticated.

MaxKeyLength

The maximum RSA key length supported by the security media.

int MaxKeyLength { get; }

Property Value

int: For RDH based security this provides the max RSA key length in bytes that can be handled by the security media. For RDH-1 only security medias this value is always 96 (768 bits).

PassphraseFlags

Provides information about the security media passphrase (or PIN, or password).

FinSecurityMediaPassphraseFlags PassphraseFlags { get; }

Property Value

FinSecurityMediaPassphraseFlags

PassphraseMaxLength

Provides the maximum length of the security media passphrase (or PIN, or password).

int PassphraseMaxLength { get; }

Property Value

int: The returned value must not be greater than 256 and must be greater or equal than PassphraseMinLength.

PassphraseMinLength

Provides the minimum length of the security media passphrase (or PIN, or password).

int PassphraseMinLength { get; }

Property Value

int: The returned value must not be negative and must be less or equal than PassphraseMaxLength.

SecurityMediaID

Provides the currently selected security media ID.

string SecurityMediaID { get; }

Property Value

string

If this security media is not in the Selected or Authenticated state, then the returned vaue will be null.

Smart card based implementations shall returned their unique smart card identification (CID). Key file based implementations shall return the fully qualified file name of the key file.

SecurityMediaType

Indicates the type of security media that is managed by this IFinSecurityMedia implementation.

FinSecurityMediaType SecurityMediaType { get; }

Property Value

FinSecurityMediaType

Remarks

This property can always be queried, regardless of whether the security media is currently authenticated. Usually an implementation only returns a constant value through this property.

SecurityProfiles

Provides an array with all the security profiles that are supported by this IFinSecurityMedia implementation.

FinSecurityProfile[] SecurityProfiles { get; }

Property Value

FinSecurityProfile[]: The returned array must always contain at least one element. And, of course, must never be null.

Remarks

This property can always be queried, regardless of whether the security media is currently authenticated. Usually an implementation only returns a constant array through this property.

State

Indicates the current state of this security media instance.

FinSecurityMediaState State { get; }

Property Value

FinSecurityMediaState

Methods

Authenticate(string, string)

Authenticate user against previously selected security media.

FinAuthenticateResult Authenticate(string sUserName, string sPassphrase)

Parameters

sUserName string: Optional user name which may be required to access certain types of security media. If not needed, then null may be passed here. The flag UserNameRequired indicates whether an user name will be required.
sPassphrase string: Passphrase (or PIN, or password) required to gain access to the security media.

Returns

FinAuthenticateResult: Returns the result of the authentication. In addition to returning a result, an exception may be thrown.

Remarks

Before a security media can be authenticated it must be in the Selected state.

Exceptions

ArgumentNullException: The parameter sPassphrase was null.
InvalidOperationException: This IFinSecurityMedia instance is not in the Selected State.

AuthenticateAdmin(string, string)

Authenticate admin user against security media.

FinAuthenticateResult AuthenticateAdmin(string sUserName, string sAdminPassphrase)

Parameters

sUserName string
sAdminPassphrase string

Returns

FinAuthenticateResult

AuthenticateSecure()

Attempt a class 2 card reader secure authentication.

FinAuthenticateResult AuthenticateSecure()

Returns

FinAuthenticateResult: If the security media implementation, or the card reader does not support secure PIN entry, then the special FinAuthenticateResult value AuthenticateSecureNotSupported is returned. If secure PIN entry is supported, then it is attempted and its real authentication result is returned.

CanAuthenticateSecure()

Indicates whether AuthenticateSecure() may be called.

bool CanAuthenticateSecure()

Returns

bool

Remarks

This security media must be at least in the Selected State when this method is called. Only if this returns true, then a secure authentication will be tried.

CanChangePassphraseSecure()

Indicates whether ChangePassphraseSecure() may be called.

bool CanChangePassphraseSecure()

Returns

bool

Remarks

This security media must be at least in the Selected State when this method is called. Only if this returns true, then a secure PIN change will be tried.

Cancel()

Cancels the Authenticated state and returns into the Selected state.

void Cancel()

Remarks

This method may only be called in the Authenticated or Selected state. In the latter case this method simply does nothing.

Exceptions

InvalidOperationException: This IFinSecurityMedia instance is not in any of the allowed states.

ChangePassphrase(string, string, string)

Change the passphrase (or PIN, or password) that is required to authenticate the security media.

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

Parameters

sUserName string: Optional user name which may be required to access certain types of security media. If not needed, then null may be passed here. The flag UserNameRequired indicates whether an user name will be required.
sOldPassphrase string: The current passphrase (or PIN, or password) required to gain access to the security media.
sNewPassphrase string: The new passphrase (or PIN, or password) that shall be used to protect the security media.

Returns

FinAuthenticateResult: Returns the result of authentication with the old passphrase. In addition to returning a result, an exception may be thrown.

Remarks

The passphrase can only be changed if this IFinSecurityMedia is in the Selected State.

Exceptions

ArgumentNullException: The parameter sOldPassphrase or sNewPassphrase was null.
NotSupportedException: The security media has a fixed passphrase.
InvalidOperationException: This IFinSecurityMedia instance is not in the Selected State.

ChangePassphraseSecure()

Attempt a class 2 card reader secure PIN modification.

FinAuthenticateResult ChangePassphraseSecure()

Returns

FinAuthenticateResult: If the security media implementation, or the card reader does not support secure PIN modification, then the special FinAuthenticateResult value AuthenticateSecureNotSupported is returned. If secure PIN modification is supported, then it is attempted and its real authentication result is returned.

Create(string, string, string)

Creates an all new security media.

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

Parameters

sSecurityMediaID string: The complete filename of the key file to be created as the new security media. Must not be null and must not be an empty string.
sUserName string: Optional user name which may be required to create certain types of security media. If not needed, then null may be passed here. The flag UserNameRequired indicates whether an user name will be required.
sPassphrase string: Passphrase to use for encrypting the new security media. Must not be null.

Remarks

This method must only be called in the Null state. If it completes without exception, then the security media object has changed into the Authenticated state.

Also, this method does only apply to KeyFile based security medias. Calling this method on any other type of security media will immediately raise an exception.

The new key file will be initially empty and does not contain any stored contacts or keys. The methods StoreContact(int, FinContact) and the key management related methods must be used in order to completely set up the key file.

Exceptions

ArgumentNullException: Either of the parameters was null.
ArgumentException: The given security media ID was an empty string or an otherwise unacceptable file name.
NotSupportedException: The security media is not a KeyFile and thus cannot be created.
InvalidOperationException: This IFinSecurityMedia instance is not in the Null State.

CreateContact()

Creates a default contact record to be used with this security media implementation.

FinContact CreateContact()

Returns

FinContact

Remarks

The returned FinContact instance must be initialised with all applicable default values required by this security media. At a minimum the fields SecurityMediaType, SecurityMediaID, SecurityProcCode, and CustSysStat must be initialised.

Exceptions

InvalidOperationException: This IFinSecurityMedia instance is not in the Authenticated State.

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

Decrypt the given cryptogam.

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

Parameters

aContact FinContact
aKey FinSecureKey: FinSecureKey instance to be used for decrypting the data. The key must have been obtained through ObtainKey(FinContact, FinSecureKeyType, int, int), or GenerateKey(FinContact, FinSecureKeyType, int, int, int), or have been previously stored through StoreKey(FinContact, FinSecureKey).
nOpMode FinOperationMode: The cryptographic operation mode that shall be applied.
vbCrypt byte[]

Returns

byte[]

Remarks

This method must always be implemented. If the private exponent is included in the FinSecureKey returned by ObtainKey(FinContact, FinSecureKeyType, int, int), then this method may simply delegate to Decrypt(FinOperationMode, byte[]).

ElevateKey(FinContact, FinSecureKey, FinSecureKeyState)

Elevates the state of the indicated key.

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

Parameters

aContact FinContact
aKey FinSecureKey: The key which's state to elevate. The parameter must not be null and must refer to a user or a bank key. The key reference must have been obtained through ObtainKey(FinContact, FinSecureKeyType, int, int), GenerateKey(FinContact, FinSecureKeyType, int, int, int), or StoreKey(FinContact, FinSecureKey).
nNewKeyState FinSecureKeyState: The new, elevated state for the given key. This must be either Passive or Active.

Remarks

If the given key is already in the requested elevated state, then this method does nothing.

Exceptions

NotSupportedException: The security media does not support changing the key state.
ArgumentNullException: The key parameter was null.
ArgumentException: The given key is one of the temporary keys; or the given key reference is otherwise invalid; or the given new key state is neither Passive nor Active.
InvalidOperationException: This IFinSecurityMedia instance is not in the Authenticated State; or the given key is in the Null state; or the given key is in the Active state and the requested new key state is Passive.

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

Encrypt the given data.

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

Parameters

aContact FinContact
aKey FinSecureKey: FinSecureKey instance to be used for encrypting the data. The key must have been obtained through ObtainKey(FinContact, FinSecureKeyType, int, int), or GenerateKey(FinContact, FinSecureKeyType, int, int, int), or have been previously stored through StoreKey(FinContact, FinSecureKey).
nOpMode FinOperationMode: The cryptographic operation mode that shall be applied.
vbData byte[]: Data to be encrypted. This should be the 3DES key that was used to encrypt the message.

Returns

byte[]: Cryptogram.

Remarks

This method must always be implemented but can be easily delegated to the Encrypt(FinOperationMode, byte[]) method of the FinSecureKey most of the time.

EraseContact(int)

Completely erases the contact data stored at the given index.

void EraseContact(int nContactIndex)

Parameters

nContactIndex int: Contact index position at which to erase the contact information. This parameter must be within the range from zero through ContactCapacity minus one.

Remarks

The stored contact data record is completely erased. In addition, any bank keys that are attached to the given contact index are completely erased, too. Also, the status of the user keys associated with the contact index is reset to the FinSecureKeyState New.

Exceptions

NotSupportedException: The security media does not support storing and thus erasing of contact data.
ArgumentOutOfRangeException: The contact index was outside the allowed range.
InvalidOperationException: This IFinSecurityMedia instance is not in the Authenticated State.

EraseKey(FinContact, FinSecureKey)

Completely erases the indicated key from the security media.

void EraseKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact
aKey FinSecureKey: The key which shall be erased from the security media. This must not be null. The key reference must have been obtained through ObtainKey(FinContact, FinSecureKeyType, int, int), GenerateKey(FinContact, FinSecureKeyType, int, int, int), or StoreKey(FinContact, FinSecureKey).

Exceptions

NotSupportedException: The security media does not support erasing keys, e.g. a smart card with preinstalled keys with certificate.
ArgumentNullException: The key parameter was null.
ArgumentException: The given key reference is invalid.
InvalidOperationException: This IFinSecurityMedia instance is not in the Authenticated State.

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

Generates a new public/private key pair.

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

Parameters

aContact FinContact: Provides the information about the contact to create a new key pair for. The implementation uses this information in order to associate and store the complete key name that identifies the key. This parameter must not be null.
nKeyType FinSecureKeyType: Type of key to create. Must be one of UserCipheringKey, or UserAuthenticationKey.
nKeyLength int: The desired nominal key length in bytes. For the classic RDH-1 security procedure the nominal key length can be in the range from 89 through 96, where 96 is the recommended value. Later RDH versions use longer keys. This parameter must be in the range from 32 through 512. A particular implementation may have much narrower constraints.
nKeyNumber int: The KeyNumber that shall be assigned to the new key. This must be in the range from 0 through 998.
nKeyVersion int: The KeyVersion that shall be assigned to the new key. This must be in the range from 0 through 998.

Returns

FinSecureKey: Returns the key that was created. As this key was just created it always starts out in the Passive state and must be utlimately activated.

Remarks

User keys shall only be generated if the security media does not already contain suitable keys. An application should always just use the existing keys, if possible.

When changing the user keys, two new key pairs should be created as temporary keys and only be activated after they have been acknowledged by the bank.

Exceptions

ArgumentNullException: The contact parameter was null.
ArgumentException: The given key type was neither of the allowed key types.
ArgumentOutOfRangeException: The parameter nKeyNumber or the parameter nKeyVersion was outside the allowed range, or the requested nKeyLength is outside the defined range.
NotSupportedException: The security media does not support generating keys, e.g. a smart card with preinstalled keys with certificate, or the security media does not support the requested key length.
InvalidOperationException: This IFinSecurityMedia instance is not in the Authenticated State.

InitPassphrase(string, string)

Initialises the passphrase on a virgin security media.

FinAuthenticateResult InitPassphrase(string sUserName, string sPassphrase)

Parameters

sUserName string: Optional user name which may be required to access certain types of security media. If not needed, then null may be passed here. The flag UserNameRequired indicates whether an user name will be required.
sPassphrase string: Passphrase (or PIN, or password) that shall be used to protect the security media.

Returns

FinAuthenticateResult

Remarks

This method may only be invoked if a previous attempt to call Authenticate(string, string) returned NoPassphrase.

Exceptions

ArgumentNullException: The parameter sPassphrase was null.
InvalidOperationException: This IFinSecurityMedia instance is not in the Selected State.
NotSupportedException: The passphrase is provided by the security media manufacturer and cannot be initialised by the user.

ObtainContact(int)

Reads the selected contact record and returns it in a new FinContact instance.

FinContact ObtainContact(int nContactIndex)

Parameters

nContactIndex int: If the security media supports storing multiple contacts, then this parameter selects the storage index where the contact was stored. The parameter must be in the range from zero through ContactCapacity minus one.

Returns

FinContact

Exceptions

ArgumentOutOfRangeException: The contact index was outside the allowed range.
InvalidOperationException: This IFinSecurityMedia instance is not in the Authenticated State.

ObtainKey(FinContact, FinSecureKeyType, int, int)

Find and obtain reference to crypto key from security media.

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

Parameters

aContact FinContact: The contact for which to obtain the key. This must have been obtained from an earlier call to ObtainContact(int) or, if created from scratch, must have been previously stored through StoreContact(int, FinContact).
nKeyType FinSecureKeyType: The type of key to be obtained.
nKeyNumber int: The key number of the key to be obtained. Use 999 in order to obtain the key of the given key type with the highest key state.
nKeyVersion int: The key version of the key to be obtained. Use 999 in order to obtain the key of the given key type with the highest key state.

Returns

FinSecureKey

If the key was found it is returned. If the requested key does not exist on the security media, then null is returned.

If the security media is responsible for maintaining the SignatureID, then the SignatureID property of the returned FinSecureKey must be initialized.

Exceptions

ArgumentNullException: The parameter aContact was null.

Release()

Release security media and all its resources.

void Release()

Remarks

This method may be called in any state in order to return the IFinSecurityMedia instance to the Null state.

ResetKey(FinContact, FinSecureKey)

Returns the state of the indicated key to its base state without erasing it.

void ResetKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact
aKey FinSecureKey: The key to reset. The parameter must not be null. This can be any key type supported by the security media. The key reference must have been obtained through ObtainKey(FinContact, FinSecureKeyType, int, int), GenerateKey(FinContact, FinSecureKeyType, int, int, int), or StoreKey(FinContact, FinSecureKey).

Remarks

The base state for user and temporary keys is the New state. The base state for bank keys is the Passive state. If the indicated key is already in its base state, then this method does nothing.

Exceptions

NotSupportedException: The security media does not support changing the key state.
ArgumentNullException: The parameter aKey was null.
ArgumentException: The given key reference is invalid.
InvalidOperationException: This IFinSecurityMedia instance is not in the Authenticated State; or the given key is in the Null KeyState.

Select(string)

Selects a security media for subsequent access.

FinAuthenticateResult Select(string sSecurityMediaID)

Parameters

sSecurityMediaID string

Identification of the physical security media. For smart card based security this is the unique smart card serial number (ICCSN or similar). For file based security this is the filename including the complete path.

This parameter must not be null.

Returns

FinAuthenticateResult: A FinAuthenticateResult value that indicates whether the identified security media is available and is a valid security media as needed by this IFinSecurityMedia implementation.

Remarks

Although a FinAuthenticateResult is returned not all values of that enumeration are valid results. The return value Success indicates that the identified security media is available and is a valid security media as needed by this IFinSecurityMedia implementation.

Other allowed results are: NoSecurityMedia, WrongSecurityMedia

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

Signs the hash value using the given key.

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

Parameters

aContact FinContact
aKey FinSecureKey: FinSecureKey instance to be used for signing the hash value. The key must have been obtained through ObtainKey(FinContact, FinSecureKeyType, int, int), or GenerateKey(FinContact, FinSecureKeyType, int, int, int), or have been previously stored through StoreKey(FinContact, FinSecureKey).
nOpMode FinOperationMode: The cryptographic operation mode that shall be applied.
nHash FinHash: Identifies the hash algorithm that was used to produce the hash value. This is neeed for properly formatting the hash value for the signature operation.
vbHash byte[]: Hash to be signed. Must not be null.

Returns

byte[]: Returns the signature value.

Remarks

If the security media is responsible for maintaining the SignatureID, then the SignatureID property of the given FinSecureKey must be updated.

StoreContact(int, FinContact)

Stores or updates the contact data record on the security media.

void StoreContact(int nContactIndex, FinContact aContact)

Parameters

nContactIndex int: Contact index position at which to store the contact information. This parameter must be within the range from zero through ContactCapacity minus one.
aContact FinContact: Provides the contact details to be stored. The amount of contact data actually stored on/in the security media depends on the type of security media and the implementation. In the worst case nothing will be stored and this method returns without doing anything. This parameter must not be null.

Exceptions

NotSupportedException: The security media does not support storing of contact data.
ArgumentNullException: The aContact parameter was null.
ArgumentOutOfRangeException: The contact index was outside the allowed range.
InvalidOperationException: This IFinSecurityMedia instance is not in the Authenticated State.

StoreKey(FinContact, FinSecureKey)

Stores or updates the public bank key on the security media.

void StoreKey(FinContact aContact, FinSecureKey aKey)

Parameters

aContact FinContact: The contact for which to store the key. This must have been obtained from an earlier call to ObtainContact(int) or, if created from scratch, must have been previously stored through StoreContact(int, FinContact).
aKey FinSecureKey: Provides the bank key data to be stored or updated. Must not be null. This key must be of type BankCipheringKey, or BankAuthenticationKey.

Remarks

On the security media the key to be updated is solely identified by the CountryCode, the BankCode, and the KeyType. For each combination of these attributes only one key can exist and will be updated if present.

Exceptions

ArgumentNullException: The parameter aContact or the parameter aKey was null.
ArgumentException: The given key type was neither of the allowed key types.
InvalidOperationException: This IFinSecurityMedia instance is not in the Authenticated State.
NotSupportedException: The security media does not support storing public keys.

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

Verify the hash value against the given signature using the given key.

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

Parameters

aContact FinContact
aKey FinSecureKey: FinSecureKey instance to be used for verifying the hash value. The key must have been obtained through ObtainKey(FinContact, FinSecureKeyType, int, int), or GenerateKey(FinContact, FinSecureKeyType, int, int, int), or have been previously stored through StoreKey(FinContact, FinSecureKey).
nOpMode FinOperationMode: The cryptographic operation mode that shall be applied.
nHash FinHash: Identifies the hash algorithm that was used to produce the hash value. This is neeed for properly formatting the hash value for the verify operation.
vbHash byte[]: Hash to be verified. Must not be null.
vbSignature byte[]: Signature to be verified. Must not be null.

Returns

bool: If the signature is valid, then true is returned. If the signature is invalid, then false is returned.

Remarks

This method must always be implemented but can be easily delegated to the Verify(FinOperationMode, FinHash, byte[], byte[]) method of the FinSecureKey most of the time.