Interface IEbicsSecurityMedium

Interface for integrating RSA security tokens, such as smart cards, as EBICS security medias.

Namespace: Subsembly.EBICS

Assembly: Subsembly.EBICS.Core.dll

Syntax

public interface IEbicsSecurityMedium

Remarks

This interface provides a very simple and generic way to integrate almost any security token that supports the RSA primitive operations as a security media for EBICS security operations.

The IEbicsSecurityMedium interface uses the concept of a SecurityMediaID which uniquely identifies a security medium. A SecurityMediaID may be a smart card ID, a hardware serial number, a file name, or something similar that uniquely identifies the token. The SecurityMediaID is required in order to avoid accidental use of the wrong security medium. An implemenation may use any non-empty string as a SecurityMediaID.

The interface does not provide generic methods for creating security medias, such as key files, and also does no provide administration methods such as for changing PINs. Such methods are token specific and therefore are implemented only in concrete classes.

Properties

CanChangePIN

Indicates whether the PIN (or password or whatever) of the security medium can be changed via ChangePIN(String, String).

Declaration

bool CanChangePIN { get; }

Property Value

Type	Description
System.Boolean

LastError

The security medium error code from the most recent failing method.

Declaration

EbicsSecurityMediumErrorCode LastError { get; }

Property Value

Type	Description
EbicsSecurityMediumErrorCode

Remarks

If the last operation completed successfully, then the value of this property is undefined. It may be zero, or 0x9000, or anything else. Only if the last operation did fail, then this property provides an error code.

The property value is either a positive smart card status word as defined in ISO 7816 part 4, or one of the special, negative failure values defined for the EbicsSecurityMediumError enumeration.

This property may be read in any state and at any time, even when no security token is present. However, it provides a meaningful value only, when a previous call to this interface has returned with failure.

SecurityMedium

Provides the content for the <SecurityMedium> XML element in an EBICS request.

Declaration

string SecurityMedium { get; }

Property Value

Type	Description
System.String

Remarks

According to the EBICS specification this value is defined as follows:

0000	No specification
01dd	Diskette
02dd	Chipcard
03dd	Other removable storage medium
04dd	Non-removable storage medium

In the above table, "dd" represents any number combination that is specified individually by each institution.

This property may be read in any state and at any time, even when no security token is present.

SecurityMediumID

The ID of the currently selected or authenticated security medium.

Declaration

string SecurityMediumID { get; }

Property Value

Type	Description
System.String

Remarks

In the Null state, this is null.

This property may be read in any state and at any time, even when no security token is present.

SecurityMediumType

The physical type of security medium implemented by this interface.

Declaration

EbicsSecurityMediumType SecurityMediumType { get; }

Property Value

Type	Description
EbicsSecurityMediumType

Remarks

This property may be read in any state and at any time, even when no security token is present.

State

Indicates the current state of the security medium.

Declaration

EbicsSecurityMediumState State { get; }

Property Value

Type	Description
EbicsSecurityMediumState

Remarks

This property may be read in any state and at any time, even when no security token is present.

SupportedSecurityCodes

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

Declaration

EbicsSecurityCode SupportedSecurityCodes { get; }

Property Value

Type	Description
EbicsSecurityCode	A set of flags that indicates all the security processes that are implemented for this security media.

Remarks

The returned set includes all security processes that are supported by the implementation of this IEbicsSecurityMedium instance. There is no guarantee whether a particular physical security token really supports all the security processes indicated here. For example, a SECCOS implementation may support and indicate A004, A005 and A006, but a particular inserted SECCOS smart card may support A004 only.

In order to determine which security processes are really supported by a physical security token one must call GetPubKey(EbicsSecurityCode) for the desired security process. If this call successfully returns the public key information for the requested security process, then that security process is supported by the currently selected security token.

This property may be read in any state and at any time, even when no security token is present.

Methods

Authenticate(String)

Authenticate the selected security token for use.

Declaration

bool Authenticate(string sPIN)

Parameters

