EBICS Hosts

Customers and Users

In the context of EBICS, a customer is defined as the organizational unit that concludes a contract with the bank, and a user is defined as a human or technical system that is assigned to a customer. Customers are often also referred to as partner, and users are often also referred to as subscriber. The customer/partner has a Partner ID to uniquely identify it, and the user/subscriber has a User ID. The customer-user combination is tied to a mailbox, and their associated IDs are specified on the EBICS mailbox: EBICS tab. See EBICS Mailbox. These IDs are sent with almost every initial request to the bank server.

Technical Subscribers

The EBICS specification explains the concept of technical subscribers. When requests are sent from a technical subscriber, the optional  <SystemID> element is defined. Technical subscribers do not exist in the context of the VersaLex EBICS client, therefore, the <SystemID> element will never be specified.

Bank-Customers Contracts

Initially, a contract is established between a bank and a customer. The contract includes details such as the orders the customer can issue, which accounts are accessible, and signing permission level.. All contractual details are outside of the EBICS specification and are therefore outside the scope of the VersaLex EBICS client. The management of these contractual details are maintained somewhere within the environment of the financial institution, and not within the VersaLex environment. Therefore, it is the responsibility of the financial institution to guard against unauthorized transactions. For example, if a certain VersaLex user is not authorized to issue a particular order, this transaction will ultimately be prevented when the bank server issues the appropriate return code (that is, EBICS_INVALID_USER_STATE) during the initialization phase of an order.

File-Based Transfers

All order data tranmissions are file-based. The VersaLex EBICS client, by default, ensures that all upload requests specify an HTTP header Content-Type name parameter corresponding to the original file name within the VersaLex file system. Conversely, it is anticipated that the bank server will provide a Content-Type "name" parameter or a Content-Disposition "filename" parameter within the returned HTTP headers for all download requests. While this is anticipated, it is not required for download orders. See Inbound File Names.

Data Segmentation and Checkpoint Restart

Signatures

EBICS calls for multiple levels of signatures. Almost every message request and response carries a signature; this signature is wrapped within the <AuthSignature> element and it uses the XML Signature methodology. This is referred to as the identification and authentication signature, and it is required for almost every EBICS request and response. In addition to the identification and authentication signature, a so-called electronic signature (abbreviated as ES) can also be present on an EBICS upload request. This signature is embodied within the <UserSignatureData> element. The ES signs the payload and the identification and authentication signature signs overall EBICS packages.

Order Attributes

The EBICS specification requires the <OrderAttribute> element on most EBICS requests. See the table below. To learn more, see the EBICS specification at www.ebics.org .

The <OrderAttribute> element is 5-character field. The setting for each character is as follows:

Security Media For Private Keys

The EBICS specification defines the following codes for identification of the medium for storage of private keys.

Inbound File Names

Inbound files can be received via a GET command or via one of the ancillary orders executed through the EBICS mailbox: EBICS tab (using Execute Ancillary Order or Download Bank Keys). See EBICS Mailbox.

The general order of precedence is as follows:

1. If a "destination" name is specified on the GET command, it is used.
2. Otherwise, the Default File Name setting from the EBICS Host: EBICS tab is used. See EBICS Host

Within the destination string of a GET command or within the Default File Name, source file macros (e.g., %sourcefile%) can be used to build the final destination name. When a macro is used, if the Content-Disposition "filename" or the Content-Type "name" is specified on the inbound response from the bank server, then it is used to resolve the macro. If both parameters are specified, then Content-Disposition takes precedence. Conversely, if neither parameter is specified, then the generic string, "receive.file", is used for the macro substitution.

After the inbound file name is determined, the following will determine its final name. These steps are different for files associated with a GET command and for files associated with an ancillary or key download.

If a file is associated with a GET command:

• if -UNI is specified on the command, and the file already exists, the name will be made unique (e.g., changing FDL.xml to FDL1.xml) to avoid overwriting the file.
• if -APE is specified on the command, the file will be appended to if it already exists.
• if neither -UNI nor -APE are specified, and the file already exists, it will be overwritten.

If a file is associated with an ancillary or key download:

• if the file already exists, the name will be made unique (e.g., changing HTD.xml to HTD1.xml) to avoid overwriting the file.

Key Management

The EBICS specification defines several provisions and order types associated with the exchange of public keys.  Three sets of public-private keys are defined for EBICS application-level encryption and signing. They are:

1. key pair for encryption
2. key pair for identification and authentication signature
3. key pair for electronic signature (ES)

According to the specification, key pairs 1 and 2 can be the same pair, but key pair 3 must be unique. The bank server will respond with appropriate error codes if this requirement is not met.

SSL/TLS Keys

In addition to the keys used at the application-level, there is a public-private key pair for TLS-level encryption.  The EBICS specification makes no restrictions as to whether or not this key pair may coincide with one of the application-level keys.

Key Exchange

When a user is first created, the bank will classify the user as New. Prior to conducting transactions, the user must be classified as Ready. The Ready state means that the bank has all the information necessary for the user to start submission of orders, including bank's download keys. To achieve the Ready state, the bank requires the receipt of certain keys. Know the requirements of your banking partner in order to provide the necessary keys according to the prescribed methods.

The transfer of keys from the client to the server and from the server to the client is referred to as key exchange and is supported through the EBICS mailbox: EBICS tab. See EBICS Mailbox. Under EBICS, provisions have been made for key exchange through certain order types defined within the specification. The key exchange order types implemented through the VersaLex EBICS client are:

Upload:

• INI - Upload ES key
• HIA - Upload signing and encryption keys
• H3K - Upload signing, encryption, and ES keys
• PUB - Update ES key
• HCA - Update signing and encryption keys
• HCS - Update signing, encryption, and ES keys

Download:

• HPB - Download signing and encryption keys

The EBICS specification also calls for hardcopy "initialisation letters" through which a secondary submission of key information is passed. The VersaLex EBICS client also provides functions to produce these letters.

EBICS Client Order Types