11.3. EBICS Implementation Notes¶
Warning
This document summarizes and clarifies some aspects of the EBICS protocol that are important to LibEuFin. Both version 3.0 and 2.5 are discussed here.
It is not a specification, and it does not replace the official EBICS specification.
11.3.1. EBICS Glossary¶
- A004¶
Electronic signature process, used in H004, deprecated in H005 with EBICS 3.0.
- A005¶
- A006¶
- BTF¶
Business Transaction Formats. Before EBICS 3.0, many different order types were used for business-related messages. With EBICS 3.0, the more generic BTU and BTD order types are used for all business-related messages.
- E002¶
EBICS encryption process, used to encrypt the order payload.
- EBICS¶
The Electronic Banking Internet Communication Standard.
- EDS¶
Distributed Electronic Signature. Allows multiple subscribers to authorize an existing order.
- ES¶
Electronic Signature. This abbreviation is commonly used in the context of EBICS.
The following signature classes are defined (in descending order from strongest to weakest):
- E
Single signature (German “Einzeln”).
- A
First signature.
- B
Second signature.
- T
Transport signature. Only used to verify authorized submission, but not to verify the bank-technical authorization.
In H004 and H005, the ES of the bank is specified as a “planned feature” that is not actually implemented yet. Thus banks in practice only use their encryption key pair and authentication/identity key pair.
- FTAM¶
Historical predecessor protocol to EBICS (file transfer, access and management).
- H004¶
Host protocol version 4. Refers to the XML Schema defined in EBICS 2.5.
- H005¶
Host protocol version 5. Refers to the XML Schema defined in EBICS 3.0.
- HEV¶
The Host EBICS Version. Queried by the client with an HEV request message.
- Host ID¶
Alphanumeric identifier for the EBICS Host. One EBICS server can host multiple banks, and each bank is identified by the Host ID. This concept is similar to Taler’s merchant backend instance identifiers.
- Human Subscriber¶
See Subscriber.
- ISO 20022¶
ISO 20022: Financial Services - Universal financial industry message scheme. Rather important standard for financial industry business-related messages. In contrast, EBICS takes care of message transmission, segmentation, authentication, key management, etc.
The full catalogue of messages is available gratis.
- Order Number¶
Interchangeably called “Order ID”.
Each upload transaction gets a unique order number assigned by the bank server. The Order Number is used to match VEUs in a second upload to the original order. An Order Number matches the format
[A-Z][A-Z0-9]{3}
(and is not really a number!).Must be unique per customer ID and per order type.
- Partner ID¶
In German, this is called “Kunden ID” (= Customer ID). One partner can have multiple “participants”, which are identified by user IDs.
Practical example: A company has one Partner ID. Each person at the company that can access the company’s bank accounts gets their own User ID. When the person is indirectly accessing the bank server (for example via a client server application), an additional “System ID” is created for this “technical subscriber”. When there is no technical subscriber, the System ID must be the same as the User ID. Usually the System ID is optional though.
The
(partner, user, system)
triple uniquely identifies a subscriber.- Segmentation¶
EBICS implements its own protocol-level segmentation of business-related messages. The segmentation can be seen as an alternative to the HTTP facilities of
Accept-Ranges
.The order data of an EBICS message may not exceed 1 MB. The segmentation applies both to requests and responses.
- Subscriber¶
Entity that wishes to communicate with the financial institution via EBICS.
Subscribers can be technical or human. Technical subscribers are typically a server in client-server applications, where the server talks to a financial institution via EBICS.
Requests from technical subscribers have a
SystemID
in addition to aPartnerID
andUserId
. A technical subscriber cannot sign a bank-technical request.- System ID¶
See Partner ID.
- Technical Subscriber¶
See Subscriber.
- TLS¶
Transport Layer Security. All messages in EBICS are sent over HTTP with TLS. In the current version of the standard, only server certificates are required.
- Transaction ID¶
A transaction ID is a 128-bit cryptographically strong random number. It is assigned by the bank server for every transaction, i.e. upload or download of an order.
The transaction ID must not be guessable, as it would allow a potential attacker to upload segments of an upload that do not match the whole message’s digest.
- Transaction key¶
Symmetric encryption key for the data uploaded/downloaded in a transaction.
- UNIFI¶
UNIversal Financial Industry message scheme. Sometimes used to refer to ISO 20022.
- User ID¶
See Partner ID.
- V001¶
FTAM encryption algorithm (“Verschlüsselung”), superseded in EBICS by E002.
- VEU¶
Distributed Electronic Signature (from German “Verteilte Elektronische Unterschrift”).
- X002¶
Identification and authentication signature in H004 and H005.
11.3.2. Order Types¶
By convention, order types beginning with “H” are administrative order types, and other ones are bank-technical order types. This convention isn’t always followed consistently by EBICS.
11.3.2.1. Relevant Order Types¶
- BTD¶
Only EBICS3.0+. Business Transaction Format Download. Administrative order type to download a file, described in more detail by the BTF structure.
- BTU¶
Only EBICS3.0+. Business Transaction Format Upload. Administrative order type to upload a file, described in more detail by the BTF structure.
- C52¶
Before EBICS 3.0. Download bank-to-customer account report (intra-day information).
- C53¶
Before EBICS 3.0. Download bank-to-customer statement report (prior day bank statement).
- CCC¶
Type: Upload.
Send SEPA Credit Transfer Initiation (pain.001) via XML container. This is the DFÜ variant (Appendix 3 DFÜ-Agreement).
- CCT¶
Type: Upload.
Send SEPA Credit Transfer Initiation (pain.001) directly. This is the DFÜ variant (Appendix 3 DFÜ-Agreement).
- CIZ¶
Type: Download.
Payment Status Report for Credit Transfer Instant.
- CRZ¶
Type: Download.
Fetch payment status report (pain.002).
- FDL¶
Before EBICS 3.0, France. File Download. Mainly used by France-style EBICS.
- FUL¶
Before EBICS 3.0, France. File Upload. Mainly used by France-style EBICS.
- HAA¶
Type: Download, Optional.
Download order types for which there is new data available.
- HAC¶
Customer acknowledgement. Allows downloading a detailed “log” of the activities done via EBICS, in the pain.002 XML format.
- HCS¶
Change keys without having to send a new INI/HIA letter.
- HCS¶
Change the subscribers keys (
K_SIG
,K_IA
andK_ENC
).- HIA¶
Transmission of the subscriber keys for (1) identification and authentication and (2) encryption within the framework of subscriber initialisation.
- HKD¶
Type: Download, Optional.
Download information about a customer (=partner). From German “Kundendaten”.
- HPB¶
Query the three RSA keys of the financial institute.
- HPD¶
Host Parameter Data. Used to query the capabilities of the financial institution.
- HTD¶
Type: Download.
Download information about a subscriber. From German “Teilnehmerdaten”.
- INI¶
Transmission of the subscriber keys for bank-technical electronic signatures.
- SPR¶
From German “sperren”. Suspend a subscriber. Used when a key compromise is suspected.
11.3.2.2. Other Order Types¶
The following order types are, for now, not relevant for LibEuFin:
- AZV¶
Type: Upload.
From German “Auslandszahlungsverkehr”. Used to submit cross-border payments in a legacy format.
- CCU¶
Type: Upload.
German “Eilüberweisung”.
- CDZ¶
Type: Download.
Download payment status report for direct debit.
- H3K¶
Type: Upload.
Send all three RSA key pairs for initialization at once, accompanied by a CA certificate for the keys. This is (as far as we know) used in France, but not used by any German banks. When initializing a subscriber with H3K, no INI and HIA letters are required.
- HCA¶
Type: Upload.
Change the identification and authentication key as well as the encryption key (
K_IA
andK_ENC
). Superseded by HCS.- HSA¶
Type: Optional
Order to migrate from FTAM to EBICS. Removed in EBICS 3.0.
- HVD¶
Type: Download.
Retrieve VEU state.
- HVE¶
Type: Upload.
Host Verification of Electronic Signature. Used to submit an electronic signature separately from a previously uploaded order.
- HVS¶
Type: Upload.
Cancel Previous Order (from German “Storno”). Used to submit an electronic signature separately from a previously uploaded order.
- HVU¶
Type: Download.
Retrieve VEU overview.
- HVU¶
Type: Download.
Retrieve VEU extra information. From German “Zusatzinformationen”.
- PTK¶
Type: Download.
Download a human-readable protocol of operations done via EBICS. Mandatory for German banks. Superseded by the machine-readable HAC order type.
- PUB¶
Type: Upload.
Change of the bank-technical key (
K_SIG
). Superseded by HSA.
11.3.3. EBICS Message Format¶
The following elements are the allowed root elements of EBICS request/response messages:
ebicsHEVRequest
/ebicsHEVResponse
: Always unauthenticated and unencrypted. Used only for query/response of the host’s EBICS version.ebicsUnsecuredRequest
: Request without signature or encryption (beyond TLS). Used for INI and HIA.ebicsKeyManagementResponse
: Unauthenticated response. Used for key management responses and sometimes also to deliver error messages that are not signed by the bank (such as “invalid request”).ebicsNoPubKeyDigestsRequest
: Signed request that does not contain the hash of the bank’s public key that the client expects. Used for key management, specifically only the HPB order type.ebicsRequest
/ebicsResponse
ebicsUnsignedRequest
: Not used anymore. Was used in FTAM migration with the HSA order type.
11.3.4. Order ID Allocation¶
In practice, the Order ID seems to be allocated via number of counters at the level of the PartnerID.
11.3.5. EBICS Transaction¶
A transaction in EBICS simply refers to the process of uploading or downloading a file. Whether it is an upload or download transaction depends on the order type. Each transaction is either an upload transaction or a download transaction, neither both.
Uploads and downloads must proceed in segments of at most 1 MB
. The
segmentation happens after (1) encryption, (2) zipping, and (3) base64-encoding
of the order data.
The number of segments is always fixed starting from the first message sent (for uploads) or received (for downloads) by the subscriber. The digest of the whole message is also sent/received with the first message of a transaction. The EBICS host generates a 128-bit transaction ID. This ID is used to correlate uploads/downloads of segments for the same transaction.
If an attacker would be able to guess the transaction ID, they could upload a bogus segment. This would only be detected after the whole file has been transmitted.
An upload transaction is finished when the subscriber has sent the last segment. A download transaction is only finished when the subscriber has sent an additional acknowledgement message to the EBICS host.
When upload/download of a segment fails, the client can always re-try. There are some conditions for that:
Segment
n
can only be downloaded/uploaded when segments[0..n-1]
have been downloaded/uploaded.The (implementation-defined) retry limit may not be exceeded.
11.3.6. Formats¶
11.3.6.1. ISO 20022¶
ISO 20022 is XML-based and defines the message format for many finance-related activities.
ISO 20022 messages are identified by a message identifier in the following format:
<business area> . <message identifier> . <variant> . <version>
Some financial instututions (such as the Deutsche Kreditwirtschaft) have decided to use
a subset of elements/attributes in a message, this is what the <variant>
part is for.
“Standard” ISO20022 have variant 001
.
The most important message types for LibEuFin are:
- camt - Cash Management
Particularly camt.053 (BankToCustomerStatement)
- pain - Payment Initiation
Particularly pain.001 (CustomerCreditTransferInitiation) to initiate a payment and pain.002 (CustomerPaymentStatus) to get the status of a payment.
11.3.7. SWIFT Proprietary¶
SWIFT Proprietary messages are in a custom textual format. The relevant messages are MT940 and MT942.
MT940 contains pre-advice, in the sense that transactions in it might still change or be reversed.
MT942 contains the settled transactions by the end of the day.
SWIFT will eventually transition from MT messages to ISO20022, but some banks might still only give us account statements in the old SWIFT format.
11.3.8. Key Management¶
RSA key pairs are used for three purposes:
Authorization of requests by signing the order data. Called the bank-technical key pair, abbreviated here as
K_SIG
.Identification/authentication of the subscriber. Called the identification and authentication key pair, abbreviated here as
K_IA
.Decryption of the symmetric key used to decrypt the bank’s response. Called the encryption key pair, abbreviated here as
K_ENC
.
One subscriber may use three different key pairs for these purposes. The identification and authentication key pair may be the same as the encryption key pair. The bank-technical key pair may not be used for any other purpose.
11.3.9. Real-time Transactions¶
Real-time transactions will be supported with EBICS starting November 2019. That’s the earliest date, some banks may offer it later or not at all.
For us, CIZ is the relevant order type that we need to ask banks for.
11.3.10. Payment Reversal¶
It looks like there is no way to “reject” payments, unless you are the bank.
There is a concept of payment reversal (with pain.007
for direct debit and camt.055
for SEPA Credit Transfer),
but they are a way for the payer / sender to reverse a payment before it is finalized.
11.3.11. Bank Support¶
All German banks that are part of the Deutsche Kreditwirtschaft must support EBICS.
The exact subset of EBICS order types must be agreed on contractually by the bank and customer. The following subsections list the message types that we know are supported by particular banks.
11.3.11.1. GLS Bank¶
According to publicly available forms, GLS Bank supports the following order types:
11.3.11.2. Sparkasse München¶
See this document.
11.3.11.3. HypoVereinsbank¶
See this document.
11.3.12. Cryptography¶
EBICS uses the XML Signature standard for signatures. It does not use XML encryption.
The EBICS specification doesn’t directly reference the standardized URIs for the various signing algorithms. Some of these URIs are defined in RFC 6931.
A005 is http://www.w3.org/2001/04/xmldsig-more#rsa-sha256.
The
RSASSA-PKCS1-v1_5
signature scheme contains theEMSA-PKCS1-v1_5
encoding scheme mentioned in the EBICS spec.
A006 is http://www.w3.org/2007/05/xmldsig-more#rsa-pss as defined in RFC 6931.
11.3.12.1. XML Signatures¶
XML Signatures can be a combination of:
detached (referencing another document)
enveloping (signs over
Object
tags within theSignature
elements)enveloped (signs over arbitrary data (via XPath expression) in other parts of the document that contains the signature).
In EBICS, only enveloped signatures are used.
In the XML Signature standard, the element for a signature is Signature
. EBICS violates this
standard by always mandating AuthSignature
as the name. AuthSignature
is an alias to
the SignatureType
XSD type in the XML Schema.
- Canonicalization vs transforms:
Canonicalization refers to the processing of the
SignedInfo
element.Transformations apply to the data that
Reference
elements reference. Canonicalization algorithms can be used as a transformation on referenced data.
11.3.13. Standards and Resources¶
11.3.13.1. EBICS¶
The EBICS standard documents are available at http://www.ebics.org.
EBICS 3.0:
The main EBICS 3.0 specification (
2017-03-29-EBICS_V_3.0-FinalVersion.pdf
).Annex 1 specifies EBICS return codes, as EBICS doesn’t use HTTP status codes directly (
2017-03-29-EBICS_V_3.0_Annex1_ReturnCodes-FinalVersion.pdf
) .Annex BTF contains the registry of BTF codes.
11.3.13.2. DFÜ Agreement¶
The DFÜ Agreement is the set of standards used by the German Banking Industry Committee (Deutsche Kreditwirtschaft).
The following Annexes (also see the DK Website) are relevant for implementing EBICS:
Annex 1 is the EBICS specification
(Annex 2 is deprecated)
Annex 3 describes the data formats used by German banks within EBICS.
11.3.13.3. EBICS Compendium¶
The EBICS Compendium has some additional info on EBICS. It is published by a company that sells a proprietary EBICS server implementation.