Class EbicsSecurityMediumContact

Namespace: Subsembly.EBICS

Assembly: Subsembly.EBICS.Core.dll

Implementation of IEbicsSecurityMedium with flexible key storage and key management information stored in a EbicsContact that owns the keys.

[Obfuscation(Exclude = true, ApplyToMembers = false)]
public class EbicsSecurityMediumContact : IEbicsSecurityMedium, IEbicsSecurityMediumSignature, IEbicsSecurityMediumPrivKeys

Inheritance: object

EbicsSecurityMediumContact

Implements: IEbicsSecurityMedium

IEbicsSecurityMediumSignature

IEbicsSecurityMediumPrivKeys

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

This implementation replaces the EbicsSecurityMediumVoid providing more flexibility and better security. It provides more flexibility by offering the possibility to override the actual key blob storage for each key individually. It offers better security by using different passwords for INI and HIA keys.

The password provided to Authenticate(string) is used to encrypt the private keys as securely as possible. Optionally another, different password may be used to encrypt the digital signature key (INI).

For more secure storage of keys, an override may take over key storage and store the keys in some secure storage on device.

Constructors

EbicsSecurityMediumContact(EbicsContact)

public EbicsSecurityMediumContact(EbicsContact aContact)

Parameters

aContact EbicsContact: The EbicsContact that will be used to store the private keys.

Fields

CLASSNAME

The fully namespace qualified class name of this class.

public const string CLASSNAME = "Subsembly.EBICS.EbicsSecurityMediumContact"

Field Value

string

Properties

CanChangePIN

Indicates whether the password can be changed.

public bool CanChangePIN { get; }

Property Value

bool: Changing the password is supported by this implementation and therefore this property is always true.

CanChangeSignaturePassword

As this implementation supports changing the digital signature password, the value is always true.

public bool CanChangeSignaturePassword { get; }

Property Value

bool

LastError

public EbicsSecurityMediumErrorCode LastError { get; }

Property Value

EbicsSecurityMediumErrorCode

NeedAuthenticateSignature

Indicates whether AuthenticateSignature(string) must be called before a digital signature can be done.

public bool NeedAuthenticateSignature { get; }

Property Value

bool

SecurityMedium

Always is "0000".

public string SecurityMedium { get; }

Property Value

string

SecurityMediumID

public string SecurityMediumID { get; }

Property Value

string

SecurityMediumType

public EbicsSecurityMediumType SecurityMediumType { get; }

Property Value

EbicsSecurityMediumType

State

public EbicsSecurityMediumState State { get; }

Property Value

EbicsSecurityMediumState

SupportedSecurityCodes

Provides the set of EBICS security operations that are supported by this security media implementation.

public EbicsSecurityCode SupportedSecurityCodes { get; }

Property Value

EbicsSecurityCode

Remarks

The EbicsSecurityMediumVoid implementation always supports all security operations defined by the EbicsSecurityCode enumeration. However, only those security operations are possible, where there are actually private keys available in the selected contact.

Methods

Authenticate(string)

Authenticate this security medium with the given authentication password.

public bool Authenticate(string sPassword)

Parameters

sPassword string

Returns

bool

Remarks

Whenever this method is called the digital signature key authentication is reset and then retried using an empty string as the digital signature password. Hence, if no digital signature password was initialized, then this authentication also authenticates the digital signature key. If a different digital signature password was set, then it must be explicitly authenticated using AuthenticateSignature(string).

Exceptions

ArgumentNullException

AuthenticateSignature(string)

Authenticate the digitial signature key, so that it can be used for digital signatures (A004, A005, or A006).

public bool AuthenticateSignature(string sPassword)

Parameters

sPassword string: The digitial signature key password. This must not be null.

Returns

bool

Exceptions

ArgumentNullException: The parameter sPassword was null.
InvalidOperationException: This instance is not in the Authenticated State.

ChangePIN(string, string)

Change the authentication password.