Type	Name	Description
System.String	sPIN	The security token PIN for authentication. This may be an empty string if no PIN is required. It must not be null.

Returns

Type	Description
System.Boolean	If authentication was successful, then true is returned. If not, then false is returned and LastError provides the details.

Remarks

In the SECCOS smart card based implementation this will authenticate the CSA Password of the smart card, only. The signature PIN is authenticated internally by the SignHash(EbicsSecurityCode, Byte[]) method, if needed.

This security medium must be in the Selected State when this method is called. When the method completes successfully, the security token has been switched into the Authenticated State. The authenticated state ends when the token is removed/disconnected or when the method Release() is called.

For secure PIN entry for smart cards the interface IEbicsSecurityMediumClass2 must be used, if it is supported.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter sPIN was null.
System.InvalidOperationException	This security medium instance is not in the Selected state.

ChangePIN(String, String)

Change the PIN (password) used to protect the security token.

Declaration

bool ChangePIN(string sOldPIN, string sNewPIN)

Parameters

Type	Name	Description
System.String	sOldPIN	The old PIN to be changed. Must not be null.
System.String	sNewPIN	The new PIN to be assigned. Must not be null.

Returns

Type	Description
System.Boolean	If the PIN was changed successfully, then true is returned. If not, then false is returned and LastError provides the details.

Remarks

This security medium must be in the Selected, State when this method is called. When the method returns, the security medium remains in the same state, regardless of success or failure.

For secure PIN change for smart cards the interface IEbicsSecurityMediumClass2 must be used, if it is supported.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter sOldPIN or sNewPIN was null.
System.InvalidOperationException	This security medium instance is not in the Selected state.

Create(String, String)

Creates a new software security medium.

Declaration

bool Create(string sSecurityMediaID, string sPIN)

Parameters

Type	Name	Description
System.String	sSecurityMediaID	Usually the path to the key file to be created. If so, this must not be null and must not be an empty string. This must be a valid file name of a non-existing file.
System.String	sPIN	The PIN to be assigned to the new file to be created.

Returns

Type	Description
System.Boolean	If the security token was successfully created, then true is returned. If creation failed, then false is returned and LastError provides more information.

Remarks

This method may only be called when this security medium is in the Null State. If the security token was successfully created, then it will be in the Authenticated State. thereafter.

Exceptions

Type	Condition
System.ArgumentNullException	The parameter sSecurityMediaID or sPIN was null.
System.ArgumentException	The parameter sSecurityMediaID was an empty string.
System.InvalidOperationException	There is already a selected file.

GetPasswordInfo()

Provides information about the password that must be passed to Authenticate(String).

Declaration

EbicsPasswordInfo GetPasswordInfo()

Returns

Type	Description
EbicsPasswordInfo

GetSecurityOperations(EbicsContact)

Get an implementation for the security operations bound to the key set for a particular contact.

Declaration

IEbicsSecurityOperations GetSecurityOperations(EbicsContact aContact)

Parameters

Type	Name	Description
EbicsContact	aContact	The EbicsContact that identifies the key set that shall be implicitly used with the returned security operations implementation. Implementations that only store a single key set may ignore this parameter.

Returns

Type	Description
IEbicsSecurityOperations

Release()

Releases a previously authenticated security token.

Declaration

void Release()

Remarks

This method shall end the authenticated state of the security token. Subsequently any calls to methods that require the authenticated state must fail. This method may be called in any state and at any time, even when no security token is present, and it must never fail.

Select(String)

Connect with existing security token.

Declaration

bool Select(string sSecurityMediaID)

Parameters

Type	Name	Description
System.String	sSecurityMediaID	Unique identification of the required token. Must not be null or an empty string.

Returns

Type	Description
System.Boolean	If a connection to the requested token could be established, then true is returned. If the token was not found, then false is returned and LastError provides more information.

Remarks

This method may only be called when this security medium is in the Null State. If the security token was successfully selected, then it will be in the Selected State.

Exceptions

Type	Condition
System.InvalidOperationException	This security medium instance is not in the Null state.