Class FinContact

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

Inheritance
System.Object
FinPersist
FinContact
Inherited Members
System.Object.Equals(System.Object)
System.Object.Equals(System.Object, System.Object)
System.Object.GetHashCode()
System.Object.GetType()
System.Object.MemberwiseClone()
System.Object.ReferenceEquals(System.Object, System.Object)
Namespace: Subsembly.FinTS
Assembly: Subsembly.FinTS.Core.dll
Syntax
public sealed class FinContact : FinPersist
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 ElementDescription
ContactNamePurely optional human readable name that tags this contact. If absent, then the contact won't have a name but can be used anyway.
CountryCodeISO 3166 numeric country code that identifies the country where the bank resides. This corresponds to the CountryCode property.
BankCodeBank code that identifies the bank within the country given by the country code. This corresponds to the BankCode property.
UserIDOptional FinTS user identification. If absent, then this is a contact that uses anonymous access to the identified bank. This corresponds to the UserID property.
FinTSVersionThe 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.
CustSysStatFinTS customer system status. If absent, then the default value 1 is assumed. This corresponds to the CustSysStat property.
CustSysIDOptional FinTS customer system ID. This corresponds to the CustSysID property.
SignatureIDNext signature counter value to be used. If absent, then the counter will be restarted with the value one. This corresponds to the SignatureID property.
DefaultLanguageThe 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.
DefaultCustIDThe 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.
DefaultResponseTimeoutDefault 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.

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

FilterFunctionVersionFinTS only defines the value 1 for this attribute, hence it is ignored, for now.
SecurityProcCodeThe security procedure code of the security procedure that is employed by this contact.
SecurityProcVersionAdditionally 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.
SecurityMediaIDAdditional identification of the security media. The meaning of this property depends on the security media class implementation.
BankParamDataThe complete sequence of bank parameter data (BPD) segments inside a single base 64 encoded BLOB.
UserParamDataThe complete sequence of user parameter data (UPD) segments as a single base 64 encoded BLOB.
BankKeyHashOptional the base 64 encoded fingerprint value of the bank keys. Provided through the property BankKeyFingerprint.
BankKeyHashAlgOptional the hash algorithm used for computing the BankKeyHash. "999" is RIPEMD-160 and "3" ist SHA-256. See FingerprintHashAlgorithm.
TanMediaNameOptional a TAN media name chosen by the user. If this is set, then the given TAN medium will be used.
StrongCustomerAuthenticationAn 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.

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

Declaration
public FinContact(IFinSecurityMedia aSecurityMedia)
Parameters
Type Name Description
IFinSecurityMedia aSecurityMedia

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.

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.

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

FinContact(String, Int32, String, String, String)

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

Declaration
[Obsolete]
public FinContact(string sCommAddress, int nFinTSVersion, string sTanProcedure, string sBankCode, string sUserID)
Parameters
Type Name Description
System.String sCommAddress

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.
System.Int32 nFinTSVersion

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.
System.String sTanProcedure

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.
System.String sBankCode

The bank code (eight digits) of the new contact.
System.String sUserID

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
Type Condition
System.ArgumentNullException

At least one of the parameters sCommAddress, sBankCode, or sUserID was null.
System.ArgumentOutOfRangeException

The given FinTS version was outside the range 0 through 999.
System.ArgumentException

One of the parameters was otherwise invalid.

FinContact(String, String, String)

Creates an all new FinContact for PIN/TAN security.

Declaration
public FinContact(string sCommAddress, string sBankCode, string sUserID)
Parameters
Type Name Description
System.String sCommAddress

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.
System.String sBankCode

The bank code (eight digits) of the new contact.
System.String sUserID

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
Type Condition
System.ArgumentNullException

At least one of the parameters sCommAddress, sBankCode, or sUserID was null.
System.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.

Declaration
public const int DEFAULTFINTSVERSION = 300
Field Value
Type Description
System.Int32

MAXSIGNATUREID

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

