Class FinContact

Namespace: Subsembly.FinTS

Assembly: Subsembly.FinTS.Core.dll

Stores communication parameters, synchronisation status, bank and user parameter data, and further configuration information of a particular FinTS homebanking contact.

public sealed class FinContact : FinPersist

Inheritance: object

FinPersist

FinContact

Inherited Members: FinPersist.RootTag

FinPersist.SaveAs(string)

FinPersist.Load(string)

FinPersist.Write(Stream)

FinPersist.Read(Stream)

FinPersist.SaveXml()

FinPersist.SaveXml(string)

FinPersist.LoadXml(string)

FinPersist.ToXml(string)

FinPersist.WriteXmlDocument(XmlWriter)

FinPersist.WriteXmlDocument(XmlWriter, string)

FinPersist.ReadXmlDocument(XmlReader)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

Remarks

All information that is needed in order to set up, use and maintain FinTS homebanking for a particular user at a particular bank is consolidated in a FinContact instance. Any FinTS homebanking dialog is conducted within the context of a FinContact instance.

In order to preserve all the information of a FinContact, its entire state can be saved and loaded using an XML format. This is not done automatically, however, but must be triggered by the client application.

In the course of a FinTS homebanking dialog some properties of the FinContact, such as the signature counter, are continuously updated. All such updates to the FinContact should be immediately saved to some persistent backing store. Otherwise the FinTS user state information may get of of sync with the FinTS server. If a FinContact got out of sync, then any subsequent attempt to conduct a FinTS homebanking dialog with it will fail. In order to recover from this situation, the FinContact must be re-synchronised.

As a special case a FinContact can also be used to hold the information for anonymous access to a particular bank. In that case, the user ID will be null. The context information for an anonymous FinContact usually is just temporary and there is no need to save that state, once the anonymous FinTS homebanking dialog has ended.

In order to make any FinTS homebanking connection with the FinTS Subsembly, the first step is to obtain a sufficiently initialised FinContact instance. This can be done by creating a new FinContact instance from scratch and initialise its properties, or by loading the contact information from an XML string using the LoadXml(string), or Load(string) methods.

In order to persist the synchronisation status, and thus avoid having to resynchronise the contact every time the FinContact is recreated from scratch, the complete contact information should be saved in a ContactFolder.

The XML format generated when saving the contact consists of a single <FinContact> root node with the following elements:

XML Element	Description
ContactName	Purely optional human readable name that tags this contact. If absent, then the contact won't have a name but can be used anyway.
CountryCode	ISO 3166 numeric country code that identifies the country where the bank resides. This corresponds to the CountryCode property.
BankCode	Bank code that identifies the bank within the country given by the country code. This corresponds to the BankCode property.
UserID	Optional FinTS user identification. If absent, then this is a contact that uses anonymous access to the identified bank. This corresponds to the UserID property.
FinTSVersion	The FinTS version configured for this contact. Each FinTS homebanking dialog created from this contact will be conducted using this FinTS version. If this is zero, then the FinDialog uses the FinTS version "300" as the default version.
CustSysStat	FinTS customer system status. If absent, then the default value 1 is assumed. This corresponds to the CustSysStat property.
CustSysID	Optional FinTS customer system ID. This corresponds to the CustSysID property.
SignatureID	Next signature counter value to be used. If absent, then the counter will be restarted with the value one. This corresponds to the SignatureID property.
DefaultLanguage	The default FinTS language that will be adopted by any new FinDialog created from this contact. If absent, then the FinDialog uses the default language Default. This is stored as a numeric value in the range from 0 through 3.
DefaultCustID	The default customer ID that will be used if no explicit customer ID is given to the InitDialog(FinDialogType, string, string, string) method of the FinDialog class. If this is absent, then the InitDialog(FinDialogType, string, string, string) method will use the UserID as the default customer ID.
DefaultResponseTimeout	Default timeout to be applied to all online message transmissions by the FinDialog class.
CommService	The communications service ID. Currently the following values are defined by FinTS: 1 - BTX FiF Transport 2 - Raw TCP connection to Port 3000 3 - HTTP or HTTPS connection to a given URL Currently only the CommService types 2 (TCP) and 3 (HTTP/HTTPS) are supported by the FinTS Subsembly. If no CommService contact attribute is set, then the default value "3" is implicitly assumed.
CommAddress	The communication address to connect to. For HTTPS transmission this must be the complete case sensitive URL including the https:// prefix. For other transport protocols this is another transport specific address.
FilterFunction	Optional filter function to be applied to the transmitted data stream. Currently the following values are defined by FinTS: MIM - MIME Base 64 encoding UUE - UUencode/UUdecode The only filter function supperted by the FinTS Subsembly is MIME base 64 encoding, which is required for all HTTP/HTTPS communication based dialogs. Thus, if this attribute is not given, then "MIM" will be the default setting.
FilterFunctionVersion	FinTS only defines the value 1 for this attribute, hence it is ignored, for now.
SecurityProcCode	The security procedure code of the security procedure that is employed by this contact.
SecurityProcVersion	Additionally qualifies the security procedure code. The default value is "1" if not set.
SecurityMediaType	Type of security media. `0` - No security media or external security media, such as a TAN list. This is the default value. `1` - The security media is a key file. `2` - the security media is a smart card.
SecurityMediaID	Additional identification of the security media. The meaning of this property depends on the security media class implementation.
BankParamData	The complete sequence of bank parameter data (BPD) segments inside a single base 64 encoded BLOB.
UserParamData	The complete sequence of user parameter data (UPD) segments as a single base 64 encoded BLOB.
BankKeyHash	Optional the base 64 encoded fingerprint value of the bank keys. Provided through the property BankKeyFingerprint.
BankKeyHashAlg	Optional the hash algorithm used for computing the BankKeyHash. "999" is RIPEMD-160 and "3" ist SHA-256. See FingerprintHashAlgorithm.
TanMediaName	Optional a TAN media name chosen by the user. If this is set, then the given TAN medium will be used.
StrongCustomerAuthentication	An optional integer value that selects the FinContactSCA choice. See enumeration for a description of values.