public bool ChangePIN(string sOldPassword, string sNewPassword)

Parameters

sOldPassword string
sNewPassword string

Returns

bool

Exceptions

ArgumentNullException: The parameter sOldPassword or sNewPassword was null.
InvalidOperationException: This security medium instance is neither in the Selected state, nor in the Authenticated.

ChangeSignaturePassword(string, string)

Change the password that protects the digital signature key.

public bool ChangeSignaturePassword(string sOldPassword, string sNewPassword)

Parameters

sOldPassword string: The current digital signature key password. If no digital signature key password is set, then an empty string must be passed. The parameter must not be null.
sNewPassword string: The new digital signature key password. If the digital signature key password shall be disabled, then this parameter must be an empty string. The parameter must not be null. It must also meet the requirements returned by GetSignaturePasswordInfo().

Returns

bool: If the digital signature key password was changed successfully, then true is returned. If changing the password failed, then false is returned, and the old password is still in effect.

Remarks

This instance must have been successfully authenticated before this method may be called.

For a newly created EbicsSecurityMediumContact, the password for the digital signature key will be an empty string. Setting the password to an empty string effectively disables the digital signature password. If the password is an empty string a successful call to Authenticate(string) implicitly also authenticates the digital signature key, and there is no need to call AuthenticateSignature(string).

Exceptions

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

Create(string, string)

public bool Create(string sSecurityMediaID, string sPassword)

Parameters

sSecurityMediaID string: This is not needed by the EbicsSecurityMediumContact and may have any value.
sPassword string

Returns

bool

Remarks

When a new EbicsSecurityMediumContact security medium is created through this method, then the digital signature password will be initialized with an empty string. In order to setup a different digital signature password, the method ChangeSignaturePassword(string, string) must be used, passing an empty string as the old digital signature password.

Exceptions

ArgumentNullException
InvalidOperationException

GetPasswordInfo()

public EbicsPasswordInfo GetPasswordInfo()

Returns

EbicsPasswordInfo

GetSecurityOperations(EbicsContact, EbicsSecurityCode)

public IEbicsSecurityOperations GetSecurityOperations(EbicsContact aContact, EbicsSecurityCode nCode)

Parameters

aContact EbicsContact
nCode EbicsSecurityCode

Returns

IEbicsSecurityOperations

GetSignaturePasswordInfo()

public EbicsPasswordInfo GetSignaturePasswordInfo()

Returns

EbicsPasswordInfo

Release()

public void Release()

RetrieveKey(EbicsContact, EbicsSecurityCode)

Overridable hook for retrieving a previously stored key blob.

protected virtual byte[] RetrieveKey(EbicsContact aContact, EbicsSecurityCode nCode)

Parameters

aContact EbicsContact: The contact for which the key blob shall be retrieved. This is the same contact that was used when this instance was created.
nCode EbicsSecurityCode: Identifies the key to be retrieved.

Returns

byte[]: Returns the key blob that was previously stored for nCode. If nothing was stored for that code, then null shall be returned.

Select(string)

public bool Select(string sSecurityMediaID)

Parameters

sSecurityMediaID string

Returns

bool

StoreKey(EbicsContact, EbicsSecurityCode, byte[])

Overridable hook for storing an encrypted key blob.

protected virtual void StoreKey(EbicsContact aContact, EbicsSecurityCode nCode, byte[] vbKeyBlob)

Parameters

aContact EbicsContact: The contact for which the key blob shall be stored. This is the same EbicsContact that this instance was created from.
nCode EbicsSecurityCode: Identifies the key to be stored. For each possible EbicsSecurityCode, only a single key may be stored. If there already is a key for the given code, it shall be overwritten by the given key blob.
vbKeyBlob byte[]: The encrypted key blob to be stored. Currently this is 4096 bytes in size. If this parameter is null, then any key stored for nCode shall be erased.

Remarks

The default implementation simply stores the key blob in the given aContact.