Declaration
public const long MAXSIGNATUREID = 9999999999999999L
Field Value
Type Description
System.Int64

Properties

AllowedSecurityFunctions

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

Declaration
public string[] AllowedSecurityFunctions { get; set; }
Property Value
Type Description
System.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.

BankCode

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

Declaration
public string BankCode { get; set; }
Property Value
Type Description
System.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
Type Condition
System.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.

Declaration
public byte[] BankKeyFingerprint { get; set; }
Property Value
Type Description
System.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.

BPD

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

Declaration
public FinBankParamData BPD { get; set; }
Property Value
Type Description
FinBankParamData

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

BPDVersion

The version number of the collected BPD.

Declaration
public int BPDVersion { get; }
Property Value
Type Description
System.Int32

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

CommAddress

Convenient shortcut for accessing the CommAddress attribute.

Declaration
public string CommAddress { get; }
Property Value
Type Description
System.String
See Also

CommService

Convenient shortcut for accessing the CommService attribute.

Declaration
public FinCommService CommService { get; }
Property Value
Type Description
FinCommService
See Also

ContactFolder

Optional reference to IFinContactFolder instance that hosts this contact.

Declaration
public IFinContactFolder ContactFolder { get; set; }
Property Value
Type Description
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.

Declaration
public Guid ContactGuid { get; }
Property Value
Type Description
System.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.

Declaration
public string ContactName { get; set; }
Property Value
Type Description
System.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
Type Condition
System.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.

Declaration
public string CountryCode { get; set; }
Property Value
Type Description
System.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
Type Condition
System.ArgumentOutOfRangeException

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

CustSysID

Optional FinTS customer system ID.

Declaration
public string CustSysID { get; set; }
Property Value
Type Description
System.String

The customer system ID may be null or a nonempty string of up to 30 characters.
Exceptions
Type Condition
System.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.

Declaration
public int CustSysStat { get; set; }
Property Value
Type Description
System.Int32

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
Type Condition
System.ArgumentOutOfRangeException

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

DefaultCustID

Declaration
public string DefaultCustID { get; set; }
Property Value
Type Description
System.String

EnableSecurePinEntry

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

Declaration
public bool EnableSecurePinEntry { get; set; }
Property Value
Type Description
System.Boolean
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.

Declaration
public string FilterFunction { get; }
Property Value
Type Description
System.String
See Also

FilterFunctionVersion

The filter function version as defined by HBCI.

Declaration
public int FilterFunctionVersion { get; }
Property Value
Type Description
System.Int32
See Also

FingerprintHashAlgorithm

The hash algorithm to be used to compute key fingerprints.

Declaration
public FinHash FingerprintHashAlgorithm { get; set; }
Property Value
Type Description
FinHash
Remarks

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

FinTSVersion

The FinTS version for which this contact is configured.

Declaration
public int FinTSVersion { get; set; }
Property Value
Type Description
System.Int32

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
Type Condition
System.ArgumentOutOfRangeException

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

HaveFinTSVersion

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

Declaration
public bool HaveFinTSVersion { get; }
Property Value
Type Description
System.Boolean
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.

Declaration
public bool HaveSecurityFunction { get; }
Property Value
Type Description
System.Boolean

HaveSecurityProcCode

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

Declaration
public bool HaveSecurityProcCode { get; }
Property Value
Type Description
System.Boolean

HaveSecurityProcVersion

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

Declaration
public bool HaveSecurityProcVersion { get; }
Property Value
Type Description
System.Boolean
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.

Declaration
public bool IsPinTan { get; }
Property Value
Type Description
System.Boolean
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.

Declaration
public bool IsRAH { get; }
Property Value
Type Description
System.Boolean
Remarks

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

IsRDH

True if this contact uses the RDH security procedure.

Declaration
public bool IsRDH { get; }
Property Value
Type Description
System.Boolean
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.

Declaration
public bool IsRSA { get; }
Property Value
Type Description
System.Boolean
Remarks

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

IsSynchronised