Constructors

FinContact()

Creates an all new FinContact with default values.

public FinContact()

Remarks

Use this constructor to create an all new FinContact instance from scratch. This constructor generates an all new ContactGuid in order to distinguish the new contact from any other contact that may have previously existed.

The created FinContact instance has no associated ContactFolder and therefore is not persistent. In order to save the contact data, add the initialised FinContact instance to a suitable IFinContactFolder implementation.

FinContact(IFinSecurityMedia)

Creates an all new FinContact instance from a security media.

public FinContact(IFinSecurityMedia aSecurityMedia)

Parameters

aSecurityMedia IFinSecurityMedia: The security media to initialise the new FinContact instance from. If null, a new FinSecurityMediaVoid instance will be created and associated with the contact.

Remarks

Use this constructor to create an all new FinContact instance from a security media. The constructor generates an all new ContactGuid and the given security media will be attached to this contact's SecurityMedia property.

This constructor does not set the security profile if the given security media supports more than one profile.

FinContact(string, int, string, string, string)

DEPRECATED: Creates an all new FinContact for PIN/TAN security.

[Obsolete]
public FinContact(string sCommAddress, int nFinTSVersion, string sTanProcedure, string sBankCode, string sUserID)

Parameters

sCommAddress string: Complete Internet URL of the FinTS system including the https: prefix. For example "https://hbci11.fiducia.de/cgi-bin/hbciservlet". The correct address can be obtained from your bank.
nFinTSVersion int: Version of the FinTS protocol to use. The FinTS PIN/TAN security procedure is currently defined for HBCI 2.2 and FinTS 3.0. This means this parameter should have the value 220 or 300.
sTanProcedure string: The TAN procedure to be used. For the classic PIN/TAN procedure this parameter shall be null. For iTAN security procedures this parameter must be set to the bank-specific technical identification of the requested procedure.
sBankCode string: The bank code (eight digits) of the new contact.
sUserID string: The user ID of the new contact. Depending on the bank this may also be an account number or something different, like, for example, the VR-NetKey.

Exceptions

ArgumentNullException: At least one of the parameters sCommAddress, sBankCode, or sUserID was null.
ArgumentOutOfRangeException: The given FinTS version was outside the range 0 through 999.
ArgumentException: One of the parameters was otherwise invalid.

FinContact(string, string, string)

Creates an all new FinContact for PIN/TAN security.

public FinContact(string sCommAddress, string sBankCode, string sUserID)

Parameters

sCommAddress string: Complete Internet URL of the FinTS system including the https: prefix. For example "https://hbci11.fiducia.de/cgi-bin/hbciservlet". The correct address can be obtained from your bank.
sBankCode string: The bank code (eight digits) of the new contact.
sUserID string: The user ID of the new contact. Depending on the bank this may also be an account number or something different, like, for example, the VR-NetKey.

Exceptions

ArgumentNullException: At least one of the parameters sCommAddress, sBankCode, or sUserID was null.
ArgumentException: One of the parameters was otherwise invalid.

Fields

DEFAULTFINTSVERSION

The default FinTS version. Current this value is 300 in order to indicate FinTS 3.0.

public const int DEFAULTFINTSVERSION = 300

Field Value

int

MAXSIGNATUREID

The maximum value for the SignatureID is 9999999999999999 (16 digits).

public const long MAXSIGNATUREID = 9999999999999999

Field Value

long

Properties

AllowedSecurityFunctions

The list of allowed security functions (TAN processes) as reported by the bank.

public string[] AllowedSecurityFunctions { get; set; }

Property Value

string[]: If no list of security function codes has been received so far, then this property is null. Otherwise the returned array contains the security function codes just as they were returned by the bank. Usually these should be integer strings with values in the range from "900" through "997".

Remarks

On each dialog initialisation the bank responds with a list of TAN procedures that are enabled for the customer. The list consists of the security function codes of the allowed TAN procedures. These are conveyed in a HIRMS status element with status code 3920.

The FinDialog class uses this property in order to persistently store this information.

The helper method GetAllowedTanProcs(FinContact) uses this property in order to create a list of allowed TAN procedures.

BPD

The current or most recent bank parameter data (BPD) that have been collected for this contact.

public FinBankParamData BPD { get; set; }

Property Value

FinBankParamData: If no BPD are available for this contact, yet, then this value will be null.

BPDVersion

The version number of the collected BPD.

public int BPDVersion { get; }

Property Value

int: If no BPD have been collected, then this property will be zero.

BankCode

Bank code that identifies the bank within the country given by the CountryCode.

public string BankCode { get; set; }

Property Value

string

A bank code can be any non-empty string with up to 30 characters. It is not limited to numeric German bank sort codes.

The actual interpretation and thus constraining of the bank code depends on the selected CountryCode. If the country code indicates germany (280), then the bank code must hold the eight digit bank sort code (Bankleitzahl). For other countries the value of the bank code may be different.

In some countries, the bank is usually solely identified through the account number which already includes some bank identification code. If this is the case, then this property still must be initialised with some unique bank identification. This can be either the SWIFT code (BIC) of the bank or the bank code part of the account number.

The default value of this property is null and therefore must be changed before this contact can be used for anything.

Remarks

Changing the bank code of a FinContact instance changes its logical primary key. Therefore all subordinate dynamic properties are erased. This means that the FinContact must be (re-)synchronised.

Exceptions

ArgumentOutOfRangeException: An attempt to set the bank code to a zero length string or a string longer than 30 characters will cause an ArgumentOutOfRangeException to be thrown.

BankKeyFingerprint

The stored bank key fingerprint.

public byte[] BankKeyFingerprint { get; set; }

Property Value

byte[]

Remarks

This value IS NOT computed from the bank keys. It is just stored for reference and comparison during the initialization phase of the contact.

CommAddress

Convenient shortcut for accessing the CommAddress attribute.

public string CommAddress { get; }

Property Value

string

See Also: SetCommService(FinCommService, string)

CommService

CommService

Convenient shortcut for accessing the CommService attribute.

public FinCommService CommService { get; }

Property Value

FinCommService

See Also: SetCommService(FinCommService, string)

CommAddress

ContactFolder

Optional reference to IFinContactFolder instance that hosts this contact.

public IFinContactFolder ContactFolder { get; set; }

Property Value

IFinContactFolder

Remarks

If this reference is set, then any changes made to this FinContact instance will trigger a call to the Update(FinContact) method of the IFinContactFolder interface.

ContactGuid

A GUID that uniquely identifies this contact.

public Guid ContactGuid { get; }

Property Value

Guid

Remarks

This property is managed automatically by the FinContact class and therefore can only be read. A newly created FinContact will always get a newly create GUID. If a FinContact instance is stored, its GUID is stored with it, and also restored when loaded.

ContactName

Optional human readable contact name.

public string ContactName { get; set; }

Property Value

string: The contact name may be a nonempty string of up to 256 characters. The default value of this property is a generic localized default name.

Exceptions

ArgumentException: An attempt was made to set an empty contact name string.

CountryCode

ISO 3166 numeric country code that identifies the country where the bank resides.

public string CountryCode { get; set; }

Property Value

string

The country code is a required property that consists of a string of exactly three digits. Although it contains only digits it is represented as a string, because any leading zeroes are significant and must not get lost.

The country code for Germany is always "280" which is also the default value. Usually there is no need to set anything different.

Remarks

Changing the country code of a FinContact instance changes its logical primary key. Therefore all subordinate dynamic properties are erased. This means that the FinContact must be (re-)synchronised.

Exceptions

ArgumentOutOfRangeException: An attempt to set the country code to a string that does not contain three digits will cause an ArgumentOutOfRangeException to be thrown.

CustSys

Optionally a global IFinCustomerSystem can be provided through this property.

public static IFinCustomerSystem CustSys { get; set; }

Property Value

IFinCustomerSystem

Remarks

If a global IFinCustomerSystem is provided, it will be used to store the CustSysID for all contacts. If none is provided, then the CustSysID will be stored solely in the FinContact itself.

CustSysID

Optional FinTS customer system ID.

public string CustSysID { get; set; }

Property Value

string: The customer system ID may be null or a nonempty string of up to 30 characters.

Exceptions

ArgumentOutOfRangeException: An attempt to set the customer system ID to a zero length string or a string longer than 30 characters will cause an ArgumentOutOfRangeException to be thrown.

CustSysStat

FinTS customer system status.

public int CustSysStat { get; set; }

Property Value

int

The FinTS customer system status can only have the values zero or one. The value zero indicates that a customer system ID is not required for the customer system. The value one indicates that a customer system ID is required.

When a FinContact is created from scratch, this property is initialised with the default value one.

Exceptions

ArgumentOutOfRangeException: An attempt to set any other value than zero or one will cause an ArgumentOutOfRangeException to be thrown.

DefaultCustID

public string DefaultCustID { get; set; }

Property Value

string

EnableSecurePinEntry

Enable or disable secure PIN entry at the smart card reader.

public bool EnableSecurePinEntry { get; set; }

Property Value

bool

Remarks

This flag can be used to explicitly disable the secure PIN entry for this contact. By default this attribute is true.

FilterFunction

The filter function as defined by HBCI.

public string FilterFunction { get; }

Property Value

string

See Also: SetFilterFunction(string)

FilterFunctionVersion

The filter function version as defined by HBCI.

public int FilterFunctionVersion { get; }

Property Value

int

See Also: SetFilterFunction(string)

FinTSVersion

The FinTS version for which this contact is configured.

public int FinTSVersion { get; set; }

Property Value

int

The FinTS version is a required property of any contact and therefore should be explicitly set to a nonzero value in the range from 201 through 999.

The FinTS version is specified as a number in the range from 201 through 999 according to the FinTS specification. The value 201 represents HBCI 2.0.1, 210 is HBCI 2.1, 220 is HBCI 2.2, and 300 is FinTS 3.0

By default this value is 300 which indicates FinTS 3.0.

Remarks

Changing the FinTS version of a FinContact instance will delete all dynamic properties. This means that the FinContact must be (re-)synchronised.

Exceptions

ArgumentOutOfRangeException: An attempt was made to set a value outside the allowed range from 0 through 999.

FingerprintHashAlgorithm

The hash algorithm to be used to compute key fingerprints.

public FinHash FingerprintHashAlgorithm { get; set; }

Property Value

FinHash

Remarks

This value shall only be set by security medias that have a special need (read: only by the SECCOS 6 implementation).

HaveFinTSVersion

Indicates whether the FinTSVersion has been explicitly set to a non-zero version number.

public bool HaveFinTSVersion { get; }

Property Value

bool

Remarks

If the FinTSVersion has not been set, or has been explicitly set to zero, then the FinTSVersion property will return the DEFAULTFINTSVERSION. In order to be able to differentiate whether the default version has been returned, or whether the same version has been explicitly set, this property has been added.

HaveSecurityFunction

Indicates whether the property SecurityFunction has been explicitly set to a non-zero value.

public bool HaveSecurityFunction { get; }

Property Value

bool

HaveSecurityProcCode

Indicates whether the SecurityProcCode has been explicitly set to a non-null string.

public bool HaveSecurityProcCode { get; }

Property Value

bool

HaveSecurityProcVersion

Indicates whether the SecurityProcVersion has been explicitly set to a non-zero version number.

public bool HaveSecurityProcVersion { get; }

Property Value

bool

Remarks

If the SecurityProcVersion has not been set, or has been explicitly set to zero, then the SecurityProcVersion property will return a computed default value. In order to be able to differentiate whether the default version has been returned, or whether the same version has been explicitly set, this property has been added.

IsPinTan

True if this contact uses any PIN/TAN security procedure.

public bool IsPinTan { get; }

Property Value

bool

Remarks

If a SecurityProcCode was set, then it is used to determine whether this contact uses PIN/TAN security, or not. If HaveSecurityProcCode is false, then the SecurityMediaType is used to determine whether this contact uses PIN/TAN security, or not.

IsRAH

True if this contact uses the RAH security procedure.

public bool IsRAH { get; }

Property Value

bool

Remarks

The SecurityProcCode must have been set, before this property returns anything useful.

IsRDH

True if this contact uses the RDH security procedure.

public bool IsRDH { get; }

Property Value

bool

Remarks

The SecurityProcCode must have been set, before this property returns anything useful.

IsRSA

True if this contact uses the RDH or RAH security procedures.

public bool IsRSA { get; }

Property Value

bool

Remarks

The SecurityProcCode must have been set, before this property returns anything useful.

IsSynchronised

Pseudo property that indicates whether this contact is synchronised.

public bool IsSynchronised { get; }

Property Value

bool: If this FinContact must be synchronised before it can be used for a standard FinTS homebanking dialog, then this property will be false. Only if this property is true, then this FinContact can be immediately used to begin a standard FinTS homebanking dialog.

Remarks

A contact must be synchronised if its customer system status (CustSysStat) is one, and there is no customer system ID (CustSysID), or if there are no bank parameter data available. In any other case no synchronisation is needed and this property will be true.

this[string]

The indexer provides access to all the elements of this FinContact by their XML element name.

public string this[string sElementName] { get; set; }

Parameters

sElementName string

Property Value

string

Remarks

The most important elements of a contact can be accessed more conveniently and faster through the properties of this class. This indexer shall only be used in order to access other elements, that are not available as properties.

Basically any string can be stored using any element name. However, there are several well known elements as described in the FinContact class summary. Applications should play by the rules and only use those well known elements.

Exceptions

ArgumentNullException: Passing a null element name will cause an ArgumentNullException to be thrown.
ArgumentOutOfRangeException: An attempt was made to set any of the well known elements to a value that was outside the defined range.

NeedCustSysID

Indicates whether this contact still needs a customer system ID.

public bool NeedCustSysID { get; }

Property Value

bool

See Also: CustSysStat

CustSysID

IsSynchronised

DEPRECATED! Transient PIN to be used by the FinCredentialManager class.

public string PIN { set; }

Property Value

string

Remarks

This PIN is never stored persistently and is only used by the FinCredentialManager class.

PassphraseMaxLength

Provides the maximum allowed length of the passphrase or PIN.

public int PassphraseMaxLength { get; }

Property Value

int

Remarks

This property tries to determine the actual requirements based on the security procedure, the security media and maybe other criteria in order to get a most reasonable value. If any attempt to get a reasonable value fails, then this property will be 256.

HACK: The UniCredit HypoVereinsbank sends a wrong MinPinLength and MaxPinLength in its BPD. Therefore we always allow a min length of 1 character and a max length of 99 characters here.

PassphraseMinLength

Provides the minimum required length of the passphrase or PIN.

public int PassphraseMinLength { get; }

Property Value

int

Remarks

HACK: The UniCredit HypoVereinsbank sends a wrong MinPinLength and MaxPinLength in its BPD. Therefore we always allow a min length of 1 character and a max length of 99 characters here.

PassphraseNumeric

Provides an indicatation whether the passphrase or PIN must be numeric.

public bool PassphraseNumeric { get; }

Property Value

bool

Remarks

PublicUserKeyExponent

For RDH security profiles, this is the public exponent of the user signature key.

public byte[] PublicUserKeyExponent { get; }

Property Value

byte[]

Remarks

This value may be invalid, if there is no public user key known. Only if PublicUserKeyFingerprint is not null, then this property contains a valid value.

PublicUserKeyFingerprint

For RDH security profiles, this is the fingerprint value of the public user signature key.

public byte[] PublicUserKeyFingerprint { get; }

Property Value

byte[]

Remarks

If there is no public user key known, then this is null. Otherwise this is the fingerprint of the public key that is needed for generating an Ini letter.

PublicUserKeyModulus

For RDH security profiles, this is the public modulus of the user signature key.

public byte[] PublicUserKeyModulus { get; }

Property Value

byte[]

Remarks

This value may be invalid, if there is no public user key known. Only if PublicUserKeyFingerprint is not null, then this property contains a valid value.

PublicUserKeyNumber

For RDH security profiles, this is the key number of the public user signature key.

public int PublicUserKeyNumber { get; }

Property Value

int

Remarks

This value may be invalid, if there is no public user key known. Only if PublicUserKeyFingerprint is not null, then this property contains a valid value.