Pseudo property that indicates whether this contact is synchronised.

Declaration
public bool IsSynchronised { get; }
Property Value
Type Description
System.Boolean

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.

Item[String]

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

Declaration
public string this[string sElementName] { get; set; }
Parameters
Type Name Description
System.String sElementName
Property Value
Type Description
System.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
Type Condition
System.ArgumentNullException

Passing a null element name will cause an ArgumentNullException to be thrown.
System.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.

Declaration
public bool NeedCustSysID { get; }
Property Value
Type Description
System.Boolean
See Also

PassphraseMaxLength

Provides the maximum allowed length of the passphrase or PIN.

Declaration
public int PassphraseMaxLength { get; }
Property Value
Type Description
System.Int32
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.

Declaration
public int PassphraseMinLength { get; }
Property Value
Type Description
System.Int32
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 zero.

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.

Declaration
public bool PassphraseNumeric { get; }
Property Value
Type Description
System.Boolean
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 false.

PIN

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

Declaration
public string PIN { set; }
Property Value
Type Description
System.String
Remarks

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

PublicUserKeyExponent

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

Declaration
public byte[] PublicUserKeyExponent { get; }
Property Value
Type Description
System.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.

Declaration
public byte[] PublicUserKeyFingerprint { get; }
Property Value
Type Description
System.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.

Declaration
public byte[] PublicUserKeyModulus { get; }
Property Value
Type Description
System.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.

Declaration
public int PublicUserKeyNumber { get; }
Property Value
Type Description
System.Int32
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.

Declaration
public int PublicUserKeyVersion { get; }
Property Value
Type Description
System.Int32
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.

Declaration
public bool RequestSCA { get; }
Property Value
Type Description
System.Boolean
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

SecurityFunction

Security function to be employed in signatures.

Declaration
public int SecurityFunction { get; set; }
Property Value
Type Description
System.Int32

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

Valuedescription
1Security function is RDH or RAH.
900 - 997Security function is a challenge based PIN/TAN procedure, such as the iTAN procedure. The actual value selects a particular procedure to be used.
999Security 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.

Declaration
public IFinSecurityMedia SecurityMedia { get; }
Property Value
Type Description
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.

Declaration
public string SecurityMediaClassName { get; }
Property Value
Type Description
System.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

SecurityMediaID

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

Declaration
public string SecurityMediaID { get; set; }
Property Value
Type Description
System.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.

Declaration
public FinSecurityMediaType SecurityMediaType { get; }
Property Value
Type Description
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

SecurityProcCode

Three letter security procedure code.

Declaration
public string SecurityProcCode { get; set; }
Property Value
Type Description
System.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
Type Condition
System.ArgumentNullException

An attempt was made to set a null value.
System.ArgumentException

An attempt was made to set a string that was not exactly three characters long.

SecurityProcVersion

Security procedure version.

Declaration
public int SecurityProcVersion { get; set; }
Property Value
Type Description
System.Int32
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
Type Condition
System.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.

Declaration
public FinSecurityProfile SecurityProfile { get; }
Property Value
Type Description
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.

Declaration
public FinSepaAcctInfoBuilder SepaAcctInfoBuilder { get; }
Property Value
Type Description
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).

Declaration
public long SignatureID { get; }
Property Value
Type Description
System.Int64

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.

Declaration
public FinContactSCA StrongCustomerAuthentication { get; set; }
Property Value
Type Description
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.

Declaration
public FinTanBuilder TanBuilder { get; }
Property Value
Type Description
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.

Declaration
public FinTanMedia TanMedia { get; }
Property Value
Type Description
FinTanMedia

TanMediaName

Optional a TAN media name chosen by the user.

Declaration
public string TanMediaName { get; set; }
Property Value
Type Description
System.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

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

Declaration
public FinTanMedia[] TanMedias { get; set; }
Property Value
Type Description
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.

Declaration
public int TanMediasAgeSeconds { get; }
Property Value
Type Description
System.Int32