PublicUserKeyVersion

For RDH security profiles, this is the key version of the public user signature key.

public int PublicUserKeyVersion { get; }

Property Value

int

Remarks

This value may be invalid, if there is no public user key known. Only if PublicUserKeyFingerprint is not null, then this property contains a valid value.

RequestSCA

Indicates whether strong customer authentication (HKTAN6) shall be requested for dialog initialization.

public bool RequestSCA { get; }

Property Value

bool

Remarks

Strong customer authentication is only applicable to PIN/TAN security. Hence this is always false for any other security medium.

If StrongCustomerAuthentication is Default, then this property uses a hard coded list of banks, known to not support SCA in order to decide whether a strong customer authentication shall be requested.

See Also: StrongCustomerAuthentication

IsPinTan

SecurityFunction

Security function to be employed in signatures.

public int SecurityFunction { get; set; }

Property Value

int

The following values are defined by HBCI and/or FinTS for this property:

Value	description
1	Security function is RDH or RAH.
900 - 997	Security function is a challenge based PIN/TAN procedure, such as the iTAN procedure. The actual value selects a particular procedure to be used.
999	Security function is the simple PIN/TAN procedure.

If this property is not set, or set to zero, then the default value is derived from the SecurityProcCode and the value of the TanProcedure.

If a PIN/TAN based security is selected, then the TanProcedure defines the returned value as follows: If no TanProcedure is selected, then the returned value will be 999. If a TanProcedure is selected, then the BPD are sought in order to determine the correct value from the HITANS segment. If no BPD are available, or the requested TanProcedure is not supported by the BPD, then again, 999 will be returned.

In any case, the application can override this behavour by overriding the SecurityFunction with a particular value.

The default value is zero.

Setting this value will clear the TanProcedure to be null.

SecurityMedia

The IFinSecurityMedia implementation that is attached to this contact.

public IFinSecurityMedia SecurityMedia { get; }

Property Value

IFinSecurityMedia

Remarks

Contacts that use a security media for signatures, signature verification, encryption and decryption, may have a reference to the IFinSecurityMedia implementation for handling all such requests. This will be null for contacts that use security procedures that do not use a security media, such as PIN/TAN security.

SecurityMediaClassName

Name of class that implements the IFinSecurityMedia interface for this contact.

public string SecurityMediaClassName { get; }

Property Value

string: If no security media is required by this contact, i.e. the property SecurityMediaType contains the value None, then this value may be null. In any other case it shall be set to the name of the class that implements the IFinSecurityMedia interface for the required security media. The default value is null

See Also: SetSecurityMedia(FinSecurityMediaType, string)

SecurityMediaID

Security media ID of security media that is used by this contact.

public string SecurityMediaID { get; set; }

Property Value

string: This property identifies the actual security media that is used by this contact. If no security media is used, then this property may be null, which it is also by default.

Remarks

If a KeyFile is used as the security media, then this property should contain the full path to the key file.

If a SmartCard is used as the security media, then this property should contain a hex representation of the card ID.

SecurityMediaType

Type of security media used by this contact.

public FinSecurityMediaType SecurityMediaType { get; }

Property Value

FinSecurityMediaType: This property indicates the type of security media that use is by this contact, if any. The default value of this property is None.

See Also: SetSecurityMedia(FinSecurityMediaType, string)

SecurityProcCode

Three letter security procedure code.

public string SecurityProcCode { get; set; }

Property Value

string

Remarks

The security procedure code of the security procedure that is employed by this contact. The following security procedure codes are defined in FinTS 3.0: RDH, RAH, PIN (PIN/TAN).

The default value of this property is "PIN".

Exceptions

ArgumentNullException: An attempt was made to set a null value.
ArgumentException: An attempt was made to set a string that was not exactly three characters long.

SecurityProcVersion

Security procedure version.

public int SecurityProcVersion { get; set; }

Property Value

int

Remarks

Additionally qualifies the SecurityProcCode. Currently FinTS 3.0 defines the following security procedure versions: RDH 1 through 10; RAH 7, 9, and 10; PIN/TAN versions 1 and 2.

If the security procedure version is set to its default value zero, then a value based on the currently selected SecurityProcCode and SecurityFunction is returned. For RDH and RAH security procedures the returned value is 1. For a PIN/TAN based security procedure, the returned version is 2 if a two-step TanProcedure or corresponding SecurityFunction is selected, otherwise the returned value is 1.

Exceptions

ArgumentOutOfRangeException: An attempt was made to set a value outside the accepted range from 0 through 999.

SecurityProfile

The SecurityProcCode and SecurityProcVersion combined into a single FinSecurityProfile instance.

public FinSecurityProfile SecurityProfile { get; }

Property Value

FinSecurityProfile

Remarks

This property returns a newly created FinSecurityProfile instance each time it is queried.

SepaAcctInfoBuilder

Convenient cached instance of a FinSepaAcctInfoBuilder based on this contact.

public FinSepaAcctInfoBuilder SepaAcctInfoBuilder { get; }

Property Value

FinSepaAcctInfoBuilder: The instance of the FinSepaAcctInfoBuilder class is created when this property is accessed for the very first time. If it is never accessed, a FinSepaAcctInfoBuilder instance will never be created.

Remarks

Do NOT cache the instance returned through this property. Whenever the BPD are changed, then a new SepaAcctInfoBuilder instance is required. This is ensured by the FinContact object, but cannot be ensured if the SepaAcctInfoBuilder instance was cached!

SignatureID

Next signature counter value to be used (read only).

public long SignatureID { get; }

Property Value

long

The value of the signature counter is in the range from 1 through MAXSIGNATUREID.

The signature counter "SignatureID" is a virtual value based on the number of seconds since 01.01.2012. It is ensured that a new, higher value is provided for each signature.

Remarks

It is important to note that this counter here is independent of any signature counter that may be maintained on a security media. If a security media provides a signature counter, then the signature counter of the security media will be used instead.

StrongCustomerAuthentication

Selects the FinContactSCA choice.

public FinContactSCA StrongCustomerAuthentication { get; set; }

Property Value

FinContactSCA: For new contacts this defaults to Default. See enumeration for a description of possible values.

Remarks

Changing this value will erase any stored BPD data.

This setting may be overridden automatically, by error handling. For example: If RequestSCA is set, but an error from the FinTS system indicates that the FinTS system does not support SCA, then this may be switched automatically to NoSCA.

TanBuilder

Convenient cached instance of a FinTanBuilder based on this contact.

public FinTanBuilder TanBuilder { get; }

Property Value

FinTanBuilder: The instance of the FinTanBuilder class is created when this property is accessed for the very first time. If it is never accessed, a FinTanBuilder instance will never be created.

Remarks

Do NOT cache the instance returned through this property. Whenever the BPD are changed, then a new TanBuilder instance is required. This is ensured by the FinContact object, but cannot be ensured if the TanBuilder instance was cached!

TanMedia

Provides details about the currently selected TAN media, if any.

public FinTanMedia TanMedia { get; }

Property Value

FinTanMedia

TanMediaName

Optional a TAN media name chosen by the user.

public string TanMediaName { get; set; }

Property Value

string

Remarks

A TAN media name may be required by certain TAN procedures. See FinTanProcessParameters.TanMediaNameReqd. The FinTanMediaListBuilder can be used to query a list of TAN media names available to a user.

See Also: TanMedias

TanMedias

The most recently obtained list of TAN medias available to the user.

public FinTanMedia[] TanMedias { get; set; }

Property Value

FinTanMedia[]

TanMediasAgeSeconds

The age of the stored TanMedias list measured in seconds. If there is no stored TanMedias list, then this will be Int32.MaxValue.

public int TanMediasAgeSeconds { get; }

Property Value

int

TanProcedure

OBSOLETE: Indicates the TAN security procedure that shall be used. Use SecurityFunction instead.

public string TanProcedure { get; set; }

Property Value

string

The stored value corresponds with the FinTanProcessParameters property TechnicalIdentification. It is a string that uniquely identifies a two-step TAN procedure. The stored value is null if the classic single-step TAN procedure is used.

The default value is null.

Setting this value will clear SecurityFunction to zero.

TanProcessParameters

public FinTanProcessParameters TanProcessParameters { get; }

Property Value

FinTanProcessParameters

UPD

The current or most recent user parameter data (UPD) that have been collected for this contact.

public FinUserParamData UPD { get; set; }

Property Value

FinUserParamData: If no UPD are available for this contact, yet, then this value will be null.

UPDVersion

The version number of the collected UPD.

public int UPDVersion { get; }

Property Value

int: If no UPD have been collected, then this property will return zero.

UserID

Optional FinTS user identification.

public string UserID { get; set; }

Property Value

string

The user ID may be null or a nonempty string of up to 30 characters. If it is null, then this contact can only be used for anonymous access to the identified bank.

The value of the user ID depends on the FinTS implementation of the bank. For HBCI+ the banks often use an account number instead of a real user ID here.

The default value of this property is null.

Remarks

Changing the user ID of a FinContact instance changes its logical primary key. Therefore all subordinate dynamic properties are erased. This means that the FinContact must be (re-)synchronised.

Exceptions

ArgumentOutOfRangeException: An attempt to set the user ID to a zero length string or a string longer than 30 characters will cause an ArgumentOutOfRangeException to be thrown.

VopOptInBuilder

public FinVopVerificationOptInBuilder VopOptInBuilder { get; }

Property Value

FinVopVerificationOptInBuilder

VopOptOutBuilder

public FinVopVerificationOptOutBuilder VopOptOutBuilder { get; }

Property Value

FinVopVerificationOptOutBuilder

Methods

ActivateBankKeys()

Elevate the bank key status to Active.

public void ActivateBankKeys()

Remarks

This method elevates the bank key status of all bank keys of this contact to the new state Active. The new state is also recorded in the associated security media, if any.

Authenticate(string)

Authenticates the security media attached to this contact.

public FinAuthenticateResult Authenticate(string sPassphrase)

Parameters

sPassphrase string: The passphrase (or PIN, or password) of the security media to be authenticated.

Returns

FinAuthenticateResult

Remarks

This is just a convenience method that simplifies authentication of the attached security media.

Exceptions

ArgumentNullException: The passphrase parameter was null.
InvalidOperationException: Some information required to instantiate, select and authenticate an appropriate security media is missing.

AuthenticateSecure()

Authenticates the smart card of this contact using the secure PIN entry facility of class 2 card readers, if available.

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

Remarks

AuthenticateSecure()

BeginUpdate()

Begin a series of property changes.

public void BeginUpdate()

Remarks

Changing multiple properties should be optimized by calling this method before changing the properties and EndUpdate() after changing the properties. Multiple nested calls to BeginUpdate() are possible, but must be balanced with the same number of calls to EndUpdate().

CanAuthenticateSecure()

public bool CanAuthenticateSecure()

Returns

bool

CreateCommService()

Instantiates a new IFinCommService implementation for this contact.

public IFinCommService CreateCommService()

Returns

IFinCommService: If a comm service was configured that cannot be instantiated, then null is returned. Otherwise a suitable IFinCommService implementation is instantiated and returned.