TanProcedure

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

Declaration
public string TanProcedure { get; set; }
Property Value
Type Description
System.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

Declaration
public FinTanProcessParameters TanProcessParameters { get; }
Property Value
Type Description
FinTanProcessParameters

UPD

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

Declaration
public FinUserParamData UPD { get; set; }
Property Value
Type Description
FinUserParamData

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

UPDVersion

The version number of the collected UPD.

Declaration
public int UPDVersion { get; }
Property Value
Type Description
System.Int32

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

UserID

Optional FinTS user identification.

Declaration
public string UserID { get; set; }
Property Value
Type Description
System.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
Type Condition
System.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.

Methods

ActivateBankKeys()

Elevate the bank key status to Active.

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

Declaration
public FinAuthenticateResult Authenticate(string sPassphrase)
Parameters
Type Name Description
System.String sPassphrase

The passphrase (or PIN, or password) of the security media to be authenticated.
Returns
Type Description
FinAuthenticateResult
Remarks

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

Exceptions
Type Condition
System.ArgumentNullException

The passphrase parameter was null.
System.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.

Declaration
public FinAuthenticateResult AuthenticateSecure()
Returns
Type Description
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.

Declaration
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()

Declaration
public bool CanAuthenticateSecure()
Returns
Type Description
System.Boolean

CreateCommService()

Instantiates a new IFinCommService implementation for this contact.

Declaration
public IFinCommService CreateCommService()
Returns
Type Description
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.

Declaration
public IFinFilter CreateFilter()
Returns
Type Description
IFinFilter
Remarks

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

DeleteBankKeys()

Delete the bank keys.

Declaration
public void DeleteBankKeys()
Remarks

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

EndUpdate()

Finish a series of property changes.

Declaration
public void EndUpdate()

ExportKeys(String, String, String, Boolean)

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

Declaration
public FinAuthenticateResult ExportKeys(string sFilename, string sContactPassword, string sKeyFilePassword, bool fAdoptKeyFile)
Parameters
Type Name Description
System.String sFilename

The complete path of the new key file that shalöl be created.
System.String sContactPassword

The password for this contact.
System.String sKeyFilePassword

Password for the new key file.
System.Boolean fAdoptKeyFile
Returns
Type Description
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.

Declaration
public int FindSecurityFunction(string sTanProcedure)
Parameters
Type Name Description
System.String sTanProcedure
Returns
Type Description
System.Int32

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)

Declaration
public FinTanMedia FindTanMedia(string sTanMediaName)
Parameters
Type Name Description
System.String sTanMediaName
Returns
Type Description
FinTanMedia

FindTanProcessParameters(Int32)

Declaration
public FinTanProcessParameters FindTanProcessParameters(int nSecurityFunction)
Parameters
Type Name Description
System.Int32 nSecurityFunction
Returns
Type Description
FinTanProcessParameters

GetBankKey(FinSecureKeyType)

Retrieve a stored public bank key from this contact.

Declaration
public FinSecureKey GetBankKey(FinSecureKeyType nKeyType)
Parameters
Type Name Description
FinSecureKeyType nKeyType

Selects the type of bank key that shall be returned.
Returns
Type Description
FinSecureKey

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

GetInteger(String, Int32)

Access an element as an integer value.

Declaration
public int GetInteger(string sElementName, int nDefaultValue)
Parameters
Type Name Description
System.String sElementName

Name of the element to be accessed. This must not be null.
System.Int32 nDefaultValue

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
Type Description
System.Int32

ImportKeys(String)

Declaration
public FinAuthenticateResult ImportKeys(string sPassword)
Parameters
Type Name Description
System.String sPassword
Returns
Type Description
FinAuthenticateResult

InternalSetUserID(String, String)

Private use only!

Declaration
public void InternalSetUserID(string sUserID, string sDefaultCustID = null)
Parameters
Type Name Description
System.String sUserID
System.String sDefaultCustID

IsAllowedSecurityFunction(Int32)

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