Remarks

Which IFinCommService implementation will be instantiated depends on the setting of the CommService, CommServiceClassName, and CommServiceAssemblyName contact attributes.

CreateFilter()

Instantiates a new IFinFilter implementation for this contact.

public IFinFilter CreateFilter()

Returns

IFinFilter

Remarks

Which IFinFilter implementation will be instantiated depends on the setting of the FilterFunction and FilterFunctionVersion, contact attributes.

DeleteBankKeys()

Delete the bank keys.

public void DeleteBankKeys()

Remarks

Deletes the bank keys from the contact and from the associated security media.

EndUpdate()

Finish a series of property changes.

public void EndUpdate()

ExportKeys(string, string, string, bool)

Export all RDH keys and user data from this contact into a new, external key file.

public FinAuthenticateResult ExportKeys(string sFilename, string sContactPassword, string sKeyFilePassword, bool fAdoptKeyFile)

Parameters

sFilename string: The complete path of the new key file that shalöl be created.
sContactPassword string: The password for this contact.
sKeyFilePassword string: Password for the new key file.
fAdoptKeyFile bool

Returns

FinAuthenticateResult

Remarks

Keys can only be exported from RDH based contacts that are using KeyFile, or Void security medias.

FindSecurityFunction(string)

Tries to determine the correct security function code from a TAN procedure ID.

public int FindSecurityFunction(string sTanProcedure)

Parameters

sTanProcedure string

Returns

int: If the given TAN procedure ID could be found in the set of allowed TAN procedures, then the corresponding security function code is returned. If it could not be found, either because it does not exist, or there is no TAN information available, then zreo is returned.

FindTanMedia(string)

public FinTanMedia FindTanMedia(string sTanMediaName)

Parameters

sTanMediaName string

Returns

FinTanMedia

FindTanProcessParameters(int)

public FinTanProcessParameters FindTanProcessParameters(int nSecurityFunction)

Parameters

nSecurityFunction int

Returns

FinTanProcessParameters

GetBankKey(FinSecureKeyType)

Retrieve a stored public bank key from this contact.

public FinSecureKey GetBankKey(FinSecureKeyType nKeyType)

Parameters

nKeyType FinSecureKeyType: Selects the type of bank key that shall be returned.

Returns

FinSecureKey: If the requested RSA bank key is available, then it is returned. Otherwise null is returned.

GetInteger(string, int)

Access an element as an integer value.

public int GetInteger(string sElementName, int nDefaultValue)

Parameters

sElementName string: Name of the element to be accessed. This must not be null.
nDefaultValue int: The default value that will be returned if the requested element does not exist or contains some nun-numeric string that could not be parsed.

Returns

int

GetVopOption(FinOrder, bool)

Determines the Verfication of Payee requirements for a given account and order.

public FinVopProcessStep GetVopOption(FinOrder aOrder, bool fOptOutPreferred)

Parameters

aOrder FinOrder: The order for which the VoP option shall be determined. This must not be null.
fOptOutPreferred bool: Only if this is true, then an Opt-Out may be considered and the return value may be OptOut. However, even when Opt-Out is preferred, the bank parameter data may require a Opt-In instead.

Returns

FinVopProcessStep: The return value is always one of None, OptIn, or OptOut. The returned value indicates the initial VoP step that is required when executing the order. If the return value is None, then no VoP is required.

Exceptions

ArgumentNullException
ArgumentException

ImportKeys(string)

public FinAuthenticateResult ImportKeys(string sPassword)

Parameters

sPassword string

Returns

FinAuthenticateResult

InternalSetUserID(string, string)

Private use only!

public void InternalSetUserID(string sUserID, string sDefaultCustID = null)

Parameters

sUserID string
sDefaultCustID string

IsAllowedSecurityFunction(int)

Checks whether the given security function is allowed for the user.

public bool IsAllowedSecurityFunction(int nSecurityFunction)

Parameters

nSecurityFunction int: The security function to be checked.

Returns

bool

If AllowedSecurityFunctions is null, then false is returned. There is one legacy exception to this rule: If there are no AllowedSecurityFunctions, and nSecurityFunction is 999 and RequestSCA is false, and the server does not support HKTAN, then true is returned.

In any other case: Only if the requested nSecurityFunction is contained in the AllowedSecurityFunctions data then true is returned. Otherwise false is returned.

ProduceOrderAcct(FinAcctTypeClass, SepaIBAN, SepaBIC, string)

public FinAcct ProduceOrderAcct(FinAcctTypeClass nAcctTypeClass, SepaIBAN tAcctIBAN, SepaBIC tAcctBIC, string sAcctCurrency)

Parameters

nAcctTypeClass FinAcctTypeClass
tAcctIBAN SepaIBAN: IBAN of the ordering account.
tAcctBIC SepaBIC: BIC of the ordering account.
sAcctCurrency string

Returns

FinAcct

Exceptions

ArgumentException: The parameter tAcctIBAN was null.

See Also: ProduceOrderAcct(FinAcctTypeClass, string, string, string)

ProduceOrderAcct(FinAcctTypeClass, string, string, string)

public FinAcct ProduceOrderAcct(FinAcctTypeClass nAcctTypeClass, string sAcctBankCode, string sAcctNo, string sAcctCurrency)

Parameters

nAcctTypeClass FinAcctTypeClass: The class of the account type to be sought. An attempt is made to match this class to the account type of the available accounts. If a perfect match is found, then that account is returned. If no match is found, then the first account where the other criterias are matching is returned.
sAcctBankCode string: The bank code of the account that is sought. If this is null, then the bank code will be ignored when matching the HIUPD segments.
sAcctNo string: The account number of the account that is sought. This must not be null, and must not be an empty string. Any leading zeroes are ignored.
sAcctCurrency string: The currency of the account that is sought. If this is null, then the currency will be ignored when matching the HIUPD segments. It is required, to pass null for the currency when seeking a portfolio account. It is highly recommended to pass a valid currency for all other account types.

Returns

FinAcct

Exceptions

ArgumentNullException: The parameter sAcctNo was null.

See Also: ProduceOrderAcct(FinAcctTypeClass, SepaIBAN, SepaBIC, string)

PutBankKey(FinSecureKey)

Store a public bank key in this contact and its associated security media.

public void PutBankKey(FinSecureKey aBankKey)

Parameters

aBankKey FinSecureKey: The bank key to be stored. This was usually received by an online request.

Remarks

The FinDialog class uses this method in order to store bank keys that are received during the dialog initialisation phase.

ReadXml(XmlReader)

Read all contact data from an XmlReader.

public override void ReadXml(XmlReader aXmlReader)

Parameters

aXmlReader XmlReader: The XmlReader instance to read all data from. Must not be null.

See Also: WriteXml(XmlWriter)

Release()

Releases the attached security media.

public void Release()

Remarks

If a security media is attached, then its Release() method is called. Thus the security media returns to the Null state. The IFinSecurityMedia implementation will still remain attached to the SecurityMedia property.

If no security media is attached, then this does basically nothing.

Reset()

Resets all dynamic state of this contact.

public void Reset()

Remarks

The dynamic state includes the CustSysID, SignatureID, BPD, UPD, AllowedSecurityFunctions, and TanMedias. After a reset, the contact has to be synchronized.

ResetCustSysID()

Resets the CustSysID and SignatureID.

public void ResetCustSysID()

Remarks

This methods sets the CustSysID to null and resets the SignatureID.

SelectSecurityMedia()

Ensure that a security media is available by selecting it.

public FinAuthenticateResult SelectSecurityMedia()

Returns

FinAuthenticateResult: If the configured security media is physically available and was successfully selected, then Success is returned. Other allowed results are NoSecurityMedia and WrongSecurityMedia.

SelectSecurityMedia(string)

Attempts to select a security media with a particular security media ID for this contact.

public FinAuthenticateResult SelectSecurityMedia(string sSecurityMediaID)

Parameters

sSecurityMediaID string: A particular security media ID that shall be selected for this contact. This must not be null and must not be an empty string.

Returns

FinAuthenticateResult: If the given security media is physically available and was successfully selected, then Success is returned. Other allowed results are NoSecurityMedia and WrongSecurityMedia.

Remarks

This method may be useful when dealing with key files that have not a fixed location. For key files the security media ID is the file path of the key file. Hence, calling this method with the actual file path of a key file will use the given key file, regardless of the current value of the SecurityMediaID property.

Exceptions

ArgumentNullException: The parameter sSecurityMediaID was null.
ArgumentException: The parameter sSecurityMediaID was an empty string.
InvalidOperationException: This contact does not use security medias, i.e. the value of SecurityMediaType is None.

SetCommService(FinCommService, string)

Set the communication service and address.

public void SetCommService(FinCommService nCommService, string sCommAddress)

Parameters

nCommService FinCommService: Selects the communication service to be used.
sCommAddress string: Selects the communication address to connect to. The format of the address depends on the selected communication service.

SetFilterFunction(string)

Set the encoding filter to be used for transmission.

public void SetFilterFunction(string sFilterFunction)

Parameters

sFilterFunction string: The filter function as defined by HBCI. If this is null, then no filter function will be applied. The only other value that is supported is "MIM" which will apply a base 64 encoding on the data transmitted.

Remarks

Although the implementaion is functionally fully independent from the actual communication service that is used, the HBCI standard requires that raw TCP communication TcpIp does not use a filter and that HTTP based communication Https must use the base 64 encoding "MIM" filter.

The filter function version is always set to the only defined value "1" by this method.

SetHttpHeader(string, string)

Set or clear a custom HTTP header to be included in the HTTP request sent by SendReceive(FinDialog, FinMessageBuffer)

public void SetHttpHeader(string sHeaderName, string sHeaderValue)

Parameters

sHeaderName string: Name of HTTP header to set. This must not be any of the standard HTTP headers. If a header with that name was already set, then its value will be replaced with the new sHeaderValue.
sHeaderValue string: Header value string. If this is null, then the custom header will be removed, if it was set before.

SetInteger(string, int)

Set an element as an integer value.

public void SetInteger(string sElementName, int nValue)

Parameters

sElementName string: Name of the element to be accessed. This must not be null.
nValue int: The integer value to set.

SetSecurityMedia(FinSecurityMediaType, string)

Set the security media type and implementation.

public void SetSecurityMedia(FinSecurityMediaType nSecurityMediaType, string sSecurityMediaClassName)

Parameters

nSecurityMediaType FinSecurityMediaType: THe type of security media.
sSecurityMediaClassName string: Optional fully qualified class name of the .NET Class that implements the security media.

Remarks

Important: This method does not release any previously created and/or authenticated security media that is already associated with this contact. In order to ensure that there are no dead security media classes hanging around, an application shall call Release() before setting the security media.

ToString()

public override string ToString()

Returns

string

WriteXml(XmlWriter)

Writes the contact data as a single <FinContact> XML node to the given XML writer.

public override void WriteXml(XmlWriter aXmlWriter)

Parameters

aXmlWriter XmlWriter: The XML writer to write the data to.

Exceptions

ArgumentNullException: The parameter aXmlWriter was null.