Declaration
public bool IsAllowedSecurityFunction(int nSecurityFunction)
Parameters
Type Name Description
System.Int32 nSecurityFunction

The security function to be checked.
Returns
Type Description
System.Boolean

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)

Declaration
public FinAcct ProduceOrderAcct(FinAcctTypeClass nAcctTypeClass, SepaIBAN tAcctIBAN, SepaBIC tAcctBIC, string sAcctCurrency)
Parameters
Type Name Description
FinAcctTypeClass nAcctTypeClass
SepaIBAN tAcctIBAN

IBAN of the ordering account.
SepaBIC tAcctBIC

BIC of the ordering account.
System.String sAcctCurrency
Returns
Type Description
FinAcct
Exceptions
Type Condition
System.ArgumentException

The parameter tAcctIBAN was null.
See Also

ProduceOrderAcct(FinAcctTypeClass, String, String, String)

Declaration
public FinAcct ProduceOrderAcct(FinAcctTypeClass nAcctTypeClass, string sAcctBankCode, string sAcctNo, string sAcctCurrency)
Parameters
Type Name Description
FinAcctTypeClass nAcctTypeClass

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.
System.String sAcctBankCode

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.
System.String sAcctNo

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.
System.String sAcctCurrency

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
Type Description
FinAcct
Exceptions
Type Condition
System.ArgumentNullException

The parameter sAcctNo was null.
See Also

PutBankKey(FinSecureKey)

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

Declaration
public void PutBankKey(FinSecureKey aBankKey)
Parameters
Type Name Description
FinSecureKey aBankKey

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.

Declaration
public override void ReadXml(XmlReader aXmlReader)
Parameters
Type Name Description
System.Xml.XmlReader aXmlReader

The XmlReader instance to read all data from. Must not be null.
Overrides
See Also

Release()

Releases the attached security media.

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

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

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

Declaration
public FinAuthenticateResult SelectSecurityMedia()
Returns
Type Description
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.

Declaration
public FinAuthenticateResult SelectSecurityMedia(string sSecurityMediaID)
Parameters
Type Name Description
System.String sSecurityMediaID

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
Type Description
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
Type Condition
System.ArgumentNullException

The parameter sSecurityMediaID was null.
System.ArgumentException

The parameter sSecurityMediaID was an empty string.
System.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.

Declaration
public void SetCommService(FinCommService nCommService, string sCommAddress)
Parameters
Type Name Description
FinCommService nCommService

Selects the communication service to be used.
System.String sCommAddress

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.

Declaration
public void SetFilterFunction(string sFilterFunction)
Parameters
Type Name Description
System.String sFilterFunction

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)

Declaration
public void SetHttpHeader(string sHeaderName, string sHeaderValue)
Parameters
Type Name Description
System.String sHeaderName

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.
System.String sHeaderValue

Header value string. If this is null, then the custom header will be removed, if it was set before.

SetInteger(String, Int32)

Set an element as an integer value.

Declaration
public void SetInteger(string sElementName, int nValue)
Parameters
Type Name Description
System.String sElementName

Name of the element to be accessed. This must not be null.
System.Int32 nValue

The integer value to set.

SetSecurityMedia(FinSecurityMediaType, String)

Set the security media type and implementation.

Declaration
public void SetSecurityMedia(FinSecurityMediaType nSecurityMediaType, string sSecurityMediaClassName)
Parameters
Type Name Description
FinSecurityMediaType nSecurityMediaType

THe type of security media.
System.String sSecurityMediaClassName

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

Declaration
public override string ToString()
Returns
Type Description
System.String
Overrides
System.Object.ToString()

WriteXml(XmlWriter)

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

Declaration
public override void WriteXml(XmlWriter aXmlWriter)
Parameters
Type Name Description
System.Xml.XmlWriter aXmlWriter

The XML writer to write the data to.
Overrides
Exceptions
Type Condition
System.ArgumentNullException

The parameter aXmlWriter was null.