Axway EBICS Gateway Administrator Guide

EBICS GatewayVersion 3.1.028 February 2018

Administrator Guide

Copyright © 2018 Axway

All rights reserved.

This documentation describes the following Axway software:

Axway EBICS Gateway 3.1.0

No part of this publication may be reproduced, transmitted, stored in a retrieval system, or translated into any human or computer language, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without the prior written permission of the copyright owner, Axway.

This document, provided for informational purposes only, may be subject to significant modification. The descriptions and information in this document may not necessarily accurately represent or reflect the current or planned functions of this product. Axway may change this publication, the product described herein, or both. These changes will be incorporated in new versions of this document. Axway does not warrant that this document is error free.

Axway recognizes the rights of the holders of all trademarks used in its publications.

The documentation may provide hyperlinks to third-party web sites or access to third-party content. Links and access to these sites are provided for your convenience only. Axway does not control, endorse or guarantee content found in such sites. Axway is not responsible for any content, associated links, resources or services associated with a third-party site.

Axway shall not be liable for any loss or damage of any sort associated with your use of third-party content.

Contents

Preface 8

Who should read this guide 8

EBICS Gateway documentation set 8

Related documentation 8

Support services 9

Training services 9

Accessibility 10

Documentation accessibility 10

Screen reader support 10

Support for high contrast and accessible use of colors 10

What's new 11

Product enhancements 11

EBICS Gateway 3.1.0 11

Documentation enhancements 12

Recent additions to the Administrator Guide 12

Recent corrections to the Administrator Guide 12

1 Overview 13

About EBICS Gateway 13

The EBICS standard 14

EBICS version 2.4 15

EBICS version 2.5 15

EBICS in Axway Financial Integration 16

Banks 16

Corporates 16

2 EBICS Gateway Client 17

Introduction 17

Administer EBICS Gateway Client 18

Command scripts 18

Start EBICS Gateway Client 19

Create an EBICS Gateway Client user in PassPort 19

Connect to the EBICS Gateway Client UI 19

Stop EBICS Gateway Client 20

Check the EBICS Gateway Client status 20

Configure EBICS Gateway Client partners 20

Create a Customer 21

AxwayEBICS Gateway 3.1.0 Administrator Guide 3

Create a Bank 21

Create a subscription 21

Initialize a subscription 22

Display the initialization letters 22

Retrieve Bank credentials 22

Suspend a subscription 23

Reset a subscription 23

Renew a subscription 24

How EBICS Gateway Client stores credentials in PassPort 25

Use EBICS Gateway Client with a DMZ proxy 25

About Secure Relay 25

Configure EBICS Gateway Client to use Secure Relay 26

EBICS Gateway Client TLS configuration 26

Modify inbound EBICS Gateway Client TLS configuration 26

Modify outbound EBICS Gateway Client TLS configuration 27

Configure Gateway connector 29

Configure Gateway for EBICS Gateway Client 29

Configure Gateway for Send and Fetch 30

Integrate Sentinel with EBICS Gateway Client and Gateway 34

Send and Fetch transactions with EBICS Gateway Client 37

3 EBICS Gateway Server 41

Introduction 41

EBICS Gateway Server administration 41

Administer the standalone embedded application server 42

Run the standalone embedded application server as a Windows service 43

Administer EBICS Gateway Server on WebSphere 46

Administer the JBoss EAP application server (cluster configuration) 46

About the EBICS Gateway Server administration UI 48

Log on to the user interface 48

Description of the user interface screen 48

Modifying object content 48

Searching 49

Search results 49

Detail dialog 50

New entry 51

Set up EBICS Gateway Server 52

Bank objects 53

Change Processes menu item 57

Files 58

Account objects 61

Customer objects 63

Protocol objects 70

EBICS: Processing 71


Post-processing steps 86

Configure back-end connection with Gateway and Transfer CFT 88

Configuration examples 90

EBICS Gateway Server post-processing 92

About post-processing 92

Gateway post-processing 92

API Gateway (ActiveMQ) post-processing 95

File naming conventions 98

Restart post-processing 99

Manage administrator users 100

Permissions 100

Groups 100

Administrator (specific to EBICS Gateway Server) 105

EBICS security services via PassPort 106

Overview 106

Set up communication between EBICS Gateway Server and PassPort 106

Configure exchanges 107

Create a Technical user for EBICS Gateway Server in PassPort 107

Create Business users for EBICS in PassPort 110

Create a new bank with private and public keys 111

Create a new bank with imported certificates 113

Delete a bank and associated certificates 115

Create a customer 116

Delete a customer 117

Delete a user 118

Release user keys 118

Release user certificates 119

EBICS Gateway Server TLS configuration 120

Relax or restrict the security of TLS versions 120

Encrypt data at rest in EBICS Gateway Server 124

EBICS Gateway Server behavior on encryption 124

Interoperability with backend 125

How to set up encryption for test 125

How to set up encryption for production 128

Use EBICS Gateway Server with a DMZ proxy 131

About Secure Relay 131

Configure EBICS Gateway Server to use Secure Relay 131

EBICS Gateway Server tools 132

Supplier command line 132

Supplier service 135

Run the supplier as a Windows service 146

Injector 149

Purge command line 157

Configure WebSphere environment for EBICS Gateway Server tools 161


4 Monitoring EBICS Gateway processes 163

Introduction 163

XFBTRANSFER Sentinel Tracked Object 164

Transfer states 164

XFBTransfer attributes 166

EBICSINI Sentinel Tracked Object 169

EBICSINI processing state changes 169

EBICSINI attributes 170

HEARTBEAT Sentinel Tracked Object 171

HEARTBEAT attributes 171

Overflow file for Sentinel tracking 171

Configure Sentinel monitoring of EBICS Gateway Server 172

Prerequisites 172

Configuration tasks 172

Import Tracked Objects for EBICS Gateway Server monitoring 173

Set the environment variables 174

5 Troubleshooting 175

How to find the product version number 175

Troubleshoot EBICS Gateway Server 176

Cannot stop the embedded application server 176

Cannot stop the embedded application server on Windows Server 2008 176

Redeploy EBICS Gateway Server application (embedded application server) 179

Errors when deploying EBICS Gateway Server application 179

Log messages when deploying EBICS Gateway Server application on WebSphere 180

HibernateException message 180

Purge Send with zip does not create zip archive 181

Log files 182

Appendix A: Configuration files 183

EBICS Gateway Client configuration files 183

Overview of configuration files 183

database.properties 184

ebicsclient.properties 184

jetty-secure.xml 184

secureRelayConf.xml 185

security.properties 185

EBICS Gateway Server configuration file 187

Overview 187

Sentinel tracking configuration 188

Gateway link configuration 189

PassPort configuration 190

XML security properties 192

Configure exits 193


Advanced EBICS Gateway Server configuration 194


Preface

This guide describes how to administer the client mode and server mode of EBICS Gateway. The guide includes details of the different configuration files.

Who should read this guideThis guide is intended for administrators who integrate and manage EBICS Gateway in their production environment.

It is assumed that you have a good understanding of networks and Java environments.

EBICS Gateway documentation setTo find all available documents for this product version:

1. Go to https://docs.axway.com/bundle.

2. In the left pane Filters list, select your product or product version.

Note Customers with active support contracts need to log in to access restricted content.

Related documentationThe following reference documents are available on the Axway Documentation portal at https://docs.axway.com

l Axway Supported Platforms

Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product.

l Axway Interoperability Matrix

Provides product version and interoperability information for Axway products.


https://docs.axway.com/bundle

https://docs.axway.com/

https://docs.axway.com/bundle/Axway_Products_SupportedPlatforms_allOS_en

https://docs.axway.com/bundle/Axway_Products_InteroperabilityMatrix_allOS_en

Preface

Support servicesThe Axway Global Support team provides worldwide 24 x 7 support for customers with active support agreements.

Email [email protected] or visit Axway Support at https://support.axway.com.

See Troubleshooting on page 175 for the information that you should be prepared to provide when you contact Axway Support.

Training servicesAxway offers training across the globe, including on-site instructor-led classes and self-paced online learning. For details, go to: http://www.axway.com/support-services/training


mailto:[email protected]

https://support.axway.com/

http://www.axway.com/support-services/training

Accessibility

Axway strives to create accessible products and documentation for users. The following describes the accessibility features of the documentation.

Documentation accessibilityThe product documentation provides the following accessibility features:

l Screen reader support on page 10

l Support for high contrast and accessible use of colors on page 10

Screen reader support l Alternative text is provided for images whenever necessary.

l The PDF documents are tagged to provide a logical reading order.

Support for high contrast and accessible use of colors l The documentation can be used in high-contrast mode.

l There is sufficient contrast between the text and the background color.

l The graphics have the right level of contrast and take into account the way color-blind people perceive colors.


What's new

Product enhancements

EBICS Gateway 3.1.0 l Security

o TLS 1.2 enforcement: TLS 1.2 is the default TLS protocol for EBICS Gateway.

o TLS 1.2 is mandatory by default (but can be relaxed) for following connections:

o GUI (client and server)

o EBICS channel (client and server)

o Tools connection (server)

o PassPort connection (client and server)

o Many security improvements have been made following internal security audits

l EBICS Gateway Client

o Support of EBICS Renew feature

o Support of EBICS Suspend feature

o Support of Reset (suspend a subscription locally)

l EBICS Gateway Server

o Support of EAP for cluster configuration

o GUI, EBICS channel, and tools connections are on different ports and can be configured separately

o Incremental purge feature, to reduce resource consumption during heavy purges

o Injector, Supplier and Purge now show their version in the log at startup

o Supply is greatly improved (better concurrency handling and session optimization)

o Optional encryption of data at rest using XML encryption. When set:

o All files received from customers are stored encrypted on disk

o Axway Generic Fetch and Axway Generic ZIP Fetch handlers dynamically decrypt files supplied encrypted


What's new

For more information l EBICS Gateway Client TLS configuration on page 26

l Renew a subscription on page 24

l Suspend a subscription on page 23

l Reset a subscription on page 23

l Encrypt data at rest in EBICS Gateway Server on page 124

Documentation enhancementsThis release of EBICS Gateway includes the following documentation changes:

l Administrator Guide: Some sections of this document have been reorganized with the aim of improving the structure. This affects both EBICS Gateway Client and EBICS Gateway Server. Various corrections and improvements have been made throughout the document.

l Installation Guide: This document now includes upgrade information. Various corrections and improvements have been made throughout the document.

l Security Guide: This is a new document that provides instructions and recommendations to help you strengthen the security of EBICS Gateway.

Recent additions to the Administrator GuideExisting features (previously not documented):

l June 2016: Run the standalone embedded application server as a Windows service on page 43

l August 2016: EBICS Gateway Server TLS configuration on page 120, Relax or restrict the security of TLS versions on page 120

New features available from SP1 onwards:

l June 2016: Run the supplier as a Windows service on page 146

Recent corrections to the Administrator Guide l June 2017: Updated Create Business users for EBICS in PassPort on page 110. Removed the section "Restricting privileges to specific banks" which was not correct.


1 Overview

This chapter introduces Axway EBICS Gateway, Axway Financial Integration, and the EBICS standard.

About EBICS Gateway on page 13

The EBICS standard on page 14

EBICS in Axway Financial Integration on page 16

About EBICS GatewayEBICS Gateway is an Axway product used in the Financial Integration solution. It addresses the financial data flow concentrator use case. In this use case, EBICS Gateway is used by banks and their customers to exchange financial information, using two modes:

l Banks use the EBICS server mode to exchange payment flows with their customers

l Enterprises use the EBICS client mode to send payment files to their banks and get report details (payment status reports, payment notifications, account statements, and so on)

Banks and market infrastructures supporting EBICS use both the EBICS client and EBICS server modes for clearing and settlement exchanges.

An EBICS client sends requests to a remote EBICS server, which in turn responds to the client. The communication is always at the initiative of the client. The server never takes initiative and remains in the role of a responder. If the communication needs to be initiated by both parties, an EBICS client and an EBICS server need to be installed on both sides.


1 Overview

The following diagram shows EBICS Gateway in combination with other Axway products that can be used in the Financial Integration solution.

Figure 1. EBICS Gateway in combination with other Axway products in the Financial Integration solution

As illustrated in the diagram, EBICS Gateway inter-operates with Gateway and Integrator, using Secure Relay as a proxy in the DMZ.

Integrator can validate and transform the data, and Gateway can route the data from and to the backend.

The server mode uses API Gateway's JMS service to transfer data to Integrator or Gateway in a reliable way (compatible with a cluster configuration).

EBICS Gateway uses PassPort for access management and for the storage of keys and certificates.

Sentinel provides visibility of the data exchanges in the solution.

The EBICS standardEBICS stands for Electronic Banking Internet Communication Standard. It is a standard for electronic data interchange between corporates and banks. It is maintained and promoted by EBICS SCRL (www.ebics.org).

EBICS SCRL was created in 2010 by the Zentraler Kreditausschuss (ZKA) now known as Die Deutsche Kreditwirtschaft (DK) – the German Banking Industry Committee – and the Comité Français d'Organisation et de Normalisation Bancaires (CFONB) – the standardization office in the


http://www.ebics.org/

1 Overview

banking sector of France.

It is a communication standard for SEPA exchanges, not only between customers and banks but also between banks and Clearing & Settlement mechanisms (for example: between the German banks and the Bundesbank, or between the banks and the clearing house EBA-STEP2).

EBICS version 2.4EBICS version 2.4 offers technical solutions for certain French bank requirements, such as the enlargement of identification fields (customer ID, user ID and host ID) to 35 digits, as well as two new order types for uploading and downloading files. EBICS version 2.4 also describes the use of certificates.

EBICS version 2.5EBICS Gateway Server fully support version 2.5 of the EBICS protocol. For full details of the improvements provided by EBICS 2.5, refer to the official EBICS protocol specifications.

The most notable features of this protocol version are:

l Server-generated order numbers: At each send operation, the order number formerly generated by the client-side is now generated by the server and returned to the client at the end of the transfer.

l The support of the H3K technical order type. This new order type is used for the initialization (in a similar way to INI and HIA) but allows the sending of the three certificates in just one operation. In order for this to work properly, the H3K send order type must be created manually in the EBICS Gateway Server UI and the customers that are to use it must be allowed for this order type.

l Automatic release in the H3K case: When the H3K order type is used, the users are released automatically at the end of the initialization. This is different from the typical INI+HIA procedure that required a manual release in addition to the use of PDF letters and so on.


1 Overview

EBICS in Axway Financial IntegrationThe Axway Financial Integration solution provides a means to implement EBICS exchanges from the corporate side and the bank side of an exchange.

Figure 2. Axway Financial Integration can be used for EBICS exchanges by corporates and by banks

BanksFor banking entities, Financial Integration provides a dedicated EBICS Gateway Server module to handle the EBICS protocol. Working from a dedicated UI, you can define the partners, security parameters, file types, and so on, that define the exchange agreements with your corporate clients.

You can define multiple instances of your banking entity, and define a virtually unlimited number of remote corporate partners.

For end-to-end monitoring, Financial Integration includes the services of Sentinel.

Financial Integration can communicate with any fully standardized EBICS corporate client application.

CorporatesFor corporate entities, Financial Integration provides a dedicated EBICS Gateway Client module to handle the EBICS protocol.

Financial Integration enables you to be linked to your back-end applications for dispatching and receiving EBICS exchanges from a corporate environment.

For end-to-end monitoring, Financial Integration includes the services of Sentinel.

Financial Integration can communicate with any fully standardized EBICS banking server application.


2 EBICS Gateway Client

This chapter introduces EBICS Gateway Client and its administration.

Introduction on page 17

Administer EBICS Gateway Client on page 18

Configure EBICS Gateway Client partners on page 20

Use EBICS Gateway Client with a DMZ proxy on page 25

EBICS Gateway Client TLS configuration on page 26

Configure Gateway connector on page 29

Configure Gateway for Send and Fetch on page 30

Integrate Sentinel with EBICS Gateway Client and Gateway on page 34

Send and Fetch transactions with EBICS Gateway Client on page 37

For information about the EBICS Gateway Client configuration files, refer to EBICS Gateway Client configuration files on page 183.

IntroductionEBICS Gateway Client provides the support for the EBICS protocol in Gateway on the client side (typically in corporate entities).

This enhanced version of the EBICS Gateway Client is implemented as a single running process that handles all requests. This process must be launched to allow administration or transfers.


Administer EBICS Gateway Client

Command scriptsThe command scripts are located in <EBICS Gateway dir>/client/bin.

To control EBICS Gateway Client, run the script that corresponds to your OS:

OS script

UNIX admin_ebics_client.sh

Windows admin_ebics_client.cmd

When you run the script without any argument, EBICS Gateway Client displays the usage page.

The normal usage of the script is <script> <argument>.

Argument Action

start Start EBICS Gateway Client

status Display the status of EBICS Gateway Client (for example to check whether it is started)

stop Stop EBICS Gateway Client

restart Restart EBICS Gateway Client

Return codes l 0 – OK

l 1 – error


2 EBICS GatewayClient

Start EBICS Gateway Client

On UNIXRun the script admin_ebics_client.sh start located in the <EBICS Gateway dir>/client/bin directory.

On WindowsFrom the Windows Start menu, select Start EBICS Client.

Create an EBICS Gateway Client user in PassPortTo use EBICS Gateway Client you need to have a user correctly set up in PassPort.

Before creating a user in PassPort you need to start EBICS Gateway Client at least once because it needs to register product and role information with PassPort.

Then, in PassPort, create a user on your domain and give it the Administration role on the EBICS Gateway Client product. Refer to the Axway PassPort documentation for more details about this procedure.

Now you can log in to EBICS Gateway Client.

Connect to the EBICS Gateway Client UI 1. From the Windows Start menu, select EBICS Client UI.

The EBICS Gateway Client UI opens.

2. Log in using the administrator account that was created during installation.



Stop EBICS Gateway Client

On UNIXRun the script admin_ebics_client.sh stop.

On WindowsRun the script admin_ebics_client.bat stop.

Check the EBICS Gateway Client status

On UNIXRun the script admin_ebics_client.sh status.

On WindowsRun the script admin_ebics_client.bat status.

Configure EBICS Gateway Client partnersThe EBICS protocol allows the exchange of files between parties securely over the Internet. Before exchanges can take place between two parties, a relationship should be created that also contains all the protocol parameters. This relationship must exist and be validated by both parties before any business interaction can happen.

In EBICS Gateway Client terminology this relationship is called a subscription. This section explains how to set up a subscription.

Naming convention: EBICS Gateway Client adapts to your business usage. At installation time, you can choose the naming of the local parties and remote parties. To simplify, in this section, we assume that you chose to name local party=Customer and remote party=Bank.



Create a CustomerThe Customer is your side of the subscription.

To create a Customer, click the Add Customer button in the Customers list. Provide a name that identifies this Customer.

Create a BankThe Bank is the remote side of the subscription. You need to perform this step with the information provided by the bank.

To create a Bank, click the Add Bank button in the Banks list. Provide a name that identifies this Bank and its URL. The URL is the address of the EBICS server hosted by the bank.

After you have created the Bank, you need to retrieve its TLS certificate. This is a required step to be able to securely communicate with the bank. This step is to be done when the Bank is first created or in the event that the Bank changes its TLS certificate.

Open the Bank you have created from the Banks list and click Retrieve SSL certificate on the right-hand side. After this is completed you will see the TLS certificate file name displayed in the CREDENTIALS section of the Bank page.

Create a subscriptionNow that you have created a Customer and a Bank, you can create a subscription that binds them together. You need to perform this step with the information provided by the bank.

Navigate to the Subscriptions list and click Add subscription. Enter the details and save the subscription.

Before you can initialize a subscription, you need to select three credentials:

l A signature credential – used to certify that the transfer is approved by the owner of the subscription. If it is a certificate, it needs to have the NON_REPUDIATION key usage.

l An authentication credential – used to authenticate the sender of the EBICS message. If it is a certificate, it needs to have the DIGITAL_SIGNATURE key usage.

l An encryption credential – used for the encryption of the EBICS message. If it is a certificate, it needs to have the KEY_ENCIPHERMENT key usage or KEYAGREEMENT and the SubjectDN equals to the IssuerDN.

The credential list box shows the credentials currently available inside PassPort and compatible with the current usage.

If you do not find the credential you need, you can easily generate one by clicking the Generate credential link next to the credential list box, or you can import it inside PassPort (see How EBICS Gateway Client stores credentials in PassPort on page 25).



The authentication credential generated for authentication or encryption is valid for both usages (the generated certificate has both KEY_ENCIPHERMENT and DIGITAL_SIGNATURE key usages). So you can use it for authentication and encryption.

Sets of authentication and encryption credentials can be shared by all subscriptions of a given customer, because they identify a customer rather than a subscription. The only credential that identifies a subscription, or more precisely the owner of the subscription (subscriber or user), is the signature credential. So this signature must be unique per subscriber.

Initialize a subscriptionBefore being able to communicate with the bank, the subscription needs to be initialized.

Open the subscription and click the Initialize subscription link on the right panel. After this is completed the status of the subscription changes to INITIALIZED and you will be able to generate the initialization letters.

Display the initialization lettersIf you have generated credentials for the subscription, you usually need to send the details of these credentials to the bank. This is the purpose of the initialization letters.

To retrieve the letters, open the subscription and click Display initialization letters on the right panel.

Send the letters by mail or any other mean to the bank's EBICS administrator, so that he can double-check the validity of the credentials that were sent during the initialization phase. He will then be able to release the subscription (or user) on the bank side.

Retrieve Bank credentialsOne final step to carry out after the subscription has been initialized is to retrieve the Bank credentials.

Go to the Bank view on the right panel and click the Retrieve bank credentials link.

The credentials for the Bank will be stored in PassPort. The name of the entity follows the convention described in How EBICS Gateway Client stores credentials in PassPort on page 25.

After this action has been completed you will see the Bank's credentials in the CREDENTIALS section of the Bank view.

Now you are ready to exchange files with that bank.

Note You only need to retrieve the bank credentials once, or after a change of bank credentials. There is no need to follow this step after each initialization.



Suspend a subscriptionIn some cases you might want to suspend a subscription to stop all possible communication between the remote and local parties of the subscription concerned. This could be for any reason, for example if there is a problem with a certificate.

You can suspend any subscription that currently has the INITIALIZED state.

When a subscription is suspended, the communication between EBICS Gateway Server and EBICS Gateway Client is no longer available.

l Click the Suspend subscription link.

EBICS Gateway Client sends a message to EBICS Gateway Server to lock the user of the subscription.

If the suspend operation is successful:

l On the server side the subscription is locked (user channel in LOCKED state if remote server is an EBICS Gateway Server).

l On the EBICS Gateway Client side, the subscription has the SUSPENDED state and no more credentials are set (Signature/Authentication/Encryption credentials are empty).

If an error occurs:

l An error message is displayed, and no modification is made to the subscription.

A suspended subscription has the same behavior as a new subscription. You can:

l Edit the subscription, and modify all fields

l Initialize the subscription

l Remove the subscription

To reactivate a suspended subscription you should make any required changes to the credentials and save the changes. You can then initialize the subscription again.

Reset a subscriptionIf you cannot suspend a subscription (because the signature key is lost or broken, or communication with the remote party fails), you can still reset the subscription to disable it.

The reset action is different from the suspend function in that it is local. It will disable the subscription in the EBICS Gateway Client, without sending any EBICS message to the server. This means that you will need to contact the remote EBICS server administrator and ask him to reset the subscription on the server side in order to keep the subscription synchronized on both sides.

Even if reset is primarily intended to disable initialized subscriptions that cannot be suspended, you can reset subscriptions that are in any state. This allows you to do a cleanup of the subscription:

l Put it in NEW state

l Reset the credentials. Note that they are just removed from the subscription, but stay available in PassPort for reference or reuse



Reset procedure 1. To reset a subscription, open the subscription and click the Reset link that appears on the right

panel (in read mode).

You will be prompted with a confirmation message.

2. If you confirm, the subscription will be reset.

After a subscription has been reset:

l It can no longer be used for transfers

l It can be re-initialized, after setting new credentials (and after making sure the subscription is in a compatible state on the server side)

Renew a subscriptionThe Renew subscription function enables you to easily update the credentials (certificates or keys) of a subscription without having to reinitialize it. Use this function to update compromised or outdated credentials. For certificates, you must do this before the old one expires.

When you add new credentials they are considered as pending until you replace the existing ones using the Renew function.

Prerequisites l The subscription is in INITIALIZED state.

ProcedureTo renew a subscription:

1. Open the subscription and click Edit.

2. In CREDENTIALS, add pending credentials, such as a signature.

3. Save the changes.

4. Click Renew subscription credentials on the right panel.

The new credentials are sent to the remote party (for example, the bank). The active credentials are replaced by the pending credentials.



How EBICS Gateway Client stores credentials in PassPortFor any party created in EBICS Gateway Client, entities are created in PassPort to store credentials.

Credentials are either cryptographic keys or certificates.

The entities are named according to the following convention:

{containerPrefix}:{componentInstance}:{containerType}:{containerUsage}:{partyName}

l containerPrefix is the container prefix as defined in the security.property

configuration file.

l componentInstance is the component instance as defined in the

security.property configuration file.

l containerType defines the type of container – either LOCAL for a Customer or REMOTE for

a Bank.

l containerUsage defines the type of container usage – either SIGNING for signing

credentials or TRANSPORT for encryption and authentication credentials.

l partyName is the name of the party – either the name of the Customer or the Bank depending

on the value of containerType.

Use EBICS Gateway Client with a DMZ proxyYou can install EBICS Gateway Client in a corporate network and use Axway Secure Relay in a DMZ in order to provide maximum security for your connections.

Figure 3. Secure Relay used as a DMZ proxy with EBICS Gateway Client

About Secure RelaySecure Relay is a software-driven proxy that consists of two components: a Router Agent, deployed in the DMZ, and a Master Agent, located in the corporate network. EBICS Gateway Client includes an embedded Master Agent. Secure Relay enables you to protect data, customers, and networks while enabling critical file transfer services between approved parties.

Secure Relay receives all configuration data directly from EBICS Gateway. All file transfer dialog (protocol, authentication, and so on) is handled by EBICS Gateway. This avoids any permanent or temporary storage of critical information in the DMZ, including files, configuration information (such as keys and certificates), and critical back-end processing (such as digital signing or envelope decryption).

For a detailed description of Secure Relay, refer to the Axway Secure Relay documentation.



Configure EBICS Gateway Client to use Secure RelayTo use this feature, your EBICS Gateway license file must include the Secure Relay option.

EBICS Gateway Client can be configured to use Secure Relay to go through a DMZ configuration. The Secure Relay configuration is global for the EBICS Gateway Client installation.

The use of Secure Relay is determined when you install EBICS Gateway. If Secure Relay was configured correctly during installation you do not need to take any other action. All outbound calls will pass automatically via Secure Relay.

Check the EBICS Gateway Client configuration files to see if it has been configured to use Secure Relay. For details, see EBICS Gateway Client configuration files on page 183.

If you want to modify any settings in the configuration files, for example to activate or deactivate the use of Secure Relay, use the Configure function of the installer. For details, refer to the EBICS Gateway Installation Guide.

EBICS Gateway Client TLS configurationAt installation time, EBICS Gateway Client is set to accept only TLS 1.2 connections, with safe cipher suites. This corresponds to today’s best practice, and offers you safe connections over the internet.

In some cases, for compatibility reasons, you might need to lower the HTTPS security level of EBICS Gateway Client.

Important:

l Be careful when modifying your configuration, as it can lead to weaker security.

l Any changes that you make will take effect after you restart EBICS Gateway Client.

Modify inbound EBICS Gateway Client TLS configuration on page 26

Modify outbound EBICS Gateway Client TLS configuration on page 27

Modify inbound EBICS Gateway Client TLS configurationThe inbound HTTPS connection (GUI and REST API) is controlled through the conf/jetty/jetty-secure.xml configuration file.

For information about the parameters in this file, see jetty-secure.xml on page 184.



You can modify the supported TLS/SSL protocols and cipher suites for the HTTPS connection by editing the conf/jetty/jetty-secure.xml file. At installation time, the file contains the following sections:

<Set name="ExcludeProtocols">

<Array type="String">

<Item>TLSv1</Item>

<Item>TLSv1.1</Item>

<Item>SSLv3</Item>

</Array>

</Set>

<Set name="IncludeCipherSuites">

<Array type="String">

<item>TLS_RSA_WITH_AES_256_CBC_SHA256</item>

<item>TLS_RSA_WITH_AES_256_CBC_SHA</item>

<item>TLS_RSA_WITH_AES_128_CBC_SHA256</item>

<Item>TLS_RSA_WITH_AES_128_CBC_SHA</Item>

</Array>

</Set>

Exclude protocols

The ExcludeProtocols section indicates the HTTPS protocols that are forbidden (note that protocols below SSLv3 are no longer handled by Jetty). By default, the only non-excluded protocol is TLSv1.2, making it the only one authorized.

If you want to open the connection to another protocol, remove the corresponding item from the list.

Include cipher suites

The IncludeCipherSuites section indicates which cipher suites are allowed. The cipher suites are ordered by preference, with the preferred choice at the top.

You can remove or add cipher suite item(s) as required (as long as they are handled by Jetty).

Modify outbound EBICS Gateway Client TLS configurationThe outbound HTTPS connection (EBICS channel) is controlled through the conf/security/security.properties configuration file.

For information about the parameters in this file, see security.properties on page 185.

You can modify the supported TLS/SSL protocols and cipher suites for the HTTPS connection by editing the conf/security/security.properties file. At installation time, the file contains the following lines:

# Defines the supported SSL/TLS protocols for the (EBICS protocol



outbound) https connection.

https.supportedProtocols=TLSv1.2

# Defines the supported cipher suites (for the EBICS protocol outbound)

https.supportedCipherSuites=TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_

WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_

128_CBC_SHA

https.supportedProtocols

The https.supportedProtocols parameter indicates the supported TLS/SSL protocols for the HTTPS connection used for EBICS communications. By default, the only specified protocol is TLSv1.2, making it the only one authorized.

If you want to open the connection to another protocol, add the corresponding item to the list. Use a comma to separate multiple values.

https.supportedCipherSuites

The https.supportedCipherSuites parameter indicates which cipher suites are supported for the HTTPS connection used for EBICS communications.

You can remove or add cipher suite item(s) as required. Use a comma to separate multiple values.



Configure Gateway connectorThis section describes how to set up the connectivity between Axway Gateway and EBICS Gateway Client.

Configure Gateway for EBICS Gateway ClientAfter installing EBICS Gateway Client with Axway Gateway as communication layer, you have to configure Gateway in order to make the link with the back-end application.

Prerequisites l Axway Gateway is already installed.

l Gateway must be installed on the same machine as EBICS Gateway Client.

l If you want to monitor the transfers, Sentinel Universal Agent must be installed on the same machine as EBICS Gateway Client (to be able to track EBICS activity with Sentinel). In this case, network access to either a Sentinel Event Router or a Sentinel Server is also required.

Using Transfer CFT to connect to the back-end applicationThe EBICS Gateway Client installation package includes a set of sample files that enable you to link Gateway and EBICS Gateway Client to Transfer CFT to connect to the back-end application.

The sample files that are provided in the EBICS Gateway Client installation package enable you to:

l Automate a Send request (for example, to EBICS Gateway Server)

l Automate a scheduled Fetch and send result to a Transfer CFT monitor

l Automate a Fetch request and send the received file (for example, a PSR file) to a Transfer CFT monitor

This section describes a generic implementation. You should adapt it to your specific internal application requirements.

Behavior principles: User messageThe provided scripts are based on the User message parameter that can be used with the PeSIT or FTP protocols.



Send – User message syntax

<orderTypeBL>#<bankId>#<CustomerId>#<SystemId>#<userIdTransport>#<Payloa

dId>

where:

<orderTypeBL> is the full EBICS order type (for example FUL.pain.001.001.02.ict).

<bankId> is the EBICS HostId of the Bank.

<CustomerId> is the EBICS customerID.

<SystemId> is the EBICS userID of the user used as systemID (optional).

<userIdTransport> is the EBICS userID of the transport user.

<PayloadId> is the id of the payload, this parameter is mandatory.

Fetch – User message syntax

<orderTypeBL>#<EbicsBankHostID>#<CustomerId>#<userIdTransport>#<FromDate

>#<ToDate>

where:

<orderTypeBL>, <CustomerId> and <userIdTransport> are mandatory.

<FromDate> and <ToDate> are optional. They are defined in the format YYMMDD.

Optional parameters can be empty. Note however that all the # characters are still mandatory.

Configure Gateway for Send and FetchThis section explains how to configure Gateway to detect a Send or Fetch request and trigger the related action. Sample scripts are supplied that use Gateway and Transfer CFT.

IntroductionTo execute a Send or Fetch from a Transfer CFT client you require the following Gateway objects:

l Remote Site

l Application

l Local Site

l Model (only required for Fetch requests)

l Decision Rule



Configure Gateway

Configure Gateway using sample scriptsThe sample script obj_gateway_client_ebics[.sh|.bat] creates all the required objects with the link to the required scripts. However you first need to customize the script.

1. Navigate to the EBICS Gateway Client installation directory.

2. In the directory mft/install/client, locate the file obj_gateway_client_

ebics.sh (or .bat for Windows).

3. Open the file in a text editor, and modify the following parameters:

Parameter Modification

GTW_HOME Enter the path to the Gateway installation directory.

remote_cft_EBICS_client_address Enter the Transfer CFT Server HostName.

remote_cft_EBICS_client_port Enter the Transfer CFT Server port number.

orderType Enter a Fetch OrderType. For example, HPB.

bank EBICS Bank Host ID

CustomerId EBICS Customer ID

UserId EBICS User ID

From FROM Date YYMMDD

To TO Date YYMMDD

4. Save the file.

5. From the same directory, execute the script:

l UNIX: obj_gateway_client_ebics.sh

l Windows: obj_gateway_client_ebics.bat

To delete all objects, use the script delobj_gateway_client_ebics[.sh|.bat] if the object name was not changed inside obj_gateway_client_ebics[.sh|.bat].



Configure Gateway manuallyCreate the following Gateway objects:

Remote Site

This object is necessary only if you connect to Transfer CFT as a back-end application.

In Gateway Navigator, create a new Remote Site object.

Application

In Gateway Navigator, create an Application object that specifies the record size, depending on your transfer requirements. This application is used inside the Decision Rule to trigger the right script.

Local Site

This object is necessary only if you connect to Transfer CFT as a back-end application.

In Gateway Navigator, create a new Local Site object.

Model (only for Fetch)

In Gateway Navigator, create a Model to be included in the Decision Rule. This Model is used to send the fetched file back to a Transfer CFT monitor. By defining several Models and Decision Rules, you can access several Transfer CFT monitors.

Decision Rule - for Fetch

In Gateway Navigator, create a Decision Rule that points to one of the scripts:

l UNIX: EbicsFetchClient_GTW.sh

l Windows: EbicsFetchClient_GTW.bat

These scripts are located in the directory client\mft\Fetch

When you enter the script in the Gateway field, add the name of the Model to use and add one of the following parameters:

l test

l real

The test or real value sets the communication mode with EBICS Gateway Server.

Example on Windows:

EbicsFetchClient_GTW.bat ModelName test



Decision Rule - for Send

In Gateway Navigator, create a Decision Rule that points to one of the scripts:

l UNIX: EbicsSendClient_GTW.sh

l Windows: EbicsSendClient_GTW.bat

These scripts are located in the directory client\mft\Send

When you enter the script in the Gateway field, add one of the following parameters:

l test

l real

The test or real value sets the communication mode with EBICS Gateway Server.

Example on Windows:

EbicsSendClient_GTW.bat test

For more details about creating Gateway objects, refer to the Axway Gateway online documentation.

Configure Transfer CFTThe sample script cft_ebics_client.cfg creates the required objects on the Transfer CFT side.

1. Navigate to the EBICS Gateway Client installation directory.

2. In the directory client/mft/install/client locate the file cft_ebics_

client.cfg.

3. Open the file in a text editor, and modify the following parameters:

Parameter Modification

SYST Enter the type of platform.

Example values:

l 'WINNT'

l 'UNIX'

PROT Enter 'PESITANY'

SAP Enter '6330'

HOST Enter the Gateway HostName

4. Save the file.




l UNIX: CFTUTIL @cft_ebics_client.cfg

l Windows: CFTUTIL #cft_ebics_client.cfg

Integrate Sentinel with EBICS Gateway Client and GatewayThis section explains how to configure EBICS Gateway Client to send events to Sentinel.

OverviewAutomated EBICS Transfers are monitored by:

l Log messages inside Gateway

l Sentinel tracking

In EBICS T (Transport only) with Gateway, you can enable Sentinel monitoring to track the transfer coming from the back-end and have the link with the EBICS outgoing transfer.

EBICS Gateway Client, by default, uses XFBTransfer as tracking object. The tracking object, and the object version, can be configured in the conf/ebicsclient.properties and client/bin/config[.sh|.cmd] script. Each time a message has a change in transfer state, either Gateway or EBICS Gateway Client generates and sends an XFBTransfer notification message to Sentinel. In Sentinel monitoring, you can have a complete view of the initial transfer and of the EBICS transfer. The two events (the Gateway transfer and the EBICS Gateway Client transfer) are linked to Sentinel with a Cycle link.

The following diagram shows the flow of notification messages between EBICS Gateway Client, Gateway and Sentinel.

Figure 4. Flow of notification messages between EBICS Gateway Client, Gateway and Sentinel.



Configure EBICS Gateway Client for end-to-end Sentinel integrationYou need to select the Sentinel monitoring option when you install EBICS Gateway Client. To reconfigure EBICS Gateway Client at a later stage, use the Configure function of the installer.

Notes:

l To use Sentinel, XFBTransfer must be defined inside the Sentinel Server.

l To get full benefit from Sentinel tracking, Gateway should be Sentinel-enabled too.

Sentinel attribute namesThe following table shows Sentinel attribute names used by EBICS Gateway Client and the messages sent to the Sentinel Server for different events.

Gateway notifications to Sentinel

Attribute name Initial transfer Pre-processing of EBICS transfer

Post-processing of EBICS transfer

CREATIONDATE Date. Example 09/09/2011

Date. Example 09/09/2011

CREATIONTIME Time. Example 11:47:09

Time. Example 11:47:09

CYCLEID CycleID of the EBICS transfer

CycleID of the EBICS transfer.

CycleID of the EBICS transfer.

DIRECTION Direction of the transfer: E for emission

Direction of the transfer: E for emission

Direction of the transfer: E for emission

ENDDATE Date. Example 09/09/2011

ENDTIME Time. Example 11:47:09

FILENAME File name of payload File name of payload File name of payload






ISALERT Indicates whether the transaction is in an alert state.

0 = not alert

1 = alert, not resolved

2 = alert, resolved

0

ISEND 2

LOCATION hostname

MACHINE hostname

MONITOR GTW GTW

MONITORVERSION GTW version GTW version

PRODUCTNAME Axway EBICS Client Axway EBICS Client

PRODUCTOS Name of the OS running on the machine

The OS on the machine running EBICS Gateway Client

PROTOCOL EBICS EBICS EBICS

PROTOCOLPARAMETER

N/A N/A N/A

RECEIVERID Host ID of the EBICS Bank. Example: CDN

Host ID of the EBICS Bank. Example: CDN


RETURNCODE 0 0

RETURNMESSAGE Description for a rejected transaction

SENDDATE Date. Example 09/09/2011


SENDERID






SENDTIME Time. Example 11:47:09


SIGNENTITYOBJECTID

STARTDATE Date. Example 09/09/2011


STARTTIME Time. Example 11:47:09


STATE TO_EXECUTE PROCESSING TERMINATED

TRADEDESTINATION Host ID of the EBICS Bank. Example: CDN



TRADEDESTINATIONALIAS




TRADEORIGINATOR EBICS Customer ID.

Example: CUSTCDN

EBICS Customer ID.

Example: CUSTCDN

EBICS Customer ID.

Example: CUSTCDN

TRADEREQUESTTYPE EBICS File format

Example: pain.xxx.cfonb160.dct

pain.xxx.cfonb160.dct

pain.xxx.cfonb160.dct

TRADESERVICE Order Type

Example: FUL

FUL FUL

USERID EBICS User ID.

Example: TECHUSER

EBICS User ID.

Example: TECHUSER

EBICS User ID.

Example: TECHUSER

Send and Fetch transactions with EBICS Gateway Client

General behaviorEBICS Gateway Client is a process that runs continuously, waiting for Transfer Requests.



EBICS requests are defined as an XML file set inside the client/working/incoming directory.

During the processing of this file, the file will be moved from the incoming to processing then to the done directory, or to the error directory if an error occurs.

If an error occurs, the error description is added to the XML file for diagnosis purposes. Each error is tagged with the error date.

An incoming request may also contain a script name (and parameters) to be launched when the transfer is terminated, successfully or not. XML file requests contain several fields that allow to link to the origin of the transfer, being a Gateway reference or Sentinel notifications.

Request definitionThere are two XML schemas that define the XML request:

l For the Send request, the XML schema is defined inside: mft/Send/order.xsd

l For the Fetch request, the XML schema is defined inside: mft/Fetch/fetch.xsd

Samples of XML files are provided with the XML schema.

Explanation of tags

Tag name Description

Send or Fetch Root tag of the XML request. Important: This identifies the direction of the transfer.

Send@test or Fetch@test Defines the transfer as being a test transfer. This information is sent to EBICS Gateway Server as a protocol attribute, an OrderParam value. This information is used and relevant only for the OrderTypes FUL.* and FDL.*.

initialTransferReference Identifies the transfer from the back office point of view. It is used to transfer the Gateway LocalId for Automated File Transfer.

bankName Bank name

orderType Order type. For example: FUL.camt.001.001.02

customerId Customer ID

countryCode Country code




filePath File name to read for a Send request or name to be used to write the Fetched data.

userId Send: EBICS User name used to sign the transfer. Fetch: EBICS User name that requests the transfer. There might be only one for Fetch requests.

systemID EBICS User name that is used to transport the files. If no additional signatures are sent, the transfer is done without any responsibility involved.

SentinelReferences\TrackingObject Sentinel reference of the EBICS Transfer

SentinelReferences\CycleId Sentinel reference of the EBICS Transfer

orderParams\name Name of each optional Order Parameter that is sent within the transfer

orderParams\value Value of each optional Order Parameter that is sent within the transfer

fromDate Starting date to retrieve data from. Time granularity is the day. Format is YYMMDD.

toDate Ending date to retrieve data to. Format is YYMMDD.

Results\result\@date Date of the error detection

results\result\ebicsReturnCode\errorSymbol EBICS error as a Symbol defined inside the Standards, such as EBICS_INVALID_USER_STATE or EBICS_NO_DOWNLOAD_DATA_AVAILABLE

results\result\ebicsReturnCode\errorDescription String description of the EBICS error

results\result\ebicsReturnCode\errorCode Code of the error, such as 091004 or 090005

results\result\stackTrace Java stack trace of the anomaly, for analysis purposes




endOfTransferCallBack Program name and parameters to be launched at the end of the transfer.

originalReferences Not currently used

End of transfer callback variablesThe end of transfer script is launched in a process that has these variables defined.

Most of the variables are a copy from the initial XML request, some are the result of the transfer.

Variable name Description

EBICSVAR_TEST Y if transfer is a test transfer. N otherwise.

EBICSVAR_BANK Bank name

EBICSVAR_OP_* Order parameters (optional)

EBICSVAR_FILEFORMAT File format

EBICSVAR_ORIGINAL_CYCLEID Cycle ID of the EBICS transfer

EBICSVAR_ORIGINAL_TRANSFERID Identifier of the original transfer (Local ID of Gateway transfer)

EBICSVAR_TRACKINGOBJECT Tracked Object of the EBICS transfer

EBICSVAR_FILENAME Full path name of the data file

EBICSVAR_CUSTOMER EBICS Customer ID

EBICSVAR_ORDERNUMBER EBICS Order number of the generated transfer

EBICSVAR_ORDERTYPE EBICS Order type

EBICSVAR_ERROR_CODE 0 if no error. Different otherwise.

EBICSVAR_ERROR_MESSAGE Error message

EBICSVAR_EBICS_ERROR_CODE EBICS error code. Refer to EBICS standards specifications.


3 EBICS Gateway Server

This chapter introduces EBICS Gateway Server and its administration.

Introduction on page 41

EBICS Gateway Server administration on page 41

About the EBICS Gateway Server administration UI on page 48

Set up EBICS Gateway Server on page 52

EBICS Gateway Server post-processing on page 92

Manage administrator users on page 100

EBICS security services via PassPort on page 106

Encrypt data at rest in EBICS Gateway Server on page 124

Use EBICS Gateway Server with a DMZ proxy on page 131

EBICS Gateway Server tools on page 132

For information about the EBICS Gateway Server configuration file, refer to: EBICS Gateway Server configuration file on page 187.

IntroductionEBICS Gateway Server enables you to use the EBICS protocol in a banking environment, to serve requests issued by corporate customers. You operate EBICS Gateway Server via a uniform web administration interface.

EBICS Gateway Server is scalable so it can easily be adapted to your financial exchange requirements from a simple standalone system for smaller banks, to a high-end cluster system for large retail banks.

EBICS Gateway Server administrationEBICS Gateway Server runs on an application server.

For convenience, an embedded application server is provided that can be chosen at installation for easy, almost out-of-the-box installation and configuration. This application server supports standalone (only one node) installation.


3 EBICS GatewayServer

For High Availability you can install EBICS Gateway Server on a JBoss EAP application server in a cluster configuration (multiple nodes). For details, refer to the Axway EBICS Gateway Installation Guide.

A High Availability license option is needed to install a cluster configuration.

Administer the standalone embedded application server

Start the standalone embedded application serverTo start the standalone embedded application server, go to: <EBICS Gateway dir>/server/EmbeddedServer/binand run the script for your OS:

l nohup ./standalone.sh &, or

l standalone.bat

How to access the EBICS Gateway Server interfacesIn this version of EBICS Gateway Server, three port settings are used:

l You can access the EBICS Gateway Server GUI (Admin UI) at:

https://<hostname>:<admin_ui_port>/admin

l The EBICS Service (for EBICS clients connections) is available at:

https://<hostname>:<ebics_service_port>/ebics/EbicsServlet

l The remote EJB port for the EBICS Gateway Server tools (injector, purge, supplier) is available at:

<hostname>, on port <ebics_remote_EJB_port>

Use the hostname and ports defined during installation.

l By default the Admin UI port is 8443.

l By default the EBICS service port is 8444.

l By default the remote EJB port is 4447.

Stop the standalone embedded application serverTo stop the standalone embedded application server, go to: <EBICS Gateway dir>/server/EmbeddedServer/bin

and run: ./jboss-cli.sh -c --command=shutdown

If the script asks you to accept a certificate, select: [P]ermanently.



Log filesEBICS Gateway Server logs for the standalone embedded application server are located in:

<EBICS Gateway dir>/server/EmbeddedServer/standalone/log/server.log

Java parametersIf you want to modify the JVM parameters of the standalone embedded application server, such as the JAVA_HOME, or the XMX parameters, edit the file:

<EBICS Gateway dir>/server/EmbeddedServer/bin/standalone.conf

Configuration fileYou can find the configuration parameters of the standalone embedded application server in:

<EBICS Gateway dir>/server/ EmbeddedServer/standalone/configuration/standalone.xml

Run the standalone embedded application server as a Windows serviceThe standalone embedded EBICS Gateway Server is an application that runs on WildFly. This section describes how to configure WildFly to run as a Windows service.

PrerequisitesImportant: Before running WildFly as a service, you must have successfully configured WildFly and made sure that it is working as expected.

Configuration stepsFollow these instructions to make sure that the user account under which the service will be run is properly configured, Java is available to the user, and the EBICS Gateway Server certificate is trusted by the user account.

User accountIt is good practice to have a dedicated user account for running the WildFly service because this allows you to have complete control over that user's rights. You can either create a new user or use an existing user. For details, refer to the official Windows documentation.



The remaining part of this section assumes that you are logged on as the user you have just selected.

Set up Java 1. Open the Windows Environment Variables dialog.

2. Set the user's JAVA_HOME to the JDK installed with EBICS Gateway:

<EBICS Gateway dir>\Java\win-x86\jre8_u40_64

3. Add the java binary to the PATH :

JAVA_HOME\bin\java.exe

Accept EBICS Gateway Server certificate permanently 1. Start EBICS Gateway Server:

<EBICS Gateway dir>\server\EmbeddedServer\bin\standalone.bat

2. To accept the EBICS Gateway Server SSL certificate you need to call the JBoss client once:

<EBICS Gateway dir>\server\EmbeddedServer\bin\

jboss-cli.bat -c

3. Check that you have output similar to this:

Unable to connect due to unrecognized server certificate

Subject - CN=xxx,OU=a,O=b,C=c

Issuer - CN=yyy, OU=xxx, O=aa, C=oo

Valid From - Fri Aug 09 15:45:05 CEST 2013

Valid To - Thu Nov 07 14:45:05 CET 2013

SHA1 :

f4:5b:79:bd:4f:f7:54:20:19:ac:96:8e:de:95:9e:a4:28:a3:b6:13

MD5 : c7:a9:65:1d:4c:39:47:b9:b5:bd:32:42:8e:d5:c7:72

Accept certificate? [N]o, [T]emporarily, [P]ermenantly :

If you do not get this output, the certificate has already been trusted.

4. Accept the certificate permanently.

5. Stop EBICS Gateway Server by closing the command prompt that started it.

Note: If, at some time in the future, you update the SSL certificate that is used by EBICS Gateway Server, you will need to perform this step again.

Register the service 1. In a command line prompt, move to:

<EBICS Gateway dir>\server\EmbeddedServer\bin\service

2. Enter the command:



service.bat install /controller localhost:9993

Make sure you specify the port that you are using. By default EBICS Gateway Server uses 9993 instead of the default 9990.

3. Open the Windows Services application and check that the WildFly service is now registered.

Configure the service 1. In the Windows Services application, double-click the WildFly entry to access its properties.

2. Click the Log On tab, and enter the details for the user account that you have chosen previously.

You can configure other aspects of the service in the properties dialog according to your use case.

Run the serviceAfter configuring the service, you can use the Windows Services application to start and stop the WildFly service.

Alternatively you can use the service.bat script:

l service.bat start

l service.bat stop

Uninstall the serviceTo remove the service from Windows, use the service.bat script:

service.bat uninstall

Service logsThe service logs are located together with the Server logs in:

<EBICS Gateway dir>\server\EmbeddedServer\standalone\log

This folder contains two extra log files:

l wildfly-stdout... – for standard output

l wildfly-err... – for error output



Administer EBICS Gateway Server on WebSphereImportant: After configuring the application and before starting it, restart the WebSphere Application Server.

1. Open a session in the WebSphere Administration Console using the credentials admin/start.

2. Navigate to Applications > Applications Types > WebSphere enterprise applications.

3. Click the AxwayEbicsServer application.

4. The state of EBICS Gateway Server appears, as well as the available actions:

l Click Start to start the application.

l Click Stop to stop the application.

Administer the JBoss EAP application server (cluster configuration)The administration of the EAP cluster will depend on your corporate EAP environment. EBICS Gateway Server does not provide or manage the EAP installation.

However, a sample EAP runtime configuration environment is provided in the <EBICS Gateway dir>/server/EAP_components directory. The files provided there can be adapted to configure and/or manage your own EAP environment. For more information about running the sample environment, refer to "Server post-installation: JBoss EAP cluster" in the Axway EBICS Gateway Installation Guide.

Note The commands in this section assume you have the sample environment pre-configured and working correctly.

Starting and stopping nodes

Start a nodeImportant: When starting cluster nodes, make sure you always start the master node before the slaves.

On the Master node:

1. Change to the <EBICS Gateway dir>/server/server/EAP_components/bin

directory.

2. Start the master EAP node by executing ./ebicsClusterAdmin.sh start.

3. Check the <EBICS Gateway dir>/server/server/EAP_

components/runtime/<node_name>/logs to make sure the node started OK.



On the Slave nodes:

1. Change to the <EBICS Gateway dir>/server/server/EAP_components/bin

directory.

2. Start the slave EAP node by executing ./ebicsClusterAdmin.sh start.

3. Check the <EBICS Gateway dir>/server/server/EAP_

components/runtime/<node_name>/logs to make sure the node started OK.

The server should now be up and running, and available at:https://<ADMIN_UI_ALIAS>:<ADMIN_TLS_PORT>/admin

Stop a nodeStopping a node via the command line requires the stop command to be sent through the master node. Therefore you must shut the master node down last.

The stop command can be run from any node, but nodes other than the master will require the server admin user/password.

To stop the current node you are logged into, run:

<EBICS Gateway dir>/server/server/EAP_components/bin/ebicsClusterAdmin.sh stop

To stop a specific node, run:

<EBICS Gateway dir>/server/server/EAP_components/bin/ebicsClusterAdmin.sh stop <NODE_SHORT_HOSTNAME>

Deploy EAR components for the first time

From the command line on the master node run:

<EBICS Gateway dir>/server/server/EAP_components/bin/ebicsClusterAdmin.sh deploy

Update an existing EAR

From the command line on the master node run:

<JBOSS_INSTALL_PATH>/bin/jboss-cli.sh -c --command="deploy <PATH_TO_UPDATED_bankrechner.ear> --force --runtime-name=bankrechner.ear"

Log filesIn the sample EAP environment the logs for each node are located under: <EBICS Gateway dir>/server/server/EAP_components/runtime/<NODE_HOSTNAME>

EAP Host and Process controller logs:

./log/process-controller.log



./log/host-controller.log

EBICS Server application log:

./servers/ebics-server/log/server.log (not present on the master node)

About the EBICS Gateway Server administration UI

Log on to the user interfaceWhen you call up the EBICS Gateway Server administration URL in a web browser, it opens a logon dialog screen. Enter your user name and password. This information is securely transferred to the EBICS Gateway Server and checked there.

You can access the EBICS Gateway Server GUI (Admin UI) at:

https://<hostname>:<admin_ui_port>/admin

Use the hostname and port defined during installation. By default the Admin UI port is 8443.

Browser autocompletion settingsYour browser might have an autocompletion (autofill) and a password saving feature enabled. This can bring potential security issues if a hacker gets access to your workstation. It is therefore recommended to deactivate the autocompletion and password saving features inside your browser.

Description of the user interface screenThe main screen of the EBICS Gateway Server user interface is divided into two areas. The left area displays a navigation menu that you use to switch between different object categories and functions of the application. The right area contains the content, according to the menu item selected on the left.

When you select an object category in the left area, the initial display includes a search template that enables you to search for data or enter a new data record. If appropriate, a search generates a table display of search hits. From this table, you access a detail dialog for displaying or editing the data.

Modifying object contentFor information purposes, and to protect against accidental changes, all data is initially displayed in read-only format. To make changes, you must switch the interface to processing mode.

To change to processing mode, click Start change process in the left area of the screen.



You can then navigate freely inside objects, making use of the New or Edit buttons for any changes required.

In processing mode, all modifications are recorded in EBICS Gateway Server. However, these changes are not taken into account until you validate them (or cancel them).

In the left area, the interface now displays two buttons:

l Terminate change: Enables you to leave processing mode and save all changes that have been made

l Cancel change: Enables you to leave processing mode and discard all changes that have been made

Above these two buttons, the interface displays the number of changes you have made during this editing session.

Note that when you are in processing mode, all pending changes will be either validated or canceled together: you cannot validate only some of the pending changes. If you have pending changes, but want to store a new change without validating previous ones, you have to cancel the previous changes.

SearchingThe search template contains all the data required for the search. All search fields implicitly contain an AND link, so that adding fields of search criteria increasingly restricts search results. If the search does not return a result, the No data found message is displayed directly underneath the Search button.

Search resultsSearch results are displayed in the form of a table.

The returned search results can extend to several pages. Use the Hits per page selection box to control the number of displayed results. The default setting is 20 hits per page.

Beneath the table, the interface displays the number of hits and the currently displayed page.

Beneath this information, the interface displays a set of buttons for navigating the hit list, if appropriate for the number of results.

Button Action

Display first page

Five pages back



Button Action

One page back

One page forwards

Five pages forwards

Display last page

To sort the results table by different columns, click the header of any column of the table. When you click a column a second time, the display order is reversed. The current sorting order (ascending/descending) is indicated by an arrow pointing up or down next to the column.

In addition to information about the returned data, if you are in processing mode the table contains buttons for enabling the processing or viewing of a row. Up to three buttons appear here, depending on your user type.

Button Action

Edit Opens the detail dialog for processing

Display Opens the detail dialog for the display

Delete Deletes the object

Restore Reverses the deletion of the object. It can only be selected to undo the deletion when a displayed data record has been deleted.

Detail dialogThe detail screens display the values of specific objects. The detail screen is identical for processing and displaying data. Data displayed in read-only mode cannot be processed.



Each detail screen displays the following buttons, which are visible or hidden depending on the situation:

Button Action

Save Saves the changes that have been made. Visible only in processing mode.

Back Cancels the current action and returns to the search template. Always visible. In processing mode, changes are discarded.

New entryThe search template includes a button for creating a new data object. When you click the button, the detail dialog appears in processing mode, enabling you to enter attributes for the object.



Set up EBICS Gateway ServerTo create and manage exchanges between your banking entity (yourself) and your remote customers, you need to create various objects using the menu items provided in the EBICS Gateway Server user interface.

This section describes the EBICS Gateway Server UI menu items and provides configuration examples.

Bank objects on page 53

Example: Create a Bank on page 56

Change Processes menu item on page 57

Files on page 58

Account objects on page 61

Customer objects on page 63

Example: Create a Customer on page 68

Example: Create a User on page 68

Example: Grant order types on page 70

Protocol objects on page 70

EBICS: Processing on page 71

Example: Create a Fetch order type on page 82

Example: Create a Send order type on page 83

Example: Create and associate a post-processing item on page 84

Example: Declare supplier for fetch on page 85

Post-processing steps on page 86

Configure back-end connection with Gateway and Transfer CFT on page 88

Configuration examples on page 90



Bank objectsA Bank object represents a bank or component service (department, branch, agency, filial, and so on) of a bank.

The Bank Server is capable of managing the customers of several banks. To do so, you can configure individual Bank objects in the Banks menu item.

Create a Bank 1. In the EBICS Gateway Server UI, select the Banks menu item.

2. Select Create new bank.

3. Complete the fields:

Field Description

Name Enter a unique name that is used to identify a bank at various points in the administration interface.

Host ID Enter the bank EBICS identifier.

Configuration-letter generator

If you want to change the way the configuration letter is generated by the bank for a customer, specify the class name of a new generator.

Length of hash-value input

Enter the hash value length.

Long IDs The EBICS 2.4 standard permits the use of Host IDs with lengths up to 35 characters. EBICS 2.3 limited Host IDs to 8 characters.Select this option to indicate the use of the updated standard for character length.

EBICS support Activates or deactivates EBICS for the bank you are creating. If you activate EBICS support, all keys required for EBICS encryption are generated automatically.

EBICS Host-ID Enter the bank EBICS identifier.



Field Description

URL Enter https://<host>:8443/ebics/EbicsServlet

Do not change the ebics/EbicsServlet part of this URL.

Key generation

Select which format to use for bank keys:

l Self-signed certificates

l Key pairs without certificates

l Import PKCS12 file

Key length This field is visible if you select the Self-signed certificates or Key pairs without certificates option.

Default: 2048

Import PKCS12 file

Select this option if you want to import a PCKCS12 file to store private keys with accompanying public key certificates.

Encryption key This field is only visible if you select the Import PKCS12 file option.

Enter the path to the encryption key you want to use.

File password This field is only visible if you select the Import PKCS12 file option.

Enter the password for access to the encryption key file.

Authentication key

This field is only visible if you select the Import PKCS12 file option.

Enter the path to the authentication key you want to use.

Protocol versions

Select the EBICS standard version you intend to use for exchanges between the bank and remote clients.

l H002

l H003

Signature versions

Select the EBICS signature versions you intend to use between the bank and remote clients.

l A004

l A005

l A006

Force certificates

Select this option to require the customer to use X.509 certificates.



The bank details page displays details of the selected bank. It displays the hash value of the key. Click the hash value to display the public details of the keys: modulus and exponent. For security reasons, the private details are stored in the database but are not displayed.

4. Click Save.

CFONB complianceEBICS Gateway Server checks for CFONB compliance if certain conditions are met when the Bank is created.

Ensuring CFONB complianceDuring bank creation, ensure that the following parameters are set in the EBICS Gateway Server UI. All transfers to the banks on the EBICS Gateway Server side will then be checked for CFONB compliance.

Checkbox Requirement for CFONB compliance

Long IDs Checked

Protocol versions - H003 Checked

Signature versions - A005 Checked

Signature versions - A006 Checked

Force certificates Checked

CFONB overlay requirementsFor the CFONB overlay, the most important requirements are:

l Certificate version must be 3

l Signature algorithm must be sha256WithRSAEncryption (1.2.840.113549.1.1.11)

l Maximum certificate validity must be 5 years and 2 minutes

l Certificate SubjectDN must contain CN (Common Name) value

l Certificate must have CRLDistributionPoints extension (2.5.29.31)

l Certificate must have AuthorityKeyIdentifier extension (2.5.29.35)

l Certificate must have DigitalSignature key usage

l Certificate must have KeyEncipherment key usage

l Key-length must be greater than or equal to 2048



Example: Create a Bank 1. Open an EBICS Gateway Server GUI session.

2. Select the Banks menu item.

3. Select Start change process.



Field Description

Name Enter EbicsServer for this example

Length of hash-value input

Enter 0 for this example

Long IDs Select to use the EBICS 2.5 standard for character length

EBICS support

Select to activate EBICS for the Bank you are creating

EBICS HOST-ID

Enter the BIC of the Bank

URL Enter: https://<host>:8443/ebics/EbicsServlet


Key generation

Select Self-signed certificates

Key length Enter 2048 for this example

Protocol version

Enter H003 for this example

Signature version

Enter A005 and A006 for this example

Force certificates

Select this option

6. Click Terminate change.

7. Click Terminate change process to leave editing mode.



Change Processes menu itemThe Change Processes menu item enables you to view all change operations executed by administration users on the EBICS Gateway Server.

You show all change operations or filter the operations by user. You also have the option of displaying system modifications.

To view change operations:

1. Select the Change Processes menu item.

2. Complete the filter fields.

Field Description

Name Enter a user name to generate a change display for a single user. Alternatively, leave this field blank to display changes executed by all users.

Remark

Show hidden modification

Select this option to display internal system modifications.

Status From the drop-down list, select one of the following status conditions to use as a filtering criteria:

l All (default)

l Active

l Confirmed

l Waiting for confirmation

l Refused

Results per page

From the drop-down list, select one of the following numbers for the per page results display:

l 10

l 20

l 50

l 100 (default)

3. Click Search.

The search tool returns results based on the entered criteria.



FilesThe Files menu item enables you to search for records of transfers that are in progress or have been completed by a customer. A record for every correctly-started transfer appears on this screen.

Searching filesEnter data in the following fields to create file search criteria:

Field Description

Period from Enter an earliest date and time (HH:MM) for the start of transfers. Default value is current date at time 00:00.

Period to Enter a latest date and time (HH:MM) for the start of transfers. Default value is current date at time 23:59.

Customer Enter a customer Id as filtering criteria for the file record search.

You do not have to enter a complete customer ID here, you can also search for parts of the ID.

Example: If you enter ax, the system searches for transfers for customers that include the letters ax, such as AXWAY, AXTEST or AXTRANSFER.

User-Id Enter a participant ID as filtering criteria for the file record search. You do not have to enter a complete participant ID here.

Channel Enter a channel as filtering criteria for the file record search.

Order number Each file transfer is assigned a unique order number by the customer system. Use this number as filtering criteria for the file record search.

Order type Enter an order type as filtering criteria for the file record search.



Field Description

State Enter a transfer state as filtering criteria for the file record search. Enter one of the following states:

l all

l canceled

l terminated

l error

l new

l processing

l waiting for data file

l waiting for signatures

l waiting for manual release

l waiting for being collected

l positive feedback signal

l negative feedback signal

View the Details pageAfter you run a search and receive a set of results, click Details to view additional information about any transfer that is displayed in the list of results. You can view the following information:

Field Description

General information

Customer Customer who transferred the file. The name of the customer is also a link that enables you to go to the customer page.

Order number Unique order number assigned by the customer system

Order type Specifies the file that is transferred. The accompanying sheet and post-processing are selected accordingly.

Channel Channel used for the transfer

State Current status of the transfer

Ticket

— Displays a processing report on the transfer



Field Description

File

Received Time when file transfer began

End of Transfer

Time when file transfer ended

User-Id ID of customer who initiated the transfer

Filename File name under which the file was saved in the system. The system saves the files in a directory structure that can accept any number of files. Current operating systems can only accept a limited number of files per directory. Hence, the system automatically uses a nested file structure that enables efficient file access.

File size Size of the data file in bytes

Content Click to display the entire data file

Customer Protocol

— Excerpt that contains all entries regarding this file. This enables an overview of the actions that have been executed and helps with analysis and troubleshooting.

Bank Protocol

— Detailed log messages that the system has logged for this file. Here, you can see the processing history of the file in even greater detail than in the customer log.

Signatures



Field Description

— Displays a table of signatures that have been received for this file with the following columns:

l User: User ID of the signer

l Name: Exact name of the user

l Signature permission: Signature permission type by which the correct signature is evaluated. Possible values are:

o initial signature

o second signature

o single signature

o transport signature

l Result: Result of the signature check

l Details: Click to display the technical details of the signature

Account objectsAn Account object represents an account that can be managed in the EBICS Gateway Server.

You can create Account objects to represent all of your managed accounts. The Accounts menu item enables you to display and search accounts as well as create new ones.

To create an Account:

1. Select the Accounts menu item.

2. Click Create new account.

3. Complete the fields.

Field Description

Bank Enter the bank name.

Country From the drop-down list, select the country where the account is located:

l France

l Germany

Bank code Enter the bank code.

Branch code Enter the code of the bank branch.



Field Description

Account number Enter the account number of the account. This number is used, for example, for the account authorization check, but also for the provision of account statements.

Check digits Optionally enter a French account number to be controlled for format coherence.

SWIFT code Optionally enter the SWIFT code of the bank for the provision of account statements.

Additional account number

Optionally enter an alternative account number for the provision of account statements.

IBAN If no IBAN is specified, it is calculated and entered automatically from the bank routing number and the account number. The IBAN can also be used to assign account statements.

Currency Enter a currency for the transactions on this account. This value is for information purposes only and is not used by the EBICS Gateway Server. However, this information is forwarded during the EBICS master data download.

Holder Enter an account holder identity. This value is for information purposes only and is not used by the EBICS Gateway Server. However, this information is forwarded during the EBICS master data download.

Description Enter text to describe the account. This description is for information purposes only and is not used by the EBICS Gateway Server. However, this information is forwarded during the EBICS master data download.

The Account detail page displays a list of customers who have access to the account. An account can be assigned to several customers. Every assigned customer receives account statements for this account. The customer participants can submit payments for the account.

4. Click Save.



Customer objectsA Customer object represents a customer who performs transactions with a bank.

Search for existing customersWhen you select the Customers menu item, the interface displays the customer search screen. You can enter the following criteria in a customer search. If you enter no criteria, the search returns all customers entered in the database:

Criteria Description

Customer ID Enter a valid customer ID.

Name Enter a customer name.

Bank Enter the bank to which the customer is attached.

View and edit customer detailsAfter you execute a search, the interface displays a table of returned results. if you are in:

l Read-only mode, click the Detail button to view complete details of any customer.

l Processing mode, click the Edit button to view and edit details of any customer.

The interface displays the detail window, which comprises the following tabs:

l General information tab on page 63

l User tab on page 64

l Order types tab on page 67

l Files tab on page 67

l Accounts tab on page 67

l Protocol tab on page 68

l History tab on page 68

General information tabThis tab holds general information about the Customer.

Field Description

Customer ID Enter a customer identification number



Field Description

Name (mandatory) Enter a customer name.

Name 2 Optionally enter an additional name

Name 3 Optionally enter an additional name

Street Enter the customer street address and street number

Zip code Enter the customer zip

City Enter the customer city

Country Enter the customer country

Phone Enter the customer phone

Fax Enter the customer fax address

Bankinternational ID Enter a reference to the user in the bank’s main master data application. This value is for information only and is not used elsewhere.

Bank Displays the unique bank access (read-only)

Trace EBICS requests Optionally choose to log EBICS communications with this customer.

User tabThe User tab displays a list of the users associated with this customer.

In the overview, the participant ID, name, e-mail address and the different statuses of the individual communication methods are displayed. You can thus see at a glance whether a participant is blocked or waiting for clearance.

Click Details (or Edit if you are in processing mode) to view extended attributes of the user. The extended view of the User comprises the following tabs:

l General information: Contains general information about a User associated with the customer

Field Description

UserID Id of the user



Field Description

Name Full name of the participant as it is to be used in the customer log

Name 2 Optional additional name element

Name 3 Optional additional name element

Street User street and number

Zip code User zip

City User city

Email User email

Language Language of the User

Bank internal ID Local identity of the bank

Permission for all accounts

If this option is selected, the user can access all accounts configured for the customer, otherwise the accounts have to be assigned individually on the "Accounts" tab.

Permission for all fetch order types

If this option is selected, the user is assigned all fetch order types that are configured on the customer. Otherwise, these have to be configured individually on the "Fetch order types" tab.

Permission for all send order types

If this option is selected, the user is assigned all send order types that are configured on the customer. Otherwise, these have to be configured individually on the "Send order types" tab.

Default permission

If the participant is authorized for all send order types, he or she is assigned this signature authorization for all business transactions.



Field Description

Limit type If a limit is set up here, the amount entered in the following field is the maximum that the participant can access. If this is a daily, weekly or monthly limit, the participant may access no more than this amount with all set up files within this time frame. The already utilized amount and the start of the utilization period are displayed below. The limit applies irrespective of limits that might be configured for this participant at a different point.

Limit (EUR) Maximum amount in Euro that the participant may access. This amount is only displayed if a limit has been set.

Limit reached For limits with a time span, this field displays the amount consumed so far.

Limit period For limits with a time span, this field displays the start of the utilization period.

l Channels: Identifies the authorized channel (EBICS)

l Fetch order types: This tab is only visible if the user is not authorized for all retrieve order types of the customer in general. The tab lists all order types assigned to the customer. Every order type is displayed with a selection box to control authorization for the type (processing mode only).

l Send order types: This tab is only visible if the participant is not authorized for all send order types of the customer in general.

A list (possibly spanning several pages) is displayed containing the names of the order types assigned to the customer as well as a selection box containing the signature authorizations currently assigned to the participant. When you save, the changes to the signature authorizations are accepted.

For system transport types (HCA, HIA, HSA, INI, PUB, SPR and VPK) the initial, secondary and transport signature authorizations are regarded as sufficient for executing an order.

For order types that support a limit check, you can set a limit for the user (processing mode only). The configuration is made analogous to the limit that you can set up in the general data of the user. The limit then applies to all files of the respective order type, irrespective of the limits configured for the user elsewhere.

l Accounts: This tab is only visible if the user is not authorized for all accounts of the customer in general.

A list (possibly spanning several pages) is displayed containing all accounts of the customer with the bank routing number, account number, designation and the signature authorization



currently assigned to the customer. These signature authorizations overwrite the authorization that a participant has for a send order type in general. When you save, the changes to the signature authorizations are accepted.

You can set a limit for each account for the participant. The configuration is made analogous to the limit that you set in the general data of the user. The limit then applies to all files submitted for this account, irrespective of the limits configured for the user elsewhere.)

Order types tabThis tab displays all order types that are authorized for the customer. The screen has two sections:

l Fetch order types

l Send order types

Users of a customer can only be authorized for order types for which the presently selected customer is authorized. If you remove an order authorization from the customer, all users of the customer also lose authorization for this order type.

For send orders, you can individually set the response for D files and the number of required signatures for each customer.

Files tabAll files sent by the customer are displayed here.

For a detailed description of file characteristics, see Files on page 58.

Accounts tabThis tab displays all accounts to which the customer has access.

Field Description

Bank code Enter the account bank code

Account number Enter the account number

SWIFT code Enter the SWIFT code of the account

Additional account number

Enter any additional account number information

IBAN Enter the IBAN

Holder Enter the holder name

Description Enter any description text

Click Create new account to create a completely new account for the customer.



Click Add accounts to grant the customer access to one or more already existing accounts. When you select this option, the interface displays the account search page (see Account objects on page 61). In the results list you can then select any number of accounts and accept them by clicking Add selection.

Click Create permission report to generate a report of all permissions for the customer.

Protocol tabDisplays logs that are generated for customer transactions during the period you select.

History tabDisplays a list of all changes made to the selected customer.

Example: Create a Customer 1. Open an EBICS Gateway Server GUI session.

2. Select the Customers menu item.


4. Select Create new customer.


Field Description

Customer ID

Enter CUSTOMER1 for this example

Name Enter New customer to link to EBICS Gateway Server for this example

Bank Select EbicsServer.

6. Click Save.


Example: Create a User 1. Open the CUSTOMER1 customer screen.

2. Select the User tab.





Field Description

UserID Id of the user

Name 2 Full name of the participant as it is to be used in the customer log

Name 3 Optional additional name

Street User street and number

Zip code User zip

City User city

Email User email

Language Language of the User

Permission for all accounts

If this option is selected, the user can access all accounts configured for the customer, otherwise the accounts have to be assigned individually on the "Accounts" tab.

Permission for all fetch order types

If this option is selected, the user is assigned all fetch order types that are configured on the customer. Otherwise, these have to be configured individually on the "Fetch order types" tab.

Permission for all send order types

If this option is selected, the user is assigned all send order types that are configured on the customer. Otherwise, these have to be configured individually on the "Send order types" tab.

Limit type If a limit is set up here, the amount entered in the following field is the maximum that the participant can access. If this is a daily, weekly or monthly limit, the participant may access no more than this amount with all set up files within this time frame. The already utilized amount and the start of the utilization period are displayed below. The limit applies irrespective of limits that might be configured for this participant at a different point.

Limit amount

Maximum amount in Euro that the participant may access. This amount is only displayed if a limit has been set.



Field Description

Limit utilization

For limits with a time span, this field shows the amount consumed so far.

Limit period

For limits with a time span, it shows the start of the utilization period.

5. Click Save.


Example: Grant order typesTo create an OrderType that can be shared among several Customers, select the standard option for the OrderType. This sets the OrderType as a system-level default OrderType for any newly-created Customers.

If you want to define several Users inside the same Customer, select the OrderType on the Customer level, and then select the options Permission for all fetch order types and Permission for all send order types on the Customer screen/User tab. This applies all Customer-level defined OrderTypes to the newly-created User.

Protocol objectsThe Protocols menu item enables you view server log entries that are generated for every action in the EBICS Gateway Server. You can search and filter log entry displays using the following input criteria:


Period from Enter an earliest date for the start of transfers. Default value is current date.

Period to Enter a latest date for the start of transfers. Default value is current date.

Customer Enter a customer Id as filtering criteria for the file record search.

You do not have to enter a complete customer ID here, you can also search for parts of the ID.

Example: If you enter ax, the system searches for transfers for customers that include the letters ax, such as AXWAY, AXTEST or AXTRANSFER.

Order number Enter an order number as filtering criteria for the file record search.




Order type Enter an order type as filtering criteria for the file record search.

Channel EBICS is currently the only choice.

Search resultsWhen you execute a search, the interface displays a table of results that includes the following information for each entry:

Column name Description

Date Creation time of the log entry

Customer If appropriate, the ID of the customer who is responsible for the entry

Channel EBICS is currently the only possible value

Order type The order type

Order number The order number, if the log entry was generated in connection with another file transfer.

Message Text of the entry. As a tool tip for the text, a detailed description for the message appears for some entries. The detailed description using the tool tip appears automatically on mouse-over.

Click the Export button to export the log entries to an Excel worksheet.

EBICS: ProcessingPlace the cursor over the Processing menu item to display a context menu with the following menu items:

l Fetch transactions

Select this item to display the names of the order types and the handler type.

When you create a new order type or edit an existing order type you can select the handler type. Use the Standard option to set whether newly-created customers are assigned this order type automatically.

Some handler types only make sense with certain order types.

Handler types available for fetch transactions:



Handler Order type

From-to query

Data import

One file per customer Any Yes Yes

One file per user Any Yes Yes

Public key for EBICS customers HPB No No

EBICS bank parameters HPD No No

HTD HTD No No

HKD HKD No No

One file for all customers Any No Yes

Customer protocol PTK Yes No

Payment Status Report (PSR) PSR Yes No

Payment Status Report (PSR) per user PSR Yes No

PSR with exit PSR Yes No

Customer user PSR with exit PSR Yes No

Account statements (MT940) STA Yes Yes

Fetch public key VPB No No

Interim Transaction Report (MT942) VMK No Yes

Axway Generic Fetch Transaction Any Yes Yes

Axway Generic Zip Fetch Handler Any Yes Yes

Axway Verbose Fetch Transaction (identical to Axway Generic Fetch Transaction except that it produces more logs and therefore has reduced performance)

Any Yes Yes

Axway Database Fetch Handler Any Yes Yes

Axway Database Zip Fetch Handler Any Yes Yes



Handler Order type

From-to query

Data import

Axway Verbose Database Fetch Handler (identical to Axway Database Fetch Handler except that it produces more logs and therefore has reduced performance)

Any Yes Yes

Customer protocol - PTK (with forwarding and merging) PTK Yes No

In change mode, after you display fetch transaction search results, you can click the edit button of any fetch item to open an editing screen. This screen enables you to modify the following fetch transaction attributes:

o Name: Name of the transaction

o Standard: Select whether or not newly-created customers are assigned this order type automatically

o Handler: Select the handler type for the transaction

From this editing screen, click the Descriptions button to edit existing fetch transaction descriptions or add additional descriptions.

Configuring exits: To configure exits (Axway Generic Fetch Transaction handler file copy exit, PSR with exit handler file copy exit, and the test parameter exit), you must modify properties in the EBICS Gateway Server configuration.properties file. More details

are available upon request from Axway Support.

l Send order type:

Select this item to display the following properties of order types:

o Name of the order type

o Description of the order type

o Response for setting up D files

o Number of required signatures

o Whether or not newly-created customers are assigned this order type automatically

o Handler type

o Post-processing

You can set these properties when you create an order type or when you edit an existing order type. Use the Standard option to set whether newly-created customers are assigned this order type automatically.

Some handler types only make sense with certain order types.

Internal provision table for send order types:



Handler Order type

Post-processing makes sense

Data import

Binary files Any 8-bit Yes No

CCC (pain.001.001.02.con)

CCC Yes Yes

CCM (pain.001.001.02) CCM Yes Yes

CCT (pain.001.001.02.grp)

CCT Yes Yes

CDC (pain.001.001.02.con)

CDC Yes Yes

CDD (pain.001.001.02.con)

CDD Yes Yes

CDM (pain.008.001.01) CDM Yes Yes

DTAUS files IZV, . . . Yes Yes

DTAZV files AZV, . . . Yes No

Initialize keys INI No No

Change key PUB No No

Change password PWA No No

Lock user SPR No No

Text file Any 7-bit Yes No

Customer encryption key VPK No No

To view the attributes of any send order type, click Details, or, if you are in editing mode, click Edit to view and modify the attributes. For example, you may want to define the signature mode for this order type.

Attribute Description

Name Name of the order type (3 characters)

Description Manually entered description




D-Files Response in setting up D files. Possible values:

o deny: D files are rejected

o process instantly: D-files are processed without any additional check

o release by distributed signature: Files are forward to the "distributed electronic signature"

o release manually: Files must be released manually by an administrator

Signature mode

Set the signature mode as specified by the CFONB.

Possible values:

o Normal: EBICS T profile in France. Also for other countries.

o French – Single signature: EBICS TS profile in France with only one signature allowed.

o French – Optional co-signature: EBICS TS profile in France with either one or two signatures required.

o French – Mandatory co-signature: EBICS TS profile in France with two signatures required.

Note: If EBICS TS profile is selected, DS allowed must be unchecked.

Signatures Minimum required number of signatures for authorization. If you enter a zero value, files with an electronic signature must not be submitted.

DS allowed Activate or deactivate distributed signatures.

This box must be unchecked if EBICS TS profile is selected.

Active You can deactivate an order type by unchecking this option. Inactive order types will not be shown and may not be selected in the customer's order types tab.

Standard Select this option if you want newly-created customers to be assigned this order type automatically.

Wait for feedback

Select this option if you to wait for feedback.

Handler View or select the handler type for this send order type.




Postprocessing Selection of post-processing for fully authorized orders.

l Descriptions

Select this item to view a list of all descriptive text that has been added to send and fetch transactions.

You can edit the following details of a description.

Item Description

Name Enter a name

Language Select a language from the drop-down list of languages

Prefix Send the message type prefix: send or fetch

Text Edit the text that describes the transaction

l Post-processing

Select this item to view a list of all configured post-processing chains.

Once a customer order has been fully authorized, it can be transferred to a post-processing chain. A chain is always identified by a unique name.

A processing chain consists of one or more processing steps. Every step receives inbound data, processes this data and forwards is to the next processing step, in modified form if necessary. The inbound data of the first processing step corresponds to the original file. In the detail view of a processing chain, the individual processing steps are listed in chronological order. You can change the order of the steps. Steps can be deleted, created anew and possibly configured as well.

For details of possible post-processing steps, see Post-processing steps on page 86.

l Periodical tasks

Select this item to configure regularly executed tasks. You can execute cleanup or archiving of old customer orders and delete provisional data and log entries.

Each existing scheduled task, the interface displays:

o Action: The name of the action

o Last run: The date the action was last executed

o Next run: The next programmed execution date

When you create or edit a periodical task, you complete the following fields:



Field Description

Execution mode

Enables you to select the periodicity of the action:

o Day of week

o Execution hour

o Execution minute

Last run Read only field indicates the last time the task was run.

Action Specifies which action is to be performed:

o Clean up orders: Deletes and archives old customer order files. For each order, the original file, the signatures and all log entries are archived. See corresponding section below.

After you clear an order the customer can create an order with an identical order type and order number.

o Clean up deliveries

o Clean up protocol

Clean up orders

Order older than

Together, these two attributes define how much time must have passed since the last customer action for an order before it can be cleared.

Time unit

Exported zip file

Orders are never just deleted. They must be exported at the same time. Here, you specify the name of a ZIP file into which the order data is to be exported. The file name may include substitutions of the form $(DATE format), whereby format must be a valid Java date format. For example, if C:\archive\CLEANUP-$(DATE

yyyy-MMdd).zip is specified as the file name, a ZIP file named

CLEANUP-2012-11-13.zip is generated in directory

C:\archive on 13 November 2012.

Create directories

Select this option to automatically create directories required for writing.

EBICS transaction older than

Together, these two attributes define how much time must have passed since the last EBICS customer transaction for an order before it can be cleared.

Time unit



Field Description

Incomplete order older than

Together, these two attributes define how much time must have passed since the last customer action for an order before it can be cleared.

Time unit

Clean up deliveries

Older than Together, these two attributes define how much time must have passed since the last customer action with the delivery, before it can be cleared.Time unit

Order type Order type associated with the delivery.

Clean up protocols

Older than Together, these two attributes define how much time must have passed since the last customer action using the protocol, before it can be cleared.Time unit

l Directories

If you provide external data to the customers, you must store the data in specified directories so that the EBICS Gateway Server can access it. The import rules define what happens with these files.

The Directories menu item enables you to set up and maintain import rules. You can edit existing import rules and create new ones.

When you create or edit a directory, you complete the following fields:

Field Description

Directory Specifies the directory to be searched for files to be imported.

Recurse Should sub folder also be scanned for file to import?

Filename pattern

Specifies a regular expression that is to be used to recognize files to be imported. For example, the expression ".*" means that every file in this directory is to be imported.

This file pattern should not include the folder name.

Order type Specifies for which order type an imported file is to be provided. This can be an explicitly specified order type ("FTB") or an implicit type in the form of a number i. The order type is the result of the substitution of group number i of the regular expression. For example, "0" sets the order type automatically, if the file name is identical to the order type.



Field Description

Scan interval (in sec.)

Specifies how often the directory is to be searched for new files. Before a file is imported, it must be found at least twice because it is only processed if it has not changed between two runs. After the successful import, the file is deleted from the directory.

Protocol destination

Indicates the path to the log file.

Send protocol on success

Option enables logs of successful transfers.

On error abort

Optionally, select to abort the directory search in the event of an error.

Last run Indicates the last time that the directory was searched.

Last error Description of the last error that occurred.



Field Description

Supplier Supply one file per customer

The collected file is provided to exactly one customer. In the Customer ID field, enter a fixed customer ID, or a number whose value determines which group from the regular expression contains the customer ID.

Enter:

o Customer ID

o Host ID

Supply one file per user of a customer

The collected file is provided to exactly one customer. In the Customer ID field, enter a fixed customer ID, or a number whose value determines which group from the regular expression contains the customer ID.

Enter:

o Host ID

o Customer ID

o User ID

One file for all customers

Enter:

o Host ID



Field Description

MT940 Splitter

The collected file must contain account statements. This file is split according to accounts (field 25). The parts are saved separately for each account. All customers who have STA authorizations for an account receive the corresponding statements during retrieval. Use the following settings:

o Check numbering: sort the statements by year, statement number and sheet number. Only consecutive statements are made available. Sheets with errors are written to the error file.

o Unknown accounts: If a statement contains unknown accounts, these can be ignored or provided (possibly with a warning output). If unknown but retrieved accounts are administered subsequently, the statements can be retrieved afterwards.

o Error file: If errors occur during the parsing of the input file or the check of the numbering, the incorrect data is written to this file.

MT942 Splitter

The collected file must contain transaction notes. This file is split according to accounts (field 25). The parts are saved separately for each account. All customers who have authorizations for the account statements of an account receive the corresponding statements during retrieval. Use the following settings:

o Append: If data is provided several times a day, is it concatenated, or does every file receive all transaction details of a day?

o Unknown accounts: If a note contains unknown accounts, they can be ignored or provided (possibly with a warning output). If unknown but retrieved accounts are administered subsequently, the advice notes can be retrieved afterwards.

o Error file: If errors occur during the parsing of the input file, the incorrect data is written to this file.



Field Description

Backend Feedback

The collected file contains data for the further processing of a customer order in the back-end system. If this is an error message, the file content is written to the customer log of the customer in the form of ADDITIONAL INFORMATION. Use the following settings:

o Order-PK: Group from the regular expression of the file name that refers to the database key of the customer order.

o Generate header: Select this option to generate a header line with reference to the customer order in the additional information.

o Success pattern: This regular expression is applied to the file content to distinguish whether the feedback is positive or negative.

o Write in case of success: Select this option to write additional information into the customer log in case of success.

Execute scripts

o Command: Enter the command line for executing the script

o Environment variables: Enter required environment variables for executing the script

o Mode: Enter the execution mode:

o No data

o Read file

o Modify file

o Work directory

o Temp directory

Example: Create a Fetch order type 1. Open an EBICS Gateway Server GUI session.

2. Click Start change process.

3. Click the Processing menu item, then select Fetch transactions from the context menu.

4. Click Create new order type.




Field Description

Name Enter an order type, for example OrderType: FDL.camt.xxx.cfonb240.dri

Description standard

Select this option if you want to allow the order type to any new customer.

Handler Select the Handler to be used, or accept the default "One file per Customer".

Depending on the Handler you select, the interface may display additional fields.

6. Click Save.

7. Click Terminate change on the order type page.

8. Click Terminate change on the main page.

Example: Create a Send order type 1. Open an EBICS Gateway Server GUI session.

2. Click Start change process.

3. Click the Processing menu item, then select Send Order Type from the context menu.

4. Click Create new order type.

5. Complete the fields as follows:

Field Description

Name Enter FUL.pain.001.001.02.sct for this example.

D-Files Select process immediately from the drop-down list.

Signatures Enter 0, 1 or 2 depending on the number of signatures required. 0 means "only a transport signature" and is equivalent to "no Business/responsibility signature".

Handler Select Binary files from the drop-down list.

Post processing

Select export Gateway.

6. Click Save.




Example: Create and associate a post-processing item

Create a post-processing item 1. Open an EBICS Gateway Server GUI session.

2. Click the Processing menu item, and then from the context menu, select Post processing.


4. Select Create new processing chain.


Field Example values

Name Enter Export Gateway.

Add new steps

Enter Axway Gateway Post processing.

6. Click add.

7. Specify a directory on the server for file copies and signature proofs and check the first box to request proofs.

8. Leave the script boxes blank so that the default scripts are used.

9. Click Save.



Associate the post-processing item with order type 1. Open an EBICS Gateway Server GUI session.

2. Click the Processing menu item, and then from the context menu, select Send Order Type.


4. For the order type FUL.pain.001.001.02.sct, select Edit.

5. In the Post processing field, set the value to Export Gateway.

6. Click Save.





Example: Declare supplier for fetchA supplier scans a directory and then prepares any files that are found so that the User can fetch the files or part of the files.

A supplier can split or reorganize files to fit customer requirements. For example, a large file may be split and sent to several customers who fetch from specific account numbers. When triggering the fetch, the customer retrieves only the accounts he is related to.

Procedure 1. Click Processing and then, from the context menu, select Directories.

2. Click Start change to enter editing mode.

3. Click Monitor new directory.


Field Description

Directory Enter the path to the directory you want to monitor.

File name pattern

Enter (.*)\_(.*)\_(.*)

Order type Enter 1 (first pattern matching found before the underscore).

Scan interval

Set number of seconds between scans.

Supplier Select Supply one file per customer.

Customer-Id

Enter 3.

Host-Id Enter 2.

5. Click Save.




Post-processing steps

Bulk processingThe Bulk processing step blocks the post-processing of all orders of a certain order type until a specified time is reached. Then all orders that have been blocked are concatenated into a collective file and transferred to the subsequent processing steps. If the order collector is not the first processing step of a chain, the preceding steps must not have made any changes to the data. For each processing step, only one order collector may be defined.

Bulk processing has a single attribute that takes a value:

l Start Time(s): Specifies at what time (HH:MM) blocked orders are processed. To enter multiple start times, separate the different start times with commas.

Execute scriptThe Execute script step executes a system command. It transfers the input data to the command if required. The definition of the command and optional environment variables can contain the following types of placeholder:

l $(ORDER_TYPE) Order type

l $(CHR value) Character with the specified decimal value

l $(DATE format) Current time in the Format Java format

l $(FILE) Absolute path to the data file, if a data transfer by file is requested

l $(HOSTID) Host ID of the bank. This placeholder is not available if one of the preceding processing steps was bulk processing

l $(CUSTOMER) Customer ID. This placeholder is not available if one of the preceding processing steps was bulk processing

l $(ORDER_NUMBER) Order number. This placeholder is not available if one of the preceding processing steps was bulk processing

l $(ORDER_PK) Database key of the order. This placeholder is not available if one of the preceding processing steps was bulk processing

l $(FILE_TYPE) D if the order file was sent without a signature, 0 if the order file was signed electronically and X if one of the preceding processing steps was bulk processing

l $(RESTART_POSTPROCESSING) TRUE if the post-processing is manually restarted, otherwise FALSE

If the script ends with a return value that does not equal zero, an error is logged and the processing chain is terminated.

You can specify the following properties of execute script:

l Command: The command to be executed including optional parameters. Substitutions are made as described above.



l Environment Variables: Define additional environment variables for the command in the form VAR= value. The values can contain substitutions of the above-described form.

l Data Transfer: Specifies the form in which the script expects the data. Possible values are:

o Not required: Data is not transferred to the script but sent to the next processing step without any changes

o File transfer (read only): A temporary file is generated. The name of this file can be transferred to the script using placeholder $(FILE). It is not assumed that the script modifies the file.

o File transfer (modifying): A temporary file is generated. The name of this file can be transferred to the script using placeholder $(FILE). After completing the script, the file, changed or not, is transferred to the next processing step.

o Standard input (without output): The input data is forwarded unchanged to the standard input of the script and on to the next processing step.

o Standard input and output: The input data is transferred to the standard input of the script. The standard output of the script is forwarded to the next processing step.

l Working Directory: Specifies a working directory for the script

l Data Directory: Specifies a directory for temporary files

l Line Break: Converts line breaks to a defined format. You can set whether line breaks are made in Windows or UNIX format and whether a missing line break is appended to the end of the file.

l File Export: Writes the input data into a file. The file name may contain the placeholders for script execution. File Export options:

o Output File: File name, optionally with placeholders

o Create Directories: Defines whether required directories are created automatically

o Overwrite: Defines whether already existing files may be overwritten. If not, an error is logged and the processing chain is terminated.

l Signature Export: Ignores the input data and writes the signature data to the following plug-in. Signature Export options:

o Format: This test is sent to the following plug-in for each signature including substitutions. In addition to the substitutions mentioned for script execution, the following placeholders are available:

o $(RAW) Content of the signature file (512 bytes)

o $(USER) BCS participant ID

o Technical Signatures Only: Determines whether or not transport signatures are to be exported as well



Configure back-end connection with Gateway and Transfer CFTThis procedure shows how to configure Gateway and Transfer CFT for the Server fetch and send Order Types.

1. Navigate to <EBICS Gateway dir>/server/Install/server and locate the file

obj_gateway_server_ebics.sh (or .bat for Windows).

2. Open the file in a text editor.

3. Modify the call at the beginning of the script so that the path corresponds to your Gateway installation directory.

4. Modify the following variables:

Variable Modification

remote_cft_EBICS_server_address Enter the Transfer CFT Server HostName

remote_cft_EBICS_server_port Enter the Transfer CFT Server port number

MODEL_CFT Enter pain.001.001.02.sct

5. Save the file.

6. In the same directory, locate the file cft_ebics_server.cfg.

7. Open the file in a text editor, and modify the following variables:

Variable Modification

SYST Enter the type of platform.

Example values:

l 'UNIX'

l 'WINNT'

PROT Enter 'PESITANY'

SAP Enter '6330'

HOST Enter the Gateway HostName

8. Save the file.


l UNIX: obj_gateway_server_ebics.sh

l Windows: obj_gateway_server_ebics.bat




l UNIX: CFTUTIL @cft_ebics_server.cfg

l Windows: CFTUTIL #cft_ebics_server.cfg



Configuration examplesThis section provides high-level workflows that show the steps required to set up EBICS Gateway Server.

Example: Configure EBICS Gateway ServerHere is an example of the steps you need to perform to configure EBICS Gateway Server.

1. Create a Bank.

See Example: Create a Bank on page 56

2. Create a Fetch order type.

See Example: Create a Fetch order type on page 82

3. Create a Send order type.

See Example: Create a Send order type on page 83

4. Create a Customer.

See Example: Create a Customer on page 68

5. Create a User.

See Example: Create a User on page 68

6. Create a post-processing item.

See Example: Create and associate a post-processing item on page 84

7. Grant use of an OrderType to an EBICS User.

See Example: Grant order types on page 70

8. Declare a supplier for Fetch transfer.

See Example: Declare supplier for fetch on page 85

Example: Configure EBICS Gateway Server back-end connection to Transfer CFTHere is an example of the steps required to configure EBICS Gateway Server with Transfer CFT as a back-end application. In this setup, EBICS Gateway Server links to Transfer CFT via Gateway.

1. Create a Bank.

See Example: Create a Bank on page 56

2. Create a Fetch order type.

See Example: Create a Fetch order type on page 82

3. Create a Send order type.

See Example: Create a Send order type on page 83



4. Create a Customer.

See Example: Create a Customer on page 68

5. Create a User.

See Example: Create a User on page 68

6. Create a post-processing item.

See Example: Create and associate a post-processing item on page 84

7. Grant use of an OrderType to an EBICS User.

See Example: Grant order types on page 70

8. Configure Gateway and Transfer CFT for send and fetch Order Type.

See Configure back-end connection with Gateway and Transfer CFT on page 88

9. Declare a supplier for fetch transfer.

See Example: Declare supplier for fetch on page 85



EBICS Gateway Server post-processingAbout post-processing on page 92

Gateway post-processing on page 92

API Gateway (ActiveMQ) post-processing on page 95

File naming conventions on page 98

Restart post-processing on page 99

About post-processingEBICS Gateway Server provides three integrated post-processing processes to forward files received during send transactions to Axway Gateway, Axway API Gateway (ActiveMQ), or Axway Messaging. These processes also enable you to export signatures received by EBICS Gateway Server to a dedicated XML file. The XML file can then be used by other tools to create a proof of transfer. If a transfer to Gateway, API Gateway, or Messaging fails, the post-processing can be restarted from the EBICS Gateway Server UI.

Note Post-processing with Messaging is now deprecated. It is still available, but it is not described in this documentation.

Gateway post-processingLimitation: Gateway post-processing should only be used in non-cluster environments.

OverviewHere are the different stages of the send transaction with Gateway post-processing:

1. An EBICS client sends a file to EBICS Gateway Server with a given order type and with signature(s).

2. The server decodes the send message and validates the signature(s).

3. Depending on order type, the server launches the appropriate Gateway post-processing:

l Copies file to a given directory

l Generates an XML file containing signature(s) if required

l Executes a script to call the peltrans command

4. Gateway retrieves the payload and signature files thanks to the metadata.

5. Gateway sends the file to the back-end.

Note: The data and signature files are not removed at the end of the post-processing.



Figure 5. EBICS Gateway Server post-processing with Gateway

Post-processing interaction with GatewayTo interact with Gateway, the post-processing executes a command line script. When FULorderParam is set to TEST, a different script can be called.

By default, the post-processing calls the exitPostprocessing script delivered with EBICS Gateway Server. The default script is provided in <EBICS Gateway dir>/server/Send/scripts/.

The provided scripts can be customized as required, and obtain some parameters through system properties.

List of system properties

Property Value

Bank Host ID of the bank

EbicsId EBICS Host ID of the bank

Customer ID of the customer



Property Value

UserId ID of the user.

If multiple users signed the file, the additional users will be identified by the Signer[n] properties, with Signer1 being this user, and Signer2+ being the additional users.

OrderNumber Order number of the send transaction

OrderTypeBL Concatenation of send order type and file format. Example: FUL.pain.xxx.400.vct (OrderType.FileFormat)

TestParam TRUE if the order parameters contain TEST, otherwise FALSE

Filename Name of the data file.

For more information about the file name, see File naming conventions on page 98.

AbsoluteFilePath Canonicalized path to the data file

SignatureFilename Name of the signature file

AbsoluteSignatureFilePath Canonicalized path to the signature proof file

NbOfSignatures Number of signatures present on the data file

EBICSROOT Path of the EBICS Gateway Server installation

TRACKINGOBJECT Name of the Tracking Object used to notify Sentinel

SentinelCycleID Sentinel Cycle ID of the notification

RESTART_POSTPROCESSING

TRUE if the post-processing is manually restarted, otherwise FALSE

Configure post-processing with GatewayYou configure the Gateway post-processing in the same way as any other post-processing, via the menu Processing > Post processing. For an example, see Example: Create and associate a post-processing item on page 84.

Complete the following fields:

Field Description

File directory Path to the directory where the sent file is to be copied



Field Description

Export signature proof Check this box if you want to export the signature file

Signature proof directory

Path to the directory where the signature files are to be dumped

UserId Add User ID into the name of the file and signature file

Gateway transfer launching script

Path to the script to run. If empty, the default script is used.

Gateway transfer launching script if TEST parameter is set

Path to the script to run when sent with test parameter. If empty, the default script is used.

API Gateway (ActiveMQ) post-processing

OverviewThere are multiple stages when processing a send transaction with API Gateway (ActiveMQ) post-processing:

1. An EBICS client sends a file to EBICS Gateway Server with a given order type and with signature(s).

2. The server decodes the send message and validates signature(s).

3. The server recognizes that the order type is to be processed by API Gateway, launches the post-processing, and performs the following steps:

l Copies the payload file to the configured directory

l Generates an XML file containing the signature(s) if configured

l Sends a JMS message to the configured receiver

4. The receiver retrieves the message from API Gateway for further processing.

5. The receiver retrieves the data and signature files from disk as needed using the JMS metadata fields provided in the message.

6. Integrator or Gateway sends the file to the back-end.

Note: The receiving process is responsible for the removal of the data and signature files.



Figure 6. EBICS Gateway Server post-processing with API Gateway / ActiveMQ

List of properties

Property Value

Bank Host ID of the bank

EbicsId EBICS Host ID of the bank

Customer ID of the customer

UserId ID of the user.

If multiple users signed the file, the additional users will be identified by the Signer[n] properties, with Signer1 being this user, and Signer2+ being the additional users.

OrderNumber Order number of the send transaction

OrderTypeBL Concatenation of send order type and file format.Example: FUL.pain.xxx.400.vct (OrderType.FileFormat)

OrderType Send order type. Example: FUL



Property Value

FileFormat Send file format. Example: pain.xxx.400.vct

TestParameter TRUE if the order parameters contain TEST, otherwise FALSE

OP_<CUSTOM> If any custom order parameters were set, they will be available by adding the prefix "OP_". For example, if an EBICS Gateway Client set the custom order parameter MYPARAM, it will be accessible through the property OP_MYPARAM.

Filename Name of the data file.

For more information about the file name, see File naming conventions on page 98.

DirectoryName Directory containing the data file.

Default = ${mft_home_dir}/Send/tmp/files

mft_home_dir is set via the Installer and is stored in the configuration.properties file.

AbsoluteFilePath Canonicalized path to the data file

Type Transport type of file (T = Transport, TS = Transport with signature)

SignFilename Name of the signature proof file

SignDirectoryName Directory containing the signature proof file.

Default = ${mft_home_dir}/Send/tmp/files

mft_home_dir is set via the Installer and is stored in the configuration.properties file.

AbsoluteSignFilePath Canonicalized path to the signature proof file

NbOfSignatures Number of signatures present on the data file

Signer[n] User ID of each signer present on the data file

TrackingObject Name of the Tracking Object used to notify Sentinel

SentinelCycleID Sentinel Cycle ID of the notification

ServerDate Timestamp in milliseconds (UNIX format) of when the JMS message was created by EBICS Gateway Server

SenderIdentifier Identification of the JMS message originator, always set to "EBICS_ExitPostProcessing"

ProcessingRestarted TRUE if the post-processing was manually restarted, otherwise FALSE



Configure post-processing with API Gateway (ActiveMQ)You configure the ActiveMQ post-processing in the same way as any other post-processing, via the menu Processing > Post processing. For an example, see Example: Create and associate a post-processing item on page 84.

Complete the following fields. The only mandatory fields are: Protocol URI and Queue name.

Field Description

File directory Path to the directory where the sent file is to be copied

Export signature proof

Check this box if you want to export the signature file

Signature proof directory

Path to the directory where the signature files are to be dumped

UserId Add User ID into the name of the file and signature file

Protocol URI URL address that provides the required information to connect to the ActiveMQ server. Examples:

tcp://localhost:61616

failover:(tcp://Host1:Port1,tcp://Host2:Port2)

User Name of the ActiveMQ technical user. This must be filled only if security is activated in ActiveMQ

Password Password of the ActiveMQ technical user. This must be filled only if security is activated in ActiveMQ

Queue name Name of the reception Queue inside the Queue manager of ActiveMQ server

File naming conventionsPost-processing using Gateway, API Gateway (ActiveMQ), or Messaging copies data files and signature files to a local folder with the same naming convention.

The naming convention for the data file is:

ORDERTYPE_ORDERNBR_USERID_CUSTID_EBICSHOSTID_DATE_TEST



The naming convention for the signature file is:

ORDERTYPE_ORDERNBR_USERID_CUSTID_EBICSHOSTID_DATE_TEST.signature

Notes:

l USERID is set only if the option Add UserId is checked.

l TEST is not set if test mode is not activated (FULorderParam)

Restart post-processingIf a post-processing process has failed, you can restart it from the UI.

Restart post-processing from the UIFrom the UI, you can restart post-processing on all files that have been received with the status "terminated" or "error".

1. In the Files menu, select a post-processing process you want to restart and click the Detail button.

2. Click Add an Administrative remark.

3. Enter a meaningful remark.

4. Select action: Set state to "finished" and do post-processing (again).

5. Finally, click the Add an Administrative remark button.



Manage administrator usersIn EBICS Gateway Server, all user administration is done through Axway PassPort.

You can define roles and assign individual logins for the administrative access to the EBICS Gateway Server. The assignment of roles makes it possible to define access to the configuration of the EBICS application server in different ways.

User administration distinguishes between administrators, groups, and permissions.

PermissionsThe permissions that you can grant in the system are predefined. Every right describes an action that an administrator is allowed to execute via a permission. Rights always signify permissions. If a right is not available, this means that the corresponding action cannot be executed.

GroupsA group represents a collection of rights. A group can be assigned any number of rights. In the assignment of rights, groups are used for collecting and structuring authorizations. It makes sense to create a group for every work center profile. For example, a group for Hotline, Customer Support, Administrator and so on. The users are then assigned to one or more groups and thus receive the required authorizations. The authorizations of different groups are added up so that a user receives the sum of all authorizations of his or her groups. This makes it easy to create super administrators who are simply members of all groups and thus receive all rights.

When you create a new group, you complete the following fields:

l Name: A display name for the new group that is used at different points in the program.

l Permissions: All installed permissions are displayed. For each group, you define the permissions that the members of this group should receive.

The following permissions are available for groups:

EBICS Gateway Client permissions

Permission Description Technical name

EBICS client Unique and complete privileges on the EBICS Gateway Client application

EBICS_CLIENT

Note: EBICS Gateway Client has only one, single role. Any privileges granted to a user will allow all actions to all objects inside the EBICS Gateway Client GUI.



EBICS Gateway Server permissions


Create and edit accounts

With this right, in addition to the View accounts and Edit and delete accounts right, you can also create new accounts.

ACCOUNT_CREATE

Edit and delete accounts

With this right, in addition to the View accounts right, you can change or delete existing accounts.

ACCOUNT_EDIT

View accounts With this right, the Accounts menu item is displayed. ACCOUNT_READ

Create and edit banks

With this right, in addition to the View banks and Edit and delete banks right, you can also create new banks.

BANK_CREATE

Edit and delete banks

With this right, in addition to the View banks right, you can change or delete existing banks.

BANK_EDIT

Create PTK entry for all customers of a bank

With this right, the user may create PTK entries for all customers of a bank.

BANK_PTK

View banks With this right, the Banks menu item is displayed. BANK_READ

Create descriptions

With this right, in addition to the rights View descriptions and Edit and delete descriptions, the user can create descriptions.

BUNDLE_CREATE

Edit and delete descriptions

With this right, in addition to the right View descriptions, the user can change or delete descriptions.

BUNDLE_EDIT

View descriptions

With this right, the user can display the descriptions. BUNDLE_READ

Create and edit postprocessing chains

With this right, in addition to the View postprocessing chains and Edit and delete postprocessing chains right, you can also create new post-processing chains.

CHAIN_CREATE

Edit and delete postprocessing chains

With this right, in addition to the View postprocessing chains right, you can change or delete existing post-processing chains.

CHAIN_EDIT




View postprocessing chains

With this right, the Postprocessing Chain menu item is displayed.

CHAIN_READ

Create and edit customer and user related data

With this right, in addition to the View customer and user related data and Edit and delete customer and user related data right, you can also create new customers.

CUSTOMER_CREATE

Edit and delete customer and user related data

With this right, in addition to the View customer and user related data right, you can change or delete existing customers. This includes the complete configuration of the customers, the participants and the account authorizations. The files of a customer and the customer log can also be displayed. This is independent of the View orders right.

CUSTOMER_EDIT

Create PTK entry for a customer

With this right, the user may create PTK entries for a customer.

CUSTOMER_PTK

View customer and user related data

With this right, the Customers menu item is displayed. CUSTOMER_READ

Create and edit EBICS Users

With this right, in addition to the View EBICS Users and Edit EBICS Users right, you can also create new Users.

CUSTOMER_USER_CREATE

Edit and delete EBICS Users

With this right, in addition to the View EBICS User right, you can change or delete existing users. This includes the complete configuration of the users, the participants and the account authorizations.

CUSTOMER_USER_EDIT

View EBICS Users With this right, the Users menu item is displayed. CUSTOMER_USER_READ

Create and edit fetch order types

With this right, in addition to the View fetch order types and Edit and delete fetch order types right, you can also create new fetch order types.

FETCH_CREATE

Edit and delete fetch order types

With this right, in addition to the View fetch order types right, you can change or delete existing fetch order types.

FETCH_EDIT

View fetch order types

With this right, the Fetch Order Types menu item is displayed.

FETCH_READ




Four-Eyes-Permission

This right authorizes the user to make all changes autonomously. If a user does not have this right, all changes must be confirmed by another user.

FOUR_EYES_COMMIT

Commit changes With this right, the Processing Operations menu item is displayed. Only users with this right can confirm changes made by other users.

FOUR_EYES_READ

Create and edit groups

With this right, in addition to the View groups and Edit and delete groups right, you can also create new groups.

GROUP_CREATE

Edit and delete groups

With this right, in addition to the View groups right, you can change or delete existing groups.

GROUP_EDIT

View groups With this right, the Groups sub-menu item of the User Administration menu is displayed. You also need to have the View administrators right.

GROUP_READ

Lock user With this right, the user is allowed to lock participants. LOCK_USER

View logs With this right, the Log menu item is displayed. It gives a user direct access to the log.

LOG_READ

Download order files

This right enables you to download files transferred by customers to your own computer via the administration pages.

ORDER_DOWNLOAD

Edit orders This right enables you to change the status of files and to start manual post-processing.

ORDER_EDIT

View orders With this right, the Files menu item is displayed. ORDER_READ

Create and edit schedulers

With this right, in addition to the View schedulers and Edit and delete schedulers right, you can also create new periodical tasks.

SCHEDULER_CREATE

Edit and delete schedulers

With this right, in addition to the View schedulers right, you can change or delete existing periodical tasks.

SCHEDULER_EDIT

View schedulers With this right, the Periodical Tasks menu item is displayed.

SCHEDULER_READ




Create and edit send order types

With this right, in addition to the View send order types and Edit and delete send order types right, you can also create new send order types.

SEND_CREATE

Edit and delete send order types

With this right, in addition to the View send order types right, you can change or delete send order types.

SEND_EDIT

View send order types

With this right, the Send Order Types menu item is displayed.

SEND_READ

Create and edit directories

With this right, in addition to the View directories and Edit and delete directories right, you can also create new directory monitoring-instances.

SUPPLY_CREATE

Edit and delete directories

With this right, in addition to the View directories right, you can change or delete existing directory monitoring instances.

SUPPLY_EDIT

View directories With this right, the Directory Monitoring menu item is displayed.

SUPPLY_READ

Create and edit administrators

With this right, in addition to the View administrators and Edit and delete administrators right, you can also create new users.

USER_CREATE

Edit and delete administrators

With this right, in addition to the View administrators right, you can change or delete existing users.

USER_EDIT

View administrators

With this right, the User Administration menu item is displayed. The sub-menu item Users is also displayed.

USER_READ

Reset Password This right allows to reset passwords. USER_RESET_PW

Web Administration

Everyone who wants to log on to the Web Administration needs to have this right. Without this right, logging on is not possible.

WEBLOGIN

Delete orders of a customer

With this right, the user may delete all order files of a customer.

ORDER_DELETE_ALL

Restart schedulers

Allows the user to restart the task immediately SCHEDULER_RESTART




Take over change processes

Allows one Administrator to validate/cancel Change Processes of other Administrators.

CP_TAKEOVER

Show account statements

This right allows to show account statements. It is only used within the optional Account Statements module.

ACCOUNT_STMT_VIEW

Administrator (specific to EBICS Gateway Server)An administrator corresponds to exactly one operator who can log on to EBICS Gateway Server. You identify an administrator user through a unique identification and password. Administrators can be members of several groups. Through this membership, an administrator receives all of the rights that are available to the group.



EBICS security services via PassPort

OverviewEBICS Gateway Server uses the security services of Axway PassPort for:

l Storage:

o Bank certificates and associated private keys for authentication and encryption

o User certificates for authentication, encryption and signatures

l Validation:

o Bank encryption certificates when the bank deciphers messages

o Bank authentication certificates when the bank authenticates messages

o User signature certificates during verification of the user signatures

o User authentication certificates during user authentication

o User encryption certificates when messages are deciphered

l Signing

o Messages

o Authentication operations

l Deciphering of messages

l User registration

Set up communication between EBICS Gateway Server and PassPortTo enable exchanges between EBICS Gateway Server and PassPort, you must execute tasks on both products:

l In the PassPort user interface, Create a Technical user for EBICS Gateway Server in PassPort on page 107

l Working on the machine where you installed EBICS Gateway Server, EBICS Gateway Server configuration file on page 187

In addition, you must:

l Create Business users for EBICS in PassPort on page 110



Configure exchangesAdministrative users of the EBICS Gateway Server manage security through its interface. In normal operations, there is no need for any direct action in PassPort. The PassPort user interface and its associated tools are only necessary when an exceptional maintenance action or repair is necessary.

Typical tasks for configuring EBICS exchange security:

l Create a new bank with private and public keys on page 111

l Create a new bank with imported certificates on page 113

l Delete a bank and associated certificates on page 115

l Create a customer on page 116

l Delete a customer on page 117

l Delete a user on page 118

l Release user keys on page 118

l Release user certificates on page 119

Create a Technical user for EBICS Gateway Server in PassPortIn PassPort you must create a dedicated user that the EBICS Gateway Server can use to connect to PassPort.

In the PassPort user interface, perform the following actions to create an EBICS Gateway Server user:

l Select or create a domain on page 107

l Select or create a new organization on page 108

l Create a user on page 108

l Change the user password on page 109

l Assign a role to the user on page 109

For detailed information about domains, organizations and users, refer to the Axway PassPort documentation.

Select or create a domainYou can create a user in the default domain of PassPort or in a dedicated domain. The default domain is Synchrony.

Alternatively, you can create a new domain.

1. Open a PassPort management session and in the main page, select Access > Users and organizations.



PassPort opens the Users and organizations management screen.

2. On the toolbar, click the New domain icon.

PassPort displays the New domain configuration screen.

3. Complete the fields of the New domain configuration screen.

4. Click OK.

Select or create a new organizationThe user for EBICS Gateway Server must be located in a PassPort organization. You can create the user in an existing organization or create a new organization. If you created a new domain for your user in the previous procedure, you now must create a new organization in that domain.

To create a new organization:

1. Open a PassPort management session and in the main page, select Access > Users and organizations.


2. Select a domain from the displayed list of domains, then on the toolbar click the New organization icon.

PassPort displays the New organization configuration screen.

3. In the New organization configuration screen, enter a name for the organization, and set the Status option to Active.

4. Click OK.

Create a user 1. Open a PassPort management session and in the main page, select Access > Users and

organizations.


2. Select the organization under which you want the user and then on the toolbar, click the New user icon.

PassPort displays the New user configuration screen.

3. In the New user configuration screen, enter a user ID and complete the remaining fields. Make sure the user email address is correct. The server requires this address when sending messages. The email address is used to send the user password at creation time and whenever an administrator resets the password.

4. Set the User status to Active.

5. Click OK.



Change the user passwordWhen you create a new user, PassPort sends an email containing the access password to the address that you specified when you created the user.

To modify this password:

1. Open a PassPort management session using the username and default password of the user you just created.

2. For this first login, PassPort displays a screen that invites you to change the password for the user.

3. Enter a new password and click OK.

Assign a role to the userAn EBICS user must possess specific rights to connect to PassPort. You assign user roles in the PassPort Security Manager.

1. Open a PassPort management session and in the main page, select Access > Authorization.

PassPort opens the Authorization management screen.

2. In the tree menu, select Predefined roles > Security manager.

3. In the right pane, click the User tab.

4. On the toolbar, click the Add users to role icon.

PassPort opens the Add users to role window.

5. Use the search fields to search for the EBICS user.

6. Select the EBICS user from the search results list, and click Add users.

PassPort adds the selected user to the Security manager role.

Business usersYou also need to create Business users as described in the next section.



Create Business users for EBICS in PassPort

IntroductionThis section provides guidance for the creation of Business users for EBICS. For more information, refer to the Axway PassPort documentation.

EBICS Business usersIn order to connect to the EBICS Gateway Server, EBICS users created in PassPort require a role. Optionally they can also belong to a group.

PrivilegesA privilege is a combination of a resource and one or many actions related to this resource. It creates an object usable for roles to define a right. This object can have conditions.

By default, a list of privileges is delivered with the CSD (Component Security Descriptor) file.

RolesA role is a set of privileges. The role gives permissions to a user. A role can be assigned to a user or a group.

GroupsA group is a set of users. A group may have one or more roles.

In the EBICS implementation, groups are only used for bank restrictions. However they can also be used for other purposes.

UsersA user in PassPort belongs to a domain. By default there is only one domain: Axway. In order to use these users, they must have at least one role. In addition they can belong to one or more groups.

According to the password policy, the user’s password can be one of:

l Equal to the userId

l A default password

l A generated password sent to the user by mail



How to create a Business user 1. Create a privilege.

2. Create a role.

3. Create a group.

4. Create a user.

For more information, refer to the Axway PassPort documentation.

Create a new bank with private and public keysThis procedure describes how to create a new bank in EBICS Gateway Server with generated key pairs for encryption and authentication.

Prerequisites l EBICS Gateway Server is configured to communicate with PassPort.

l You have the required permissions to create bank logs in the EBICS Gateway Server user interface.

Procedure 1. Open a session in the EBICS Gateway Server administration interface.

2. In the EBICS Gateway Server user Interface, select the Banks menu item.



Field Description

Name Enter a unique name that is used to identify a bank at various points in the administration interface.


Long IDs Select this option to activate the use of the updated EBICS 2.4 standard for character length.

EBICS support

Select this option to enable EBICS support for the new bank.

EBICS Host-ID

Enter the bank EBICS identifier.



Field Description

URL Enter https://<hostname>:<port>/ebics/EbicsServlet

Where <port> depends on the port configuration of the EBICS Gateway Server.


Import PKCS12 file

Do not select this option.

Protocol versions

Select the EBICS standard version you intend to use for exchanges between the bank and remote client.

l H002 (EBICS 2.3)

l H003 (EBICS 2.4)

Signature versions

Select the EBICS public key signature versions you intend to use for exchanges between the bank and remote clients.

l A004

l A005

l A006

Force certificates


5. Click Save.


ResultsEBICS Gateway Server creates a new bank object.

EBICS Gateway Server creates an entity in PassPort with the following parameters:

l name = [business ID of bank] :HostID

l location = local

l isTrusted = true



EBICS Gateway Server generates the following RSA public keys and their corresponding private key in PassPort:

l cert 1

o name = XXX:auth

o state = AVAILABLE

l cert 2

o name = XXX:enc

o state = AVAILABLE

The PassPort entity is trusted, therefore the created certificates are trusted. This means that the certificates are used as a Trust Anchor.

Create a new bank with imported certificatesThis procedure describes how to create a new bank in the EBICS Gateway Server with imported X.509 certificates and RSA private keys for encryption and authentication.

Prerequisites l The EBICS Gateway Server is configured to communicate with PassPort.

l You have rights to create banks logs in the EBICS Gateway Server user interface.


2. In the EBICS Gateway Server User Interface, select the Banks menu item.



Field Description

Name Enter a unique name for the new bank.


Long IDs Select this option to activate the use of the updated EBICS 2.4 standard for character length.

EBICS support

Select this option so that the EBICS Gateway Server automatically generates the keys required for EBICS encryption.



Field Description

EBICS Host-ID

Enter the bank EBICS identifier.

URL Enter https://<hostname>:<port>/ebics/EbicsServlet

Where <port> depends on the port configuration of the EBICS Gateway Server.


Import PKCS12 file

Select this option to import a PKCS#12 file to store private keys with accompanying public key certificates.

Encryption key

Enter the path to the PKCS#12 file you want to import.

File password

Enter the password for access to the encryption key file.

Authentication key

Enter the path to the PKCS#12 file you want to import.

File password

Enter the password for access to the signature key file.

Protocol versions

Select the EBICS standard version you intend to use for exchanges between the bank and remote client.

l H002

l H003

Signature versions

Select the EBICS signature versions you intend to use between the bank and remote clients.

l A004

l A005

l A006

Force certificates


5. Click Save.




ResultsThe EBICS Gateway Server creates an entity in PassPort with the following parameters:

l name = [business ID of bank]:HostID

l location = local

l isTrusted = false

The EBICS Gateway Server parses the PKCS#12 files and generates the following certificates in PassPort:

l cert 1

o name= XXX:auth

o state = AVAILABLE

l cert 2

o name = XXX:enc

o state = AVAILABLE

Because the PassPort entity is trusted, the created certificates are trusted. This means that the certificates are used as a Trust Anchor.

Delete a bank and associated certificatesThis procedure describes how to delete a bank in the EBICS Gateway Server with associated certificates and key.

Prerequisites l EBICS Gateway Server is configured to communicate with PassPort.

l You have rights to create banks logs in the EBICS Gateway Server user interface.


2. Select the Banks menu item.

3. Select an existing bank and click Delete.

4. Click Save.




ResultsThe EBICS Gateway Server:

l Deletes the bank object in EBICS Gateway Server.

l Deletes the customer and user object related to the bank.

l Deletes the entity in PassPort that represents the bank, along with all certificates and keys that belong to that entity.

l Deletes the entity in PassPort that represents the customer, along with all certificates and keys that belong to the related users.

Create a customerThe customer object represents a remote client that exchanges messages with a bank.

This procedure describes how to create a new customer, that you associate with a bank for a secured exchange.


l You have rights to create banks and change customers in the EBICS Gateway Server user interface.


2. Navigate to the Customers menu and click Start change process.

3. Select the Create new customer.


Field Description

Customer ID

Enter a valid customer ID.

Name Enter a customer name.

Bank Enter the ID of the bank with which you want to configure a secure exchange.

5. Click Save.




ResultsThe EBICS Gateway Server creates a new customer object.

The EBICS Gateway Server creates an entity in PassPort with the following parameters:

l name = CustomerID:[business ID of customer]

l location = remote

l isTrusted = false

Delete a customerThis procedure describes how to delete a customer in the EBICS Gateway Server.


l You have rights to create banks in the EBICS Gateway Server user interface.


2. Navigate to the Customers menu and click Start change process.

3. Select an existing customer and click Delete.

4. Click Save.


ResultsThe EBICS Gateway Server:

l Deletes the customer object in EBICS Gateway Server

l Deletes the entity in PassPort that represents the customer, along with user certificates and keys.



Delete a userThe user object is a child object of a customer object. It represents an account of a remote client that exchanges messages with a bank.

This procedure describes how to delete a user with its associated certificates, belonging to a preexisting customer.


l You have rights to create banks and change customers in the EBICS Gateway Server user interface.

l A customer and a user exist, named respectively CUSTOMER1 and USER1 for this example.


2. Navigate to the User menu and click Start change process.

3. Select User1 (for this example) and select Delete.

4. Click Save.


ResultsThe EBICS Gateway Server deletes USER1.

The EBICS Gateway Server deletes in PassPort, all certificates and keys based on CUSTOMER1/USER1.

Release user keysThe user object is a child object of a customer object. It represents an account of a remote client that exchanges messages with a bank.

This procedure describes how to release the keys of a user that have been sent to the server.



l A remote client has successfully sent its keys to an EBICS bank server.





3. Select User1 (for this example) and select Edit.

4. Select the Channel tab.

5. Click Release.

6. Click Save.


ResultsThe EBICS Gateway Server changes the user state to Released.

The EBICS Gateway Server sets the public keys of the entity that represents CUSTOMER1/USER1 in PassPort to Available.

Release user certificatesThe user object is a child object of a customer object. It represents an account of a remote client that exchanges messages with a bank.

This procedure describes how to release the certificates of a user that have been sent to the server.



l A remote client has successfully sent its keys to an EBICS bank server. .



3. Select User1 (for this example) and select Edit.

4. Select the Channel tab.

5. Click Release.

6. Click Save.




ResultsThe EBICS Gateway Server changes the user state to Released.

The EBICS Gateway Server builds and validates paths to the certificates of the entity that represents CUSTOMER1/USER1 in PassPort.

The EBICS Gateway Server sets the status of certificates belonging to the entity that represents CUSTOMER1/USER1 in PassPort to Available and the trust level to Trusted.

EBICS Gateway Server TLS configurationAt installation time, EBICS Gateway Server is set to accept only TLS 1.2 connections, with safe cipher suites. This corresponds to today’s best practice, and offers you safe connections over the internet. For some of the outbound connections, you still need to set up TLS security manually.

In some cases, for compatibility reasons, you might need to lower the TLS security level of EBICS Gateway Server.

Relax or restrict the security of TLS versionsThis section applies to the WildFly and EAP implementations of EBICS Gateway Server. It does not apply to the WebSphere implementation of EBICS Gateway Server.

This version of EBICS Gateway Server provides only TLS version 1.2 connections by default. However, the embedded application server can either be set to relax the security of TLS by allowing older and less secure TLS connections, or set to restrict the TLS version to 1.2 only.

Note All other application servers must be set correctly by the customer.

l Embedded application server on page 120

l EAP on page 122

Embedded application server 1. Edit the following section of the standalone.xml file, located in

EbicsGateway\server\EmbeddedServer\standalone\configuration:

<subsystem xmlns="urn:jboss:domain:undertow:1.1" default-virtual-

host="internalhost">

<buffer-cache name="default"/>

<server name="default-server" default-host="internalhost">

<https-listener name="https" socket-binding="https" security-

realm="ApplicationRealm" enabled-cipher-suites="TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_

SHA,TLS_RSA_WITH_AES_128_CBC_SHA" enabled-protocols="TLSv1.2"/>



<host name="internalhost" alias="item-a20757"/>

</server>

<servlet-container name="default">

<jsp-config/>

<session-cookie http-only="true" secure="true"/>

</servlet-container>

</subsystem>

2. The enable-protocols parameter can be modified to relax security. The parameter accepts a list with the following enabled-cipher-suites values : TLSv1, TLSv1.1, TLSv1.2. You must change the values in three different entries in the configuration file which corresponds to the three different ports (GUI, EBICS protocol connections and EBICS Gateway Tools):

<subsystem xmlns="urn:jboss:domain:undertow:1.2" default-virtual-

host="ebics-admin-host" default-server="ebics-admin-server">

<buffer-cache name="default"/>

<server name="ebics-admin-server" default-host="ebics-admin-host">

<https-listener name="https-ebics-admin" socket-binding="https-ebics-admin" security-realm="ApplicationRealm" enabled-cipher-suites="TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA" enabled-protocols="TLSv1.2"/>

<host name="ebics-admin-host">

<location name="/" handler="admin-redirect"/>

</host>

</server>

<server name="ebics-protocol-server" default-host="ebics-protocol-

host">

<https-listener name="https-ebics-protocol" socket-binding="https-ebics-protocol" security-realm="ApplicationRealm" enabled-cipher-suites="TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA" enabled-protocols="TLSv1.2"/>

<host name="ebics-protocol-host">

<location name="/" handler="disable"/>

</host>

</server>

<server name="remote-ejb" default-host="remote-ejb-host">

<https-listener name="https-remote-ejb" socket-binding="https-remote-ejb" security-realm="ApplicationRealm" enabled-cipher-suites="TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA" enabled-protocols="TLSv1.2"/>

<host name="remote-ejb-host">



<location name="/" handler="disable"/>

</host>

</server>

<handlers>

<file name="admin-redirect" path="${jboss.home.dir}/handlers/admin-

redirect"/>

<file name="disable" path="${jboss.home.dir}/handlers/disable"/>

</handlers>

<servlet-container name="default">

<jsp-config/>

<session-cookie http-only="true" secure="true"/>

</servlet-container>

</subsystem>

EAP 1. Edit the following section of the domain.xml file, located in

EbicsGateway\server\EmbeddedServer\domain\configuration:

<subsystem xmlns="urn:jboss:domain:modcluster:1.2">

<mod-cluster-config proxy-list="lfex-cluster-a01:7777"

advertise="false" connector="https">

<dynamic-load-provider>

<load-metric type="busyness"/>

</dynamic-load-provider>

<ssl password="axway12345" certificate-key-

file="/home/fex/sharedFileSystem/security/ebicsserver.keystore" cipher-suite="TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_128_CBC_SHA"

protocol="TLSv1.2" ca-certificate-file="/home/fex/sharedFileSystem/security/ebicsserver.truststore"/>

</mod-cluster-config>

</subsystem>

2. Set the cipher-suite parameter to restrict only secured cipher suites.

3. Change the protocol parameter to TLSv1.2, but note that this value is dependent on the JVM used and the load balancer used; make sure they support it. For example, if Apache is used with its load balancer, check that TLSv1.2 is present in the httpd.conf file in

Apache/httpd/conf directory:

SSLProtocol TLSv1.2

SSLProxyProtocol TLSv1.2



4. In the same file, make sure that the correct cipher suites are set (SSLCipherSuite and SSLProxyCipherSuite parameters).

5. Change the protocol value of the ssl protocol parameter to TLSv1.2 in both the host-

master.xml and host-slave.xml files:

<security-realms>

<security-realm name="ManagementRealm">

<server-identities>

<ssl protocol="TLSv1.2">

<keystore

path="/home/fex/sharedFileSystem/security/ebicsserver.keystore"

keystore-password="axway12345" key-password="axway12345"/>

</ssl>

</server-identities>

<authentication>

<truststore

path="/home/fex/sharedFileSystem/security/ebicsserver.truststore"

keystore-password="axway12345"/>

<local default-user="$local" skip-group-loading="true"/>

<properties path="mgmt-users.properties" relative-

to="jboss.domain.config.dir"/>

</authentication>

<authorization map-groups-to-roles="false">

<properties path="mgmt-groups.properties" relative-

to="jboss.domain.config.dir"/>

</authorization>

</security-realm>

<security-realm name="ApplicationRealm">

<server-identities>

<ssl protocol="TLSv1.2">

<keystore

path="/home/fex/sharedFileSystem/security/ebicsserver.keystore"

keystore-password="axway12345" key-password="axway12345"/>

</ssl>

</server-identities>

<authentication>

<jaas name="bankrechner"/>

</authentication>

</security-realm>

</security-realms>



Encrypt data at rest in EBICS Gateway ServerFor confidentiality needs, you might want to encrypt the stored data. EBICS Gateway Server now handles the standard W3C XML encryption format. This can be configured through the installer.

EBICS Gateway Server behavior on encryption on page 124

Interoperability with backend on page 125

How to set up encryption for test on page 125

How to set up encryption for production on page 128

EBICS Gateway Server behavior on encryptionWhen XML encryption is enabled, EBICS Gateway Server proposes the following behavior.

l On all inbound flows (payload sent by the customers):

o All payloads received from customers are encrypted using XML encryption before being stored on disk.

o EBICS Gateway Server automatically decrypts the payload on-the-fly when it needs to read it (if you ask through the GUI to either view or download the payload, or if a post-processing needs to read the payload to apply a rule).

l On outbound flows (payload to be fetched by customers):

o Payload can be supplied XML encrypted or not.

o EBICS Gateway Server will detect the XML encryption state of the payload to fetch and will either decrypt the supplied XML encrypted payload on-the-fly before sending it to the customer (on fetch request), or send it "as is" if it is not XML encrypted.

o EBICS Gateway Server handles encryption only on two Axway fetch handlers: Axway Generic Fetch Transaction and Axway Generic Zip Fetch Handler.

o For other fetch handlers, the payload will be sent "as is", without any attempt to decrypt.

When XML encryption is not set, the payload is not encrypted on inbound flows, and no attempt to decrypt is done on outbound (or inbound) flows.

XML encryption encrypts the payload with a public key, and envelops the encrypted payload with information that indicates how to decrypt the payload (what key/certificate and algorithms were used to encrypt).

To be able to read the XML encrypted payload, the reading application must know how to handle XML encryption and the algorithms stated in the envelope and it also must have access to the private key matching the certificate/public key also mentioned in the envelope.



As EBICS Gateway Server needs to decrypt itself the payload it encrypted on inbound flow (to be able to display the payload to the logged in user, or for post-processing analysis…), and the next application on the chain needs also to read it, the private key must be owned by multiple applications inside a given area. We’ll call this area the community. So the certificate/private key used for payload encryption in this area will be called the community encryption credentials.

On outbound flows, EBICS Gateway Server will only be able to decrypt payload that was encrypted with credentials for which it is configured. So applications supplying payload to the server must encrypt the payload with the proper community key (or not encrypt it).

Interoperability with backendEBICS Gateway Server performs XML encryption using a given structure. The encrypted files supplied to the server must follow the same structure, so that the server can recognize them as being encrypted.

As illustrated below:

l The default namespace must be xmlns="urn:ebics:payload"

l <PayloadData> must be present. It is the parent element of the standard W3C

<EncryptedData> structure representing the encrypted data

<?xml version="1.0" encoding="UTF-8"?>

<Payload xmlns="urn:ebics:payload">

<PayloadData>

<xenc:EncryptedData xmlns:xenc="http://www.w3.org/2001/04/xmlenc#"

Type="http://www.w3.org/2001/04/xmlenc#Content">

..........

</xenc:EncryptedData>

</PayloadData>

</Payload>

When the XML encryption functionality is enabled, EBICS Gateway Server is able to handle both encrypted and unencrypted payloads. The applications in the community should have the same flexibility.

See Distribute the community encryption credential on page 129 to understand how to handle the encryption/decryption credentials inside the community.

How to set up encryption for testFor test purposes, a ready-to-go configuration is provided at installation time. This is convenient for testing, but cannot be used in production.

To enable XML encryption, all you need to do is check the option Encrypt data at rest using XML Encryption in the installer, and leave the default values.

To stop encrypting data, you just need to uncheck Encrypt data at rest using XML Encryption.



The default encryption and signature algorithms match current industry standards, and should offer a good level of security. But you can change them if you have specific needs.

EBICS Gateway Server configuration fileIn EBICS Gateway Server, all configuration parameters are stored in the configuration.properties file, located in the conf directory. Below is an extract of this file showing the Encryption of Data at Rest section with the default encryption values. It also documents all possible values. Refer to the file whenever you need to tune the encryption.

Notes:

l The encryptionMethod, keystore, ksPassword, truststore, tsPassword, keyAlias, recipientAlias, and keyPassword parameters should only be set using the Configure function of the installer (or you will lose them next time you run the installer's Configure function).

l The configuration file is read at startup. So any change will take effect only after restarting EBICS Gateway Server.

################################

# Encryption of Data at Rest #

################################

#

# This section defines the security parameters to apply for Encryption/Decryption

of data at rest.

# TrustStore credentials are used for Encryption, while KeyStore credentials are

used for Decryption.

#

# All parameters are mandatory, and Property keyword must be typed as is (case

sensitive).

#

# encryptionMethod= [NONE | XMLEncryption], if NONE, all other parameters are

ignored

# keystore= <filename of the keystore to use>

# ksType= <keystore type: JKS>

# ksPassword= <password used to access the keyStore>

# keyAlias= <alias used to retrieve the private key>

# keyPassword= <password used to access the private key>

# truststore= <filename of the truststore to use>, it is where

recipients' certificate are stored

# tsPassword= <password used to access the trustStore>

# recipientAlias= <list of recipient's alias in trustStore, separated by

comma>

# Warning: Only one alias (first in the list) is supported

in current version

#

# encryptionAlgorithm= [ AES_128 | AES_192 | AES_256 | AES_128_GCM | AES_

192_GCM | AES_256_GCM ]

# keyIdentifier= [ IssuerSerial | KeyValue | X509KeyIdentifier ]

# keyEncryptionAlgorithm= [ RSA_V1_5 | RSA_OAEP | RSA_OAEP_MGF1P ]



# keyMGFAlgorithm= [ SHA_1 | SHA_224 | SHA_256 | SHA_384 | SHA_512 ]

# keyDigestAlgorithm= [ SHA_1 | SHA_224 | SHA_256 | SHA_384 | SHA_512 ]

#

encryptionMethod=NONE

#

xmlsec.keystore=${configurationDir}/xmlsec/ebicsserver.keystore

xmlsec.ksType=JKS

xmlsec.ksPassword=i05VFUqqd71dlY2hGSQBwQ==

xmlsec.keyAlias=ebicsserver

xmlsec.keyPassword=i05VFUqqd71dlY2hGSQBwQ==

#

xmlsec.truststore=${configurationDir}/xmlsec/ebicsserver.truststore

xmlsec.tsPassword=i05VFUqqd71dlY2hGSQBwQ==

xmlsec.recipientAlias=ebicsserver

#

xmlsec.encryptionAlgorithm=AES_256

xmlsec.keyIdentifier=IssuerSerial

xmlsec.keyEncryptionAlgorithm=RSA_OAEP_MGF1P

xmlsec.keyMGFAlgorithm=SHA_256

xmlsec.keyDigestAlgorithm=SHA_256

Default passwords: The default password for the keystore, truststore, and key is axway12345, which corresponds to the encrypted base64 version: i05VFUqqd71dlY2hGSQBwQ==.

Impact of the encryption settings on encryption and decryptionEBICS Gateway Server will follow the encryption instructions inside the configuration file to encrypt the payload (on inbound flow). The settings used for encryption are stored inside the XML encryption envelope, so that the reading application knows how to decrypt (this is the scope of the envelope).

When decrypting (inbound or outbound flow), EBICS Gateway Server reads the decryption instructions from the XML encryption envelope of the payload to decrypt (and not from its configuration file).

Important: In this version of EBICS Gateway Server, the key to use for decryption is not read from the XML encryption envelope, but from the configuration file. So, the applications sending encrypted data to the server must use the same credentials as the one identified in the xmlsec.keyAlias parameter (Key alias in the installer).



How to set up encryption for productionFor confidentiality reasons, you cannot use the default credentials in a production environment. The keystore and truststore must be changed.

Keystore and truststoreThe truststore is traditionally used to store the public keys and certificates of the partners whereas the keystore is used to store the personal keys and certificates (with private keys).

Currently, EBICS Gateway Server is only able to handle community credentials (with private keys), so the keystore and the truststore should be identical. This gives you the choice to:

l Set the keystore and truststore path to the same keystore location (through the installer).

l Maintain the keystore, and copy it as the truststore.

The instructions below assume that you make first choice.

Create a keystore with a self-signed certificateBecause encryption and decryption of data at rest is limited to the community, which is a private area, a self-signed certificate is sufficient.

The standard Java keytool (available in the JRE’s bin directory) enables you to create a keystore with a self-signed certificate in one shot.

Example with keytoolThe following command will generate a certificate that is valid for 5 years for encryption/decryption inside the keystore. keytool will prompt you to enter the distinguished name identifying the certificate (name, business unit, organization, city, region, and country).

<pathToJavaBin>/keytool -genkey -alias <keyAlias> -keyPass <keyPwd> -

keyalg RSA –validity 1826 –keystore <pathToKeystore> -storepass

<keyStorePwd>

Note:

l This command creates a certificate which is valid with the default encryption algorithms set in the EBICS Gateway Server configuration. If you plan to change them, you might need to generate a certificate with other characteristics.



Configure EBICS Gateway Server to use the new keystoreHere is a step-by-step procedure to register the new keystore inside EBICS Gateway Server.

1. Stop EBICS Gateway Server if not already done.

2. Use the Configure function of the installer to reconfigure EBICS Gateway Server.

3. Proceed to the EBICS Server / Encryption of data at rest screen and enter the values to match the newly-created keystore:

a. Verify that the Encrypt data at rest using XML Encryption option is checked.

b. Set the Keystore path to the newly generated keystore (<pathToKeystore>).

c. Set the Keystore password (<keyStorePwd>).

d. Set the Key alias to the alias of the community credential (<keyAlias>) used for

encryption/decryption.

e. Set the Key password with the password you gave to the certificate/key (<keyPwd>).

f. Copy the value of Keystore path inside Truststore path.

g. Copy the value of Keystore password inside Truststore password.

4. Finish the configuration.

5. Restart EBICS Gateway Server

At this point, EBICS Gateway Server is set to use the community credential for encryption and decryption. You now need to distribute the community credential to the backend side application(s) exchanging encrypted files with the server.

Distribute the community encryption credentialThe application(s) communicating with EBICS Gateway Server on the backend side need to have the same community credential, so that it/they can decrypt the payload received from EBICS Gateway Server, and encrypt the payload supplied to it.

If that application expects a Java Key Store, then you can directly provide a copy of the keystore of EBICS Gateway Server. Otherwise, you can extract the community credential as a PKCS12.

For security reasons, it is highly recommended to send the keystore/PKCS12 and its password separately!

The following command will export the certificate + private key from the keystore as a PKCS12. The pathToPkcs12File should be given a .p12 extension. keytool will prompt you to enter the password of the source keystore.



Example with keytool

<pathToJavaBin>/keytool -importkeystore -srckeystore <pathToKeyStore> -

destkeystore <pathToPkcs12File> -srcstoretype JKS -deststoretype PKCS12

-deststorepass <pkcs12Pwd> -srcalias <keyAlias> -destalias <keyAlias>



Use EBICS Gateway Server with a DMZ proxyYou can install EBICS Gateway Server in a corporate network and use Axway Secure Relay in a DMZ in order to provide maximum security for your connections.

Figure 7. Secure Relay used as a DMZ proxy with EBICS Gateway Server

About Secure RelaySecure Relay is a software-driven proxy that consists of two components: a Router Agent, deployed in the DMZ, and a Master Agent, located in the corporate network. Secure Relay enables you to protect data, customers, and networks while enabling critical file transfer services between approved parties.

In this version, EBICS Gateway Server uses the standalone version of the Secure Relay Master Agent. This means that the Master Agent configuration is handled outside EBICS Gateway Server.

All file transfer dialog (protocol, authentication, and so on) is handled by EBICS Gateway. This avoids any permanent or temporary storage of critical information in the DMZ, including files, configuration information (such as keys and certificates), and critical back-end processing (such as digital signing or envelope decryption).

For a detailed description of Secure Relay, refer to the Axway Secure Relay documentation.

Configure EBICS Gateway Server to use Secure RelayTo use this feature, your EBICS Gateway license file must include the Secure Relay option.

In order to use Secure Relay with EBICS Gateway Server, you must install the standalone Master Agent on each machine hosting an EBICS Gateway Server node, and configure it to forward the inbound connections to the EBICS Gateway Server EBICS Channel port (default 8444).

The usage of Secure Relay is transparent to the EBICS Gateway Server.

Refer to the Axway Secure Relay Master Agent documentation for installation and configuration instructions.



EBICS Gateway Server toolsThis section describes the EBICS Gateway Server tools, such as the supplier, injector, and purge.

Supplier command line on page 132

Supplier service on page 135

Run the supplier as a Windows service on page 146

Injector on page 149

Purge command line on page 157

Configure WebSphere environment for EBICS Gateway Server tools on page 161

Supplier command line

About the supplier command line toolThe supplier command line tool enables you to deposit data in the EBICS repository in a quick and easy way. This is useful if you want to supply a single file, for example for maintenance or testing.

For production usage, you should use the Supplier service on page 135. The supplier service is an automated process that can handle several files at the same time.

The supplier command line tool is included in the EBICS Gateway Server installation. After installation, you can execute the script server/supplier/bin/supplier.sh (or server/supplier\bin\supplier.bat on Windows platforms).

Configuring the supplier command line toolThe command line tool is configured when you install EBICS Gateway Server. You can reconfigure the command line tool at any time by using the Configure function of the Axway Installer.

Alternatively, you can modify the properties file <SUPPLIER_INSTALL_DIR>/conf/supply.properties manually. The following table describes the properties:

Property Description

database settings To configure your database setting, see Database on page 143.

security.encoding.active Activates (true or false) the encoding of the passwords. This property acts on both of the passwords provided in this file.




security.encoding.type Sets the type of encoding used in this file (NONE, B64 or AES).

The installer always encrypts passwords in AES. You should not use NONE or B64 except temporarily for debugging purposes.

server.host Host on which the EBICS Gateway Server is located

server.port Port on which the EBICS Gateway Server is listening

server.user User login for the EBICS Gateway Server

server.pass Password to connect to the EBICS Gateway Server

server.type Type of application server on which the EBICS Gateway Server is running:

l JBOSS – for embedded application server

l JBOSSEAP – for JBOSS Enterprise Application Platform (EAP)

l WAS – for WebSphere Application Server

Additional configuration for WebSphereBefore you can use the supplier command line tool in a WebSphere environment, you must perform some additional configuration steps. For details, see:

l Configure WebSphere environment for EBICS Gateway Server tools on page 161

Using the supplier command line toolThe supplier command line tool enables you to execute command lines from the machine where you install the EBICS Gateway Server tools.

This section provides information about the principal commands you execute using the supplier command line tool.

For additional details about supplier commands, refer to the command help available in the command line interface.

SyntaxThe general syntax of the supplier line command is:

supplier[.sh|.bat] --[parameter 1] --[parameter 2] --[parameter n]



Parameters

Parameter short name

Parameter long name

Value(s)

-b --bank <bankName>

-ct --connectionType Type of application server on which the EBICS Gateway Server is running:




-d --date <date>

The date of the supply operation

-f --file <file>

The file to supply

-ff --fileFormat <fileFormat>

The file format involved in the supply operation

-h --help Display command line help for this command

-ib --iban <iban>

The IBAN involved in the supply operation

-l --login <login>

The login of the EBICS Gateway Server

-ot --orderType <orderType>

The order type involved in the supply operation

-p --port <port>

The port of the EBICS Gateway Server

-pwd --password <password>

The password of the EBICS Gateway Server.

-enc --encoding <NONE|AES|B64>

The algorithm used to encrypt the password.




Parameter long name

Value(s)

-s --supply If set, only the database will be updated

-sz --size <size>

The size of the supplied file

-szm --sizeMode [check|fixed|compute]

Sets the method to compute and size to fetch parameter

-hstid --bankhostid <ebicsHostId> Bank EBICS host-id. If both a bank name and a host-id are given, the host-id is used

-host --hostname <url> The URL of the EBICS Gateway Server

-r --retries <n> Number or retries (in case of lock file encounters)

-t --timeout <delayInMilliseconds> Time delay between retries (in milliseconds)

-rb --rollback If set, roll back last supply using provided parameters

-frb --force If set, roll back even if file was already fetched

-mrb --multiplerollback <n> Number of rollbacks to perform

-rbf --rollbackFrom <YYYYMMDD> Date from which to roll back

-rbt --rollbackTo <YYYYMMDD> Date to which to roll back

Supplier service

About the supplier serviceThe supplier service is a standalone background process that enables you to supply account statements to EBICS Gateway Server.

The supplier service monitors a watch directory. All files that are deposited in this directory will be supplied automatically to EBICS Gateway Server. A file qualifies for the supply if its name matches a defined pattern. By default, this pattern is set to: IBAN_EBICSBANKHOSTID_ORDERTYPE_FILEFORMAT_DATE.

All files currently under a supply process are copied to the processing directory.



If the supply succeeds, the supplied file is moved from the processing directory to the success directory. If it fails, it is placed in the failed directory.

Note If you just want to supply a single file, for example for maintenance or testing, you can use the Supplier command line on page 132.

Prerequisites l The supplier service has been installed. You have to choose the Supplier module in the Axway Installer when you install EBICS Gateway Server.

l If you are using a WebSphere Application Server, you must update the supplier script (supplyservice.sh or supplyservice.bat) by adding specific properties and JAR

files so that the required libraries are accessible. For details, see

o Configure WebSphere environment for EBICS Gateway Server tools on page 161

Starting and stopping the supplier service

Start supplier serviceOn UNIX platforms, start the supplier service by running the script <SUPPLIER_INSTALL_DIR>/bin/supplyservice.sh.

On Windows platforms, run the script <SUPPLIER_INSTALL_DIR>\bin\supplyservice.bat.

Stop supplier serviceDepending on how you stop the supplier, there might be a risk of data corruption.



OS Stop command

Risk of data corruption

Description

Windows Taskkill* No Supplier processes any running supply until completion before stopping.

Windows "Process Manager" Stop

Yes Stop is not managed by the supplier. Resources are de-allocated by the OS.

Windows service

No Supplier controller is mandatory for Windows services. Supplier processes any running supply until completion before stopping.

Control-C in an open command window

No

UNIX kill -9

signal

Yes Stop is not managed by the supplier. Resources are de-allocated by the OS.

Default kill

(-15) signal

No Supplier processes any running supply until completion before stopping.

Control-C in an open command window

No

*Taskkill is not available on all Windows platforms.

The safest way to stop the supplier is to enable the supplier controller and use the related scripts as described below.

Supplier controllerThe supplier controller is a small client that instructs the supplier service to shut down.

To enable the supplier controller:

1. Open the supplier configuration file <EBICS Gateway

dir>\server\Supplier\conf\supply.properties with a text editor.

2. Set supplier.controller.activated to true.

3. Assign an available port number to supplier.controller.port (default 64000).

4. Start the supplier service:

<EBICS Gateway dir>\server\Supplier\bin\supplyservice.bat




The controller will then automatically start with the supplier service.

To stop the supplier service using the supplier controller:

1. Stop the supplier service using:

<EBICS Gateway dir>\server\Supplier\bin\controllerStop.bat

2. Make sure that supplier service stopped properly.

Whenever you call the script <SUPPLIER_INSTALL_DIR>/bin/controllerStop.sh (or controllerStop.bat on Windows), the supplier service will safely stop.

Consult log filesConsult supplier service logs in <SUPPLIER_INSTALL_DIR>/logs/supplier.log.

Supply modesTwo different supply modes are provided: File and Database. The supply mode determines how the supply is stored in EBICS Gateway Server: as a file in the data store or directly serialized into the database. Note that only an Oracle database is supported for Database supply. It is highly recommended to use File supply rather than Database supply. Database supply is only provided for compatibility reasons and will be deprecated in future versions.

You set the mode when installing EBICS Gateway Server using the Axway Installer. In the EBICS Gateway Server: Supplier settings screen, select DataStore directory (file) or Ebics Server Database (database). If you want to modify the selection later on, use the Configure function of the installer.

Important: The configuration of the supplier service depends on the configuration of EBICS Gateway Server. Each order type/ file format couple is configured with a specific handler (in Processing/ Fetch Transactions). The handler determines how data is stored in EBICS Gateway Server ("Axway Generic Fetch" Transaction for File mode and "Axway Database Fetch Handler" for Database mode). For details of handlers, see EBICS: Processing on page 71.

For example, if the (order type, file format) FDL.camt.xxx.cfonb120.stm is configured with Axway Generic Fetch (File mode), to enable the supplier service to supply on it, you need to set its supply mode to File.

For more information about supply modes and how they affect the behavior of the supplier service, see Limitations on page 145.

Supplier configuration fileThe file <SUPPLIER_INSTALL_DIR>/conf/supply.properties contains the supplier configuration settings. This section lists the properties and provides some additional information. Refer to the configuration file itself to see all the properties and the values that were assigned during installation.



SecurityThis section lists the properties related to security.


security.encoding.active Enables encoding of the passwords (true/false). This should always be true in production, and will always be set to true by the installer.

security.encoding.type Type of encoding: This property is included for compatibility reasons. You should always use AES.

security.connection.api.secure Embedded server only

Indicates if the API connection uses a secure protocol.

Possible values: true or false

This property is included for compatibility reasons. It should always be true.

TuningThese properties enable you to configure threads and connections and to configure the supplier controller.


supplier.threads Defines the number of threads to use.

Default=5

supplier.jdbc.pool.maxactive Defines the maximum number of active connections in the JDBC pool.

Default=10

supplier.jdbc.pool.jmxenabled Enable the JMX export of the JDBC pool. Only activate for debug purposes.


Default=false

supplier.jdbc.pool.connection.timeout JDBC connection timeout (in seconds).

Default=60

supplier.controller.port Defines the port number for the supplier controller.

Default=64000




supplier.controller.activated Activates/deactivates the supplier controller


Default=false

The supplier service is multi-threaded. You can tune the number of threads used to supply by editing the property:

supplier.threads=5

Increasing this value does not necessarily mean that the supplier service will be faster. It must be set according to your production environment and your use case to get the best performance.

File managementThese properties define the structure of files to supply.


file.regex POSIX regular expression that defines the file pattern.

^([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-9A-Za-z\.]+)_([0-9]+)$

file.separator The separator character between file name groups.

Default=_

file.group.mdt.iban Mandatory group 1

file.group.mdt.bankhostid Mandatory group 2

file.group.mdt.orderType Mandatory group 3

file.group.mdt.fileFormat Mandatory group 4

file.group.opt.date Optional group 5

file.transfer.strategy Defines the file transfer strategy.

Possible values: copy or move.

Default=copy

See File transfer strategy on page 141.

The default file pattern is set to: IBAN_EBICSBANKHOSTID_ORDERTYPE_FILEFORMAT_DATE.

If necessary, you can change the file pattern by editing the file.regex property:

file.regex=^([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-

9A-Za-z\.]+)_([0-9]+)$



file.regex is a POSIX regular expression which is structured: FIELD1_FIELD2_FIELD3_..._FIELDN. You can also replace the field separator with file.separator.

There are some mandatory fields for the supply: IBAN, order type, file format and EBICS bank host ID. You can add optional fields such as date or file number.

Date format: The date must be defined with the format YYYYMMDD.

You can change the position of a field in the pattern file.regex by editing these properties:

file.group.mdt.iban=1

file.group.mdt.orderType=3

file.group.mdt.fileFormat=4

file.group.mdt.bankhostid=2

file.group.opt.date=5

Note To be able to supply order types without a file format (only 3 letters), modify the configuration properties as follows:

file.regex=^([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-9A-Za-z]+)_([0-

9]+)$

file.separator=_

file.group.mdt.iban=1

file.group.mdt.bankhostid=2

file.group.mdt.orderType=3

file.group.opt.date=4

File transfer strategy

When using the File mode, the supplier service has two possible file transfer strategies: copy and move.

Copy is the default behavior. The supplier service makes a copy of the file to supply from the supplier service to the EBICS Gateway Server data store and then moves the file from the watch directory to the processing directory and then, if successful, to the success directory.

The move strategy moves the file from the watch directory directly to the data store without making a copy in the success directory. This strategy is more efficient because move is faster than copy but has a limitation. It only works when the watch directory and the EBICS Gateway Server data store directory are on the same file system partition. Otherwise you must use the copy strategy.

Depending on your use case, the copy strategy can be useful if you need to keep a copy of the successful supplied files.

When using Database mode, the copy strategy is always followed (the strategy parameter is ignored).

Example:

file.transfer.strategy=copy



Server connectionThese properties are set by the installer. They define the configuration of the connection to EBICS Gateway Server.


server.host EBICS Gateway Server host name

server.port EBICS Gateway Server port number

Default=8443

server.type Type of application server on which the EBICS Gateway Server is running:




server.user EBICS Gateway Server user to connect with.

server.pass EBICS Gateway Server user password (possibly encrypted according to the encoding property).

server.connection.retry.number Sets the number of connection retries to EBICS Gateway Server.

Default=5

server.connection.retry.delay Delay between two retries (in milliseconds).

Default=1000

The supplier service has a connection retry mechanism with EBICS Gateway Server. You can set the number of retries:

server.connection.retry.number=5

You can also set the time between two retries (in milliseconds):

server.connection.retry.delay=1000



DatabaseThese properties are set by the installer. They define the connection with the EBICS Gateway Server database in Database mode.


databaseUrl The URL of the database used by EBICS Gateway Server (for supply).

Example:

jdbc:mysql://localhost:3306/ebics

jdbc:oracle:thin:@localhost:1521:EBICS

databaseLogin The user to connect to the database.

Example: EbicsGateway

databasePassword Password to use to connect to the database (possibly encrypted according to the encoding property).

Important: The use of the database requires the handler of the used order types to be set to "Axway Database Fetch Handler" in the server. The supplier service will not run any check at runtime to ensure consistency between the supplier service set-up and the server set-up.

Monitored directoriesThese properties define the directories used by the Supply Server.


directory.watch The directory where the files to supply are retrieved from.

Example:

<EBICS Gateway Server install dir>\\data\\supplier\\in

directory.processing The directory where the files currently under a supply process are placed.

Example:

<EBICS Gateway Server install dir>\\data\\supplier\\processing

directory.fail The directory used to move the files in error. If value is empty, the files are not moved.

Example:

<EBICS Gateway Server install dir>\\data\\supplier\\failed




directory.success The directory used to move the files in success. If value is empty, the files are not moved.

Example:

<EBICS Gateway Server install dir>\\data\\supplier\\success

supplier.pollingTime Polling time (in seconds). The monitored directories will be checked every N seconds.

Default=1.

SentinelThese properties are set by the installer. They define the configuration to connect to the Sentinel Server for Sentinel notifications.


sentinel.active Activate Sentinel notifications.


Default=false

sentinel.host Sentinel Server host name

Default=127.0.0.1

sentinel.port Sentinel Server port number

Default=1308

sentinel.objectname Name of the Tracked Object that receives the notifications.

Example:

SFEX2

sentinel.objectversion Version number of the Tracked Object that receives the notifications.

Example:

3.7

Handling huge filesYou should not use the database supply if you plan to supply huge files. This can slow down your database dramatically.

Technically, there are different ways to add files to the watch directory of the supplier service. If you choose a copy-based method, the supply might be wrong for huge files. When you copy a huge file to the watch directory, the supplier service can supply it even though the copy is not finished. This



can lead to inconsistent data. To avoid this problem, copy your file with the .lck extension. For example, rename the file FILE_TO_SUPPLY to FILE_TO_SUPPLY.lck. The supplier service will ignore it until you rename or move it in the same directory without the .lck extension after the copy ends. Move is an atomic file system operation so it ensures the consistency of the file.

Sentinel notificationsThe Tracked Object for the supplier is specified in the supplier configuration file <SUPPLIER_INSTALL_DIR>/conf/supply.properties and must contain a "FileName" attribute. The default XFBTRANSFER Tracked Object already contains this attribute. The FileName attribute will be filled in with the full path name of the supplied file.

The Current table in Sentinel holds the latest supplied file name. The full list of file names for the current day is stored in the History table. The full path name is sent to Sentinel.

Note If the FileName attribute defined in the Tracked Object is not large enough to contain the full path, Sentinel will store the first characters in the database. The end of the file name will be lost.

Limitations

Supplier service locationIf you use File-based fetch handlers, the supplier service must be installed on the same machine as EBICS Gateway Server. The supplier service cannot remotely send a file to a "file system" data storage. It can be installed remotely if you use database-based handlers.

Supply modesAlthough the supplier command line tool dynamically determines how a file must be supplied (File or Database mode), the supplier service does not. The supplier service works exclusively in the configured mode. In other words, you can not mix several order types which have different storing modes. If the supplier service is configured for File mode, and you try to supply a file on an order type which is configured in Database mode in EBICS Gateway Server, the supply will fail. To bypass this limitation you can use two different installations of the supplier service, one configured for File mode and the other for Database mode. Just be careful about the order types you submit to each one.



Run the supplier as a Windows serviceThis section describes how to configure the EBICS Gateway Server supplier to run as a Windows service.

Prerequisites

Check that the supplier service is functionalBefore you start to configure the Windows service, you need to make sure that the supplier service connects successfully to EBICS Gateway Server.

1. Open a command prompt and start EBICS Gateway Server:

<EBICS Gateway dir>\server\EmbeddedServer\bin\standalone.bat

2. On a different command prompt start the supplier service:


3. Make sure the supplier service connects without error to EBICS Gateway Server.

4. Stop the supplier service, but not EBICS Gateway Server.

Configure remote stopWhen running the supplier as a Windows service you need a mechanism to stop it remotely.

The supplier controller is a small client that instructs the supplier service to shut down.

To enable the supplier controller:

1. Open the supplier configuration file <EBICS Gateway

dir>\server\Supplier\conf\supply.properties with a text editor.

2. Set supplier.controller.activated to true.

3. Assign an available port number to supplier.controller.port (default 64000).

4. Start the supplier service:



The controller will then automatically start with the supplier service.

To stop the supplier service using the supplier controller:

1. Stop the supplier service using:

<EBICS Gateway dir>\server\Supplier\bin\controllerStop.bat

2. Make sure that supplier service stopped properly.



Configuration steps

Register the service 1. In a command line prompt, move to:

<EBICS Gateway dir>\server\Supplier\bin\service

2. Enter the command:

service.bat install

3. Open the Windows Services application and check that the EBICS Server Supplier service is now registered.

Configure the service 1. In the Windows Services application, double-click the EBICS Server Supplier entry to access its

properties.

2. Click the Log On tab, and enter the details for the user account that you have chosen previously.

You can configure other aspects of the service in the properties dialog according to your use case.

Run the serviceAfter configuring the service, you can use the Windows Services application to start and stop the Supply service.

Alternatively you can use the service.bat script:

l service.bat start

l service.bat stop

Uninstall the serviceTo remove the service from Windows, use the service.bat script:

service.bat uninstall

Service logsThe service logs are located together with the Server logs in:

<EBICS Gateway dir>\server\Supplier\log



This folder contains two extra log files:

l supplyservice-stdout... – for standard output

l supplyservice-err... – for error output



InjectorThe injector enables you to manage objects on the EBICS Gateway Server repository. You can create, delete and update server objects such as banks, customers, users, accounts, order types and so on, along with the associated links between them. The input is provided in an XML file.

Prerequisites l The injector has been installed. The injector module is installed when you install EBICS Gateway Server.

l If you are using a WebSphere Application Server, you must update the injector script (injector.sh or injector.bat) by adding specific properties and JAR files so that the

required libraries are accessible. For details, see:

o Configure WebSphere environment for EBICS Gateway Server tools on page 161

How does it work?To run the injector you need to call its script (<EBICS Gateway dir>/server/injector/bin/injector.sh or injector.bat) and provide the XML file that contains the data to inject. When the injection is done (or fails), the program ends.

Since version 3.0.1, the injector handles a new XML injection file format. The former version is also handled, but only for compatibility reasons. You are strongly encouraged to update to the new version which provides more features and will be updated with new features at a future date.

Related logs can be found in <INJECTOR_INSTALL_DIR>/logs/injector.log.

Injector command line syntaxFeed the XML input file to the injector using the command line with the -in parameter:

l injector.sh -in myInjectedFile.xml, or

l injector.bat -in myInjectedFile.xml (for Windows)

Injector command line parameters


Parameter long name

Value(s)

-h --help Display command line help for this command




Parameter long name

Value(s)

-in --inject Path of the injection file

-cid --cycleid Sentinel cycleid

Basic settingsThe injector requires some basic settings in order to access the EBICS Gateway Server. Configure the injector in the parameters.properties file in the block labeled "EBICS":


ebics.server.host Hostname of the EBICS Gateway Server (or IP address).

ebics.server.port Port to connect to the EBICS Gateway Server (bootstrap port on WAS).

ebics.server.type Type of application server on which the EBICS Gateway Server is running:




ebics.server.user Username to log in to EBICS Gateway Server.

ebics.server.pass Password to authenticate EBICS Gateway Server.

In addition to the above settings, the password must be encoded according to the value of the general.encoding.type property whose values can be: NONE, AES, B64. The installer always encrypts passwords in AES. You should not use NONE or B64 except temporarily for debugging purposes.

Sentinel settingsThe injector can feed data into Sentinel. The configuration is done in the parameters.properties file in the conf directory, in the block labeled "Sentinel":


sentinel.active Activate Sentinel connectivity or not (true or false).




sentinel.host Hostname (or IP) of Sentinel Server.

sentinel.port Sentinel port number

sentinel.objectname Tracked Object to use in Sentinel.

sentinel.objectvers Tracked Object version.

If you want Sentinel connectivity to work, you must specify the cycle Id to use on the command line:

Injector.sh –in myInjectedFile.xml -cycleid cycleIdToUse

The injector fills in the following fields of XFBTRANSFER: cycleid, eventdate, eventtime, returncode, returnmessage

IsAlert, IsException and IsEnded can be set according to the termination status of the injection.

Gateway settingsThe injector can have all its actions in Gateway to create a matching configuration. Such a configuration is defined in the conf directory in parameters.properties, in the block labeled "Gateway":


gtw.active Activate the Gateway connector or not (true or false)

gtw.dir Directory to the root of the Gateway installation

gtw.interface.port Gateway port

Database settingsThe injector can have all its actions in an external database repository (such as the one in the Generic Process).

When activated, the injector runs the following stored procedures at the appropriate time:

l PS_DeleteBank

l PS_CreateCustomer

l PS_CreateFFSend

l PS_DeleteCustomer



l PS_DeleteFFSend

l PS_UpdateCustomer

l PS_UpdateFFSend

l PS_DeleteFFServer

l PS_CreateUser

l PS_DeleteUser

l PS_UpdateUser

You also need to configure the access to the database in the parameters.properties file in the "BDD" section:


bdd.active Activate the connectivity to the external database.

bdd.type MYSQL or ORACLE.

bdd.host Host to the database (or IP).

bdd.port Port to access the database.

bdd.user User to connect to the database.

bdd.pass Password to authenticate on the database.

bdd.instance Instance of the database to which to connect.

XML input file In this version of EBICS Gateway the injector XML schema has changed so that it corresponds more closely to the EBICS Gateway data model. The new XSD is more complete and offers more injection possibilities. All the object fields are now available for injections.

To build the XML input file, refer to the XSD file (EbicsInjector.xsd) delivered in the conf directory of the injector hierarchy.

Important: The order of the elements in the XML file must respect the XSD file.

The previous XML file format is also supported. The injector automatically detects if the file is in the old format or the new format.

You are strongly encouraged to move to the new format. New functionalities will only be added to the new format.



Injector object actionsThe following is a list of possible actions for each object in the XML input file:

Object Action

ebics/transactions/sendOrderType CREATE: Create a new send order type or file format

UPDATE: Update a send order type or file format

DELETE: Delete the send order type or file format

ebics/transactions/fetchOrderType CREATE: Create a new fetch order type or file format

UPDATE: Update a fetch order type or file format

DELETE: Delete the fetch order type or file format

ebics/banks/bank CREATE: Create a new bank

UPDATE: Update a bank

SELECT: Select the bank of the database. Reference to this object is made in the actions that follow. This is the case when updates need to me made to bank objects (customers, users, etc.) but not to bank properties

DELETE: Delete the bank and all its associated objects (customers, users, etc.)

ebics/banks/bank/accounts/account CREATE: Create a new account

UPDATE: Update an account

DELETE: Delete an account



Object Action

ebics/banks/bank/customers/customer CREATE: Create a new customer

UPDATE: Update a customer

SELECT: Select the customer of the database. Reference to this object is made in the actions that follow. This is the case when updates need to be made to customer objects (users, etc.) but not to customer properties

DELETE: Delete the customer

ebics/banks/bank/customers/customer/

transactions/sendOrderType

or


transactions/fetchOrderType

CREATE: Create a link between the orderType and the customer. The customer is authorized to use this orderType. The orderType must exist in the database (either already present or previously created).

DELETE: Delete the link orderType – customer.

UPDATE: The link fileFormat (send) – customer is updated. It affects only the Send fileFormat. It does not affect the Fetch fileFormat.


accounts/account

CREATE: Create a link between the account and the customer. The account must exist in the database (either already present or previously created).

DELETE: Delete the link account – customer.


users/user

CREATE: Create a new user

UPDATE: Update a user

SELECT: Select the user of the database. Reference to this object is made in the actions that follow.

DELETE: Delete the user



Object Action


users/user/transactions/sendOrderType

or


users/user/transactions/fetchOrderType

CREATE: Create a link between the orderType and the user. The user is authorized to use this orderType. The orderType must exist in the database (either already present or previously created).

DELETE: Delete the link orderType – user.

UPDATE: The link fileFormat–user is updated. It affects only the Send fileFormat. It does not affect the Fetch fileFormat.

Supported values for Handler tagThis section lists the supported values for the Handler tag inside the objects ebics/transactions/sendOrderType or ebics/transactions/fetchOrderType in the injection file. The properties.xml file from the previous version is no longer used.

Send

l BINARY_FILES

l BINARY_FILES_WITHOUT_TICKET_CREATION

l CCC_PAIN_001_001_02_CON

l CCC_PAIN_001_002_02

l CCM_PAIN_001_001_02

l CCT_PAIN_001_001_02_GRP

l CDC_PAIN_008_001_01_CON

l CDD_PAIN_008_001_01_GRP

l CHANGE_KEY

l CHANGE_PASSWORD

l CUSTOMER_ENCRYPTION_KEY

l DTA_EBCDIC_CLEARING

l DTA_EBCDIC_COMPRESSED_HBV_EMZ

l DTA_SWIFT_EBCDIC_HBV_MZ

l DTAUS_FILES

l DTAZV_FILES

l INITIALIZE_KEYS

l LOCK_USER

l MCV_FILES



l PRE_VALIDATION

l TEXTFILE

l QRX

l SEPA

l SWIFT_EBCDIC_EMZ

l SWIFT_EBCDIC_HBV_EKI

l SWIFT_EBCDIC_QMA_EKI

l SWIFT_EBCDIC_QWT_HVB

l ZZV

Fetch

l ACCOUNT_STATEMENTS

l AVISE_MT942

l AXWAY_CUSTOMER_PROTOCOL_PTK

l AXWAY_DATABASE_FETCH_HANDLER

l AXWAY_DATABASE_ZIP_FETCH_HANDLER

l AXWAY_FORWARD

l AXWAY_GENERIC_FETCH_TRANSACTION

l AXWAY_GENERIC_ZIP_FETCH_HANDLER

l AXWAY_MT940

l AXWAY_MT942

l AXWAY_PSR_EXIT_TRANSACTION

l AXWAY_USER_BASED_PSR_EXIT_TRANSACTION

l BDP

l CUSTOMER_PROTOCOL

l DISCRETE_FILES

l EBICS_BANK_PARAMETERS

l EBICS_CUSTOMER_PROTOCOL_HAC

l EXTENDED_HVU

l FETCH_PUBLIC_KEY

l HKD

l HTD

l ONE_FILE_FOR_ALL_CUSTOMERS

l ONE_FILE_PER_CUSTOMER

l ONE_FILE_PER_USER

l PAYMENT_STATUS_REPORT_PSR



l PUBLIC_KEY_FOR_EBICS_CUSTOMERS

l USER_BASED_PAYMENT_STATUS_REPORT_PSR

l ZIP_CONTAINER_ACCOUNT_INFORMATION

Purge command lineYou can find the purge command line tool in the <EBICS Gateway dir>/server/purge directory.

Execute the purge script from the bin directory.

Configure the purge command line toolBefore you can use the purge command line tool in a WebSphere environment, you must perform some additional configuration steps. For details, see:

l Configure WebSphere environment for EBICS Gateway Server tools on page 161

Using the purge command line toolThe purge command enables you to purge the EBICS repository from the machine where you install it.

The purge operates on the following items:

l Fetch data: The data store is cleaned (regardless of the fetched/unfetched status of the files), as well as the cursor table in the database and the lock files in the data store. The data store is purged regardless of its type (remote or file-system: both are purged). An archive containing the purged data is created in the current directory (if no other is specified through the zip location option). This archive contains the zipped data purged from supply done both on file system and database. The data supplied in file system is split over as many smaller archives as are required. The size of an archive is limited by the number of entries which defaults to 50 000 and can be tuned with the archiveFileCount option.

l Send data: The directory where all sent files are stored is purged (orders directory) as well as the FetchImport, Send/files and Send/tmp directories from the specified MFT directory.

The Files pane of the user interface is also emptied. A zip file of the deleted data is saved in the specified location, or in the current directory if none is specified.

l Supplies and send files. A zip file of the deleted data is saved in the specified location, or in the current directory if none is specified.

l Gateway: Using the specified Gateway installation directory, the following commands are run on Gateway:

o pelpur -pf -lts ABCDEFGIPRSTUVW -kld <time>

o pelctl archive_log



SyntaxThe syntax accepts all parameters as options on the command line.

Short option

Long option Description

-afc --archiveFileCount

Max number of entries allowed per chunk for purging the files supplied in file system. The default value, if the option is not specified is 50 000.

-bdir --backupDirectory

Specifies the directory used to store files temporarily before archiving.

This directory must be accessible from all processing nodes (and the one running the purge tool). This option is only useful when the purge is not running on shared space.

-b --bank Bank name. The Name field in the EBICS Gateway Server, neither HostID nor EbicsHostID here (only for send)

-ct --connectionType

Type of application server on which the EBICS Gateway Server is running:




-c --customer Customer name. The Name field in the EBICS Gateway Server, no HostID here (only for send).

-enc --encoding The algorithm used to encrypt the password.

Possible values:

l NONE

l AES

l B64


-fth --fetch Performs all the purges related to fetches

-fot --fetchOrdertype Fetch Order Type (for example FDL.camt.xxx.cfonb120.stm)



Short option

Long option Description

-fi --fileImport If set, purges the import history table (purges hashes of imported files to handle duplicate files)

-fn --fileName <file name>

If set, remove the entry with the specified file name from the hash file repository

-f --forever Purges all data available

-g --gateway Performs the purge of Gateway

-gd --gtwDir Specify the Gateway installation directory

-host --hostname Address of the server

-lck --lock Deletes the lock files in the data store

-log --log Performs the purge on the logs

-l --login User name to log in to the server

-md --mftDir Specify the MFT directory

-nz --nozip Do not perform a zip of the backup directory after a purge, and delete the backup directory

-pwd --password Password to authenticate to the server.

-p --port Port of the server

-rf --referenceId <refId>

If set, remove the entry with the specified reference id from the hash file repository

-s --send Performs all the purges related to sends

-sot --sendOrdertype Send Order Type (for example FUL.pain.xxx.cfonb160.ddd)

-n --time The number of days or months to keep

-u --unit MONTH or DAY

-am --useAM PassPort AM will be used if the option is set

-z --zipLocation Specify the path to the zip archive location (ignored if nz or nozip is specified)



A user can perform a purge on:

l Send with optional parameters BANK and/or CUSTOMER and/or Send Order Type.

l Fetch with optional parameters Fetch Order Type.

Bank and Customer parameters are only available for send.

If the bank does not exist, the send purge is not performed and a warning appears in the log file. If the customer or the order type does not exist, nothing happens.

The purge command line checks the input parameters:

l If the bank and/or customer and/or send order type is set, without selecting the -s or --send

parameter (send purge), the command line asks the user to verify the parameters.

l If the fetch order type is set, without selecting the -fth or --fetch parameter (fetch purge),

the command line asks the user to verify the parameters.

These checks are performed to prevent the user from making a mistake. For example, without the checks, if the user wanted to make a fetch purge on bank (which is not possible) all the fetches would be purged regardless of the bank (ignored in this case).

Purge return codesThe purge script returns the following return codes:

Purge return code

Purge result

0 Success

1 Failure at API initialization

3 Failure during the purging of logs

4 Failure during the purging of the file import history

5 Failure during the purging of delivery information (removal from file-system of files related to send operations)

6 Failure during the purging of orders (removal from database of entries related to send operations)

7 Failure during the purging of Gateway

8 Missing argument in command-line



ConfigurationIn the conf directory of the purge tool, you can specify the EBICS Gateway Serverenvironment in the server.properties file:

Property Value

ebics.server.host Address of the server

ebics.server.port Server port

ebics.server.type Type of application server on which the EBICS Gateway Server is running:




ebics.server.user User log in

ebics.server.pass User password

security.encoding.type The type of encryption for the password (NONE, AES or B64)


These options can also be specified in the command line, which will override the ones in the server.properties configuration file.

Configure WebSphere environment for EBICS Gateway Server toolsBefore you can use the EBICS Gateway Server tools (supplier, injector, purge, and so on) in a WebSphere environment, you must perform some additional configuration steps.

1. Make sure you are using an IBM JRE.

2. Set the following properties in the JVM arguments of all your client scripts (tools, purge, supplier, injector, and so on):

l -Djava.security.auth.login.config=<WAS_

profile>/properties/wsjaas_client.conf

l -Dcom.ibm.CORBA.ConfigURL=file:<WAS_

profile>/properties/sas.client.props

l -Dcom.ibm.SSL.ConfigURL=file:<WAS_

profile>/properties/ssl.client.props



where:

l <WAS_profile> is the path to the WebSphere profile folder where you have

deployed the EAR.

l wsjass_client.conf file contains the unchanged defaults shipped with

WebSphere.

l ssl.client.props file has the following modifications:

o If the API is on the same machine as the WebSphere server, the value of user.root is the profile repository.

o If the API is not on the same machine, set the value of user.root to the directory that contains a folder named etc. The user must have write rights on this

folder.

l sas.client.props file has the following modifications:

o com.ibm.CORBA.loginSource=none

o com.ibm.CORBA.securityServerHost=<hostname_of_

WebSphere>

o com.ibm.CORBA.securityServerPort=<port_of the

BOOTSTRAP>

3. Add the following JAR files to the classpath:

l com.ibm.ws.admin.client_x.x.x.jar

l ejb3exceptions.jar

l com.ibm.ws.webservices.thinclient_x.x.x.jar

l com.ibm.ws.ejb.thinclient_x.x.x.jar

where x.x.x depends on the version of your application server. You can find these JAR files in <WebSphere_Install_ROOT>/runtimes.

There are two possible methods to do this:

a. Copy the JAR files to the EBICS Gateway Server tools lib directory. For example, for

the supplier, copy the files to <EbicsGateway>/server/Supplier/lib

b. Update the start script to modify the classpath.

4. Use the Administration Console to perform these modifications:

l In CSIv2 Inbound Communications and CSIv2 Outbound Communications, change Transport parameters from "SSL-required" to "SSL-supported".

l In Security > Global Security > Custom Properties, add the property: com.ibm.websphere.security.registry.propagateExceptionsTo

Client and set it to true.


4 Monitoring EBICS Gateway processes

IntroductionYou can use Sentinel to collect information about three types of EBICS Gateway activity:

l Processing of incoming and outgoing exchanges – Client and Server

l Client subscriber initiation processes (key exchange and approval) – Server only

l Health status (heartbeat) – Server only

To provide information to Sentinel, EBICS Gateway generates event notification messages that it sends to Sentinel. Sentinel stores the information contained in these messages in the Sentinel database. You can then use Sentinel features to recover, organize and display the stored data.

Sentinel also provides you with tools that help you create pre-programmed automatic responses to specified network conditions. Using these tools, you can configure Sentinel to act immediately to handle exceptional and/or abnormal integration processing events and statuses.

The information that EBICS Gateway collects and sends to Sentinel is defined by Tracked Objects. A Tracked Object is a data container in Sentinel that defines the parameters of a specific application event. For monitoring the activities of EBICS Gateway you have three Tracked Objects:

l XFBTransfer – to generate messages concerning the processing of exchanged messages. XFBTransfer is provided as part of the Axway Gateway delivery. For more information about this Tracked Object, see XFBTRANSFER Sentinel Tracked Object on page 164.

l EBICSINI – to generate and send Client subscriber initiation processes (key exchange and approval). EBICSINI Tracked Object definition is provided inside the server\data\conf\sentinel\ebicsini.xml file. It must be imported in Sentinel

Server before using it. For more information about this Tracked Object, see EBICSINI Sentinel Tracked Object on page 169.

l HEARTBEAT – Heartbeat messages are sent by the EBICS Gateway Server regularly to indicate that it is up and running. It is possible to configure Sentinel so that it hides these messages in normal time and just triggers alerts when no more heartbeat is received. This is useful for monitoring the health of the EBICS Gateway Server. For more information about this Tracked Object, see HEARTBEAT Sentinel Tracked Object on page 171.

Note that you use the Axway Installer to configure the activation or deactivation of each Sentinel tracking individually.


4 Monitoring EBICS Gatewayprocesses

XFBTRANSFER Sentinel Tracked ObjectEBICS Gateway Server generates and sends an XFBTransfer notification message to Sentinel each time a message it is processing has a change in transfer state.

Transfer states

Fetch transfer states

State Description

FAILED This may be the first event of the transfer if the transfer is rejected by the Server. This may occur, for example, if the Transfer Request has an invalid signature, or the EBICS User is unknown by the Server. In this case, the RETURNCODE and RETURNMESSAGE contain the standard EBICS value.

Some attributes may be missing in Sentinel if missing parameters are the cause of the failure, or if a failure interrupts the complete collection of parameters.

TO_EXECUTE The transfer has been accepted by the Server and will start immediately. All parameters have been checked and are available in Sentinel.

SENT The transfer is complete and the data has been sent to the EBICS Gateway Client.

Send transfer statesOn client Sends, tracking goes beyond the EBICS Gateway Server events. It includes the transfer up to the back-end application.

State Description

FAILED This may be the first event of the transfer, if the transfer is rejected by the Server. This may occur, for example, if the Transfer Request has an invalid signature, or the EBICS User is unknown by the Server. In this case, the RETURNCODE and RETURNMESSAGE contain the standard EBICS value.

Some attributes may be missing in Sentinel if missing parameters are the cause of the failure, or if a failure interrupts the complete collection of parameters.



State Description

TO_EXECUTE The transfer has been accepted by the Server and will start immediately. Most of the parameters have been checked and are available in Sentinel.

RECEIVED The transfer has been completed and the data is available for further processing by the EBICS Gateway Server. Depending upon Server configuration, the next step might be VEU processing, post-processing or DFile handling.

ROUTED The data is transferred via post-processing to the back-end applications. This can be a JMS bridge, a Gateway transfer or a custom process.

ROUTE_FAILED Post-processing has failed, and requires a technical intervention.

COPIED This state is sent during the post-processing. When the data file has been copied or when the proof file has been written, a notification is sent to Sentinel. The attribute RETURNMESSAGE contains the full path name of the file.

ENDED_TO_ACK For a DFile, when a manual release is required. The EBICS Gateway Server is waiting for a manual acknowledgement from the EBICS Gateway Server operator.

ACK_USER For a DFile, the EBICS Gateway Server operator has validated the transfer. This transfer is forwarded to a back-end application.

NACK_USER For a DFile, the EBICS Gateway Server operator has not validated the transfer. This transfer is held on the EBICS Gateway Server and is not forwarded to the back-end application.

WAIT_FOR_SIGN For VEU handling, the EBICS Gateway Server has detected that additional signatures were needed to accept the transfer. Meanwhile, the data is stored internally on the EBICS Gateway Server and not available for the back-end application.

SIGNATURE_ADDED Either a new signature has arrived independently of the initial transfer (VEU), or several signatures are embedded within the same transfer.

In both cases, for each new signature, a new Sentinel notification with status SIGNATURE_ADDED is generated. The SUSER attribute contains the Signer name.

NACK_SIGNATURE For VEU handling, the EBICS Gateway Server has received a new (disagreement) signature for the transfer. The transfer is canceled.



XFBTransfer attributesThe following attributes contain data that is sent to the Sentinel Server.

Attribute Name Description

CREATIONDATE Creation date

CREATIONTIME Creation time

CUSTOMERID

CYCLEID Identifier of the Tracked Event, in this case, the message handling on the EBICS Gateway Server.

DIRECTION l Fetch: E (Emission)

l Send: R (Reception)

ENDDATE Processing end date. Set to the date when state is received, empty otherwise

ENDTIME Processing end time. Set to the time when state is received, empty otherwise.

EOTPROCEDURE Name of the Send script

EVENTDATE Date of the generation of the event (DD/MM/YYY)

EVENTTIME Time of the generation of the event (hh:mm:ss)

FILENAME Complete path to the file received by the Bank (Attention: this value can be subsequently removed from the system.

FILESIZE Size of the file in bytes.

ISALERT 1 = error

ISEND Accepts the values:

0: The message handling is not complete

1 or 2: The message handling is complete

ISEXCEPTION 1 = error




LOCATION Local identifier of the EBICS Gateway Server.

This value is the EbicsLocalSite attribute value that is defined in the configuration.properties file. See EBICS Gateway Server configuration file on page 187.

If EBICS Gateway Server does not locate this value, the value defaults to the hostname of the EBICS Gateway Server configuration.

MACHINE Type of platform. Possible values:

l EBICS-UNIX

l EBICS-NT

MONITOR EBCS

MONITORVERSION Product version

Example: 3.0.0

ORIGINALSENDERID SystemID if used on the transfer.

POSITION NUMBER Order Number for the send transfer

PRODUCTNAME Name of the product generating the event

PROTOCOL EBICS

PROTOCOLID Value of the Protocol version/revision.

For example, H003.1.

PROTOCOLPARAMETER Send: No value

Fetch: "From=yyyy-mm-dd To=yyyy-mm-dd"

RAPPL Customer name in the <name1> parameter in the UI

RECEIVERID l Send: bankHostId

l Fetch: userId

RETURNCODE Value of the EBICS code returned by the EBICS Gateway Server.

000000 = OK

RETURNMESSAGE Label returned by the EBICS Gateway Server

SAPPL User name in the <name2> parameter in the UI




SENDATE Send date

SENDERID l Send: userId

l Fetch: bankHostId

SENDTIME Send time

SIGNENTITYOBJECTID Reserved for future use

SIGNENTITYOBJECTTYPE Reserved for future use

STARTDATE Processing start date

STARTTIME Processing start time

STATE State of the message handing.

SUSER User name of one of the signers of the transfer.

Note: You cannot find the SystemID inside the SUSER. It is stored inside the attribute OriginalSenderId.

TRADEDESTINATION l Send: bankHostID

l Fetch: customerId

TRADEORIGINATOR l Send: customerId

l Fetch: bankHostId

TRADEREQUESTTYPE FileFormat

Example: pain.001.001.02.mct

TRADESERVICE OrderType (3 characters)

TRANSFERTYPE Set to "T" if it is a test message. (Sent for orderType FUL.* only)



EBICSINI Sentinel Tracked ObjectEBICS Gateway Server generates and sends an EBICSINI notification message to Sentinel each time there is a state change in an EBICS User initialization processing sequence.

EBICSINI processing state changesThe following table describes the processing events that lead to EBICSINI notifications being generated and sent to Sentinel.

Beginning state

Ending state

Change trigger event

<Initialization> NEW EBICS User creation in Server GUI

NEW WAITING_HIA

Subscriber sends an INI

EBICS returns "000000" code for an INI transfer

NEW WAITING_INI Subscriber sends a HIA

EBICS returns code "000000" for a HIA transfer

WAITING_HIA INITIALISED EBICS Channel state is set to "all keys received, waiting for release"

WAITING_INI INITIALISED EBICS Channel state is set to "all keys received, waiting for release"

INITIALISED ACTIVE Modifier/Validator releases the subscriber

ACTIVE LOCKED_BY_BANK

Modifier/Validator either:

l Locks the subscriber, without deleting subscriber keys

l Deletes the subscriber keys

ACTIVE LOCKED_BY_SUBSCRIBER

Subscriber sent an SPR

EBICS returns code "000000" for an SPR transfer

LOCKED_BY_BANK

NEW Modifier/Validator either:

l Unlocked the Subscriber

l Created a new EBICS Channel

LOCKED_BY_SUBSCRIBER

WAITING_INI

or

WAITING_HIA

The exit of the LOCKED_BY_SUBSCRIBER state is defined by the Send of either the INI or the HIA. The NEW state is skipped.



EBICSINI attributesThe following attributes contain data that is sent to the Sentinel Server.


State One of the following message handling states:

l NEW

l WAITING_HIA

l WAITING_INI

l INITIALISED

l READY

l LOCKED_BY_BANK

l LOCKED_BY_SUBSCRIBER

Bank Protocol Identifier for the Bank (BankHostId for EBICS)

CustomerId Protocol Identifier for the Subscriber (CustomerId)

UserId Id of the user who is affected by the STATE

IssuerUserId Protocol Identifier for the User that sent the OrderType

Key The key contains the EBICSHostId, the CustomerId and the UserId

ModificationIssuer Identification of the issuer of the state transition:

l DECLARED: Identification of the GUI user who created the User

l NEW: Identification of the GUI user who created the EBICS User

l ACTIVE: Identification of the GUI User who released the User

l LOCKED_BY_BANK: Identification of the GUI user who suspended the User

This field may be empty. It describes the state change based on the subscriber Send orderType.

Modification Date & Time

Specifies when the modification happened.

This field is generated for:

l Server GUI modification

l Subscriber send orderType




ValidationIssuer Identification of the issuer of the state transition:

l NEW: Identification of the GUI user who validate the creation of the EBICS Channel

l ACTIVE: Identification of the GUI User who released the User

l LOCKED_BY_BANK: Identification of the GUI user who validated the suspension the User

Validation Date & Time

Specifies when the validation happened

HEARTBEAT Sentinel Tracked ObjectEBICS Gateway Server generates and sends a HEARTBEAT notification message to Sentinel at regular intervals.

HEARTBEAT attributesThe following attributes contain data that is sent to the Sentinel Server.


ProductId The product identifier, it corresponds to the EbicsLocalSite property in the server’s configuration.properties file. Default value is

"AxwayEbicsServer"

Delay The delay between two heartbeat notifications. Note that if the EBICS Gateway Server is in a cluster, each node sends its heartbeat with the same product identifier. So if there are N running nodes, Sentinel should receive N notifications during this delay.

Overflow file for Sentinel trackingYou can define an overflow file for Sentinel tracking. The overflow file stores Sentinel events when the Sentinel Server is not available because of network issues or because the Sentinel Server is stopped. When the Sentinel connection is available again, the next event to come will trigger the sending of previously-stored events.

If Sentinel tracking is enabled, either the message "Using Overflow file" or "No Overflow file defined" is written to the log at the INFO level.



You can configure the name and size of the overflow file in the EBICS Gateway Server configuration.properties file.

Edit the following parameters:

l overflowFile=<overFlowFilePath>

l overflowFileMaxLength=<Max size in Mb of overflowfile>. Default=20

Configure Sentinel monitoring of EBICS Gateway Server

This section provides an overview of the tasks required to set up Sentinel monitoring.

Prerequisites l Install Composer with the Sentinel Enabler

l Install EBICS Gateway Server

Configuration tasks

In EBICS Gateway Server:

Step Task

1 Only if you are using an external application server:

Set the application server environment variables.

See Set the environment variables on page 174.

2 Check that Sentinel tracking is activated in the configuration.properties file. This should have been set during installation.

It is recommended to use the Configure function of the installer if you need to modify the parameters. For details, refer to the Axway EBICS Gateway Installation Guide.



In Composer:For details about these tasks, refer to the Axway Composer and/or Axway Sentinel documentation.

Step Task

1 Create a CommNetwork.

2 Create an Axway Server object to represent Sentinel.

3 Import the Tracked Objects.

See Import Tracked Objects for EBICS Gateway Server monitoring on page 173.

4 Create Sentinel objects for retrieving and displaying the monitored data.

5 Send EBICS Gateway Server objects to the Sentinel Server.

Import Tracked Objects for EBICS Gateway Server monitoring

Axway provides two Tracked Objects for EBICS Gateway Server monitoring:

l XFBTransfer

After you install an instance of the Gateway server, XFBTransfer is included in the importable Gateway Sentinel objects file named XFB_ALL_EN.xml. You can find this file in <Gateway_

install_directory>/extras/Sentinel/.

Alternatively, you can download this file from Axway Support at https://support.axway.com. Go to the Patch section and search for XFB_All_EN.xml, or enter the ID number PAT-00019946.

l EBICSINI

The importable file for this Tracked Object is delivered in the EBICS Gateway installation package. After installing EBICS Gateway Server you will find the file server/data/conf/sentinel/ebicsini.xml.

Import Sentinel Tracked Objects to Composer as follows:

1. Get the Tracked Object XML files as described above.

2. Open a Composer session and then open the Integration-Services workbench.

3. In Composer, select the work folder to which you want to import the object.

4. In the Integration-Services workbench, from the Tools menu select Import Object.

Composer opens the Import Wizard window.

5. Use the navigation tools of the Import Wizard to locate and select the Sentinel Tracked Object files.


https://support.axway.com/


6. Select Next. Then select Update the folder hierarchy.

Composer creates the Tracked Objects:

l XFTTransfer

l EBICSINI

To confirm the creation of these objects in Composer, check in the Monitoring tab, General sub-tab.

Set the environment variables 1. Check the EBICS Gateway Server application server "configurationPath" environment variable.

2. If necessary, modify the variable so that it corresponds to the absolute path of the EBICS Gateway Server configuration.properties file.

For information about the configuration.properties file, and where to locate it, see EBICS Gateway Server configuration file on page 187.


5 Troubleshooting

When you contact Axway Support with a problem, be prepared to provide the following information for more efficient service:

l Product version and build number

l Database type and version

l Operating system type and version

l Description of the sequence of actions and events that led to the problem

l Symptoms of the problem

l Text of any error or warning messages

l Description of any attempts you have made to fix the problem and the results

How to find the product version numberYou can find the version number of EBICS Gateway components as follows:

Installer

When you use the Installer to install, configure, or update EBICS Gateway, the version number is displayed in the screen title.

EBICS Gateway Client

In the UI, click About, at the bottom of the screen.

EBICS Gateway Client displays the version number, for example, 3.1.0.

At startup, EBICS Gateway Client also records the version number in the log.

EBICS Gateway Server

When you are logged in, EBICS Gateway Server displays the following information at the bottom left of the main screen: the version number, (for example, 3.1.0); the build number; and the Business Logics server version on which EBICS Gateway Server is based.

At startup, EBICS Gateway Server also records the version number in the log.

In addition, each tool (Supplier, Injector and Purge) records its version number in the log at startup.


5 Troubleshooting

Troubleshoot EBICS Gateway Server

Cannot stop the embedded application serverProblem: The embedded application server does not stop when you run the jboss-cli command. For example, on UNIX:

./jboss-cli.sh -c --command=shutdown

The log shows a Shutdown error.

Cause: Java 8 is not installed on the system or the JAVA_HOME environment variable is not set correctly. The script jboss-cli is using the Java of the system and not using the product Java mentioned in the standalone.conf file.

Solution: Set the environment variable JAVA_HOME to the JRE provided with EBICS Gateway as follows:

export JAVA_HOME=<install directory>/Java/linux-x86/jre8_u40_64

Cannot stop the embedded application server on Windows Server 2008If you are using Windows Server 2008, you might face the following problem when trying to stop the server using the command line:

C:\Axway\EbicsGateway\server\EmbeddedServer\bin> .\jboss-cli.bat -c -

command=shutdown

Unable to connect due to unrecognised server certificate

Subject - CN=localhost,OU=EBICSServer\ ,O=Axway,L=Puteaux,ST=France,C=FR

Issuer - CN=localhost, OU="EBICSServer ", O=Axway, L=Puteaux, ST=France,

C=FR

Valid From - Thu Jun 12 07:37:18 PDT 2014

Valid To - Wed Sep 10 07:37:18 PDT 2014

SHA1 : 59:7b:d2:d5:7b:4b:8f:2c:ef:4b:15:11:69:95:76:f4:c6:dd:19:1a

MD5 : 5f:06:26:6d:2d:e9:47:fc:a3:c2:05:d3:98:7b:77:09

org.jboss.as.cli.CliInitializationException: Failed to connect to the

controller

at org.jboss.as.cli.impl.CliLauncher.initCommandContext

(CliLauncher.java:278)

at org.jboss.as.cli.impl.CliLauncher.main(CliLauncher.java:241)

at org.jboss.as.cli.CommandLineMain.main(CommandLineMain.java:34)

at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)


5 Troubleshooting

at sun.reflect.NativeMethodAccessorImpl.invoke(Unknown Source)

at sun.reflect.DelegatingMethodAccessorImpl.invoke(Unknown Source)

at java.lang.reflect.Method.invoke(Unknown Source)

at org.jboss.modules.Module.run(Module.java:312)

at org.jboss.modules.Main.main(Main.java:460)

Caused by: org.jboss.as.cli.CommandLineException: The controller is not

available at 127.0.0.1:9993

at org.jboss.as.cli.impl.CommandContextImpl.tryConnection

(CommandContextImpl.java:1028)

at org.jboss.as.cli.impl.CommandContextImpl.connectController


at org.jboss.as.cli.impl.CommandContextImpl.connectController


at org.jboss.as.cli.impl.CliLauncher.initCommandContext

(CliLauncher.java:276)

... 8 more

Caused by: java.io.IOException: java.net.ConnectException: JBAS012144:

Could not connect to https-remoting://127.0.0.1:9

993. The connection timed out

at

org.jboss.as.controller.client.impl.AbstractModelControllerClient.execut

eForResult(AbstractModelControllerCli

ent.java:129)

at


e(AbstractModelControllerClient.java:

71)

at org.jboss.as.cli.impl.CommandContextImpl.tryConnection


... 11 more

Caused by: java.net.ConnectException: JBAS012144: Could not connect to

https-remoting://127.0.0.1:9993. The connection t

imed out

at org.jboss.as.protocol.ProtocolConnectionUtils.connectSync

(ProtocolConnectionUtils.java:119)

at

org.jboss.as.protocol.ProtocolConnectionManager$EstablishingConnection.c

onnect(ProtocolConnectionManager.java

:256)

at org.jboss.as.protocol.ProtocolConnectionManager.connect

(ProtocolConnectionManager.java:70)

at

org.jboss.as.protocol.mgmt.FutureManagementChannel$Establishing.getChann

el(FutureManagementChannel.java:204)


5 Troubleshooting

at org.jboss.as.cli.impl.CLIModelControllerClient.getOrCreateChannel

(CLIModelControllerClient.java:169)

at org.jboss.as.cli.impl.CLIModelControllerClient$2.getChannel

(CLIModelControllerClient.java:129)

at org.jboss.as.protocol.mgmt.ManagementChannelHandler.executeRequest

(ManagementChannelHandler.java:117)

at org.jboss.as.protocol.mgmt.ManagementChannelHandler.executeRequest

(ManagementChannelHandler.java:92)

at


eRequest(AbstractModelControllerClien

t.java:236)

at


e(AbstractModelControllerClient.java:

141)

at


eForResult(AbstractModelControllerCli

ent.java:127)

... 13 more

The command line displays the certificate, but never asks you to trust it.

Workaround:

1. Go to <EBICS Gateway dir>/

server/EmbeddedServer/standalone/configuration/

2. Run:

l keytool -export -keystore ebicsserver.keystore -alias

ebicsserver -file server.cer -storepass axway12345

l keytool -import -file server.cer -keystore <YOUR_WINDOWS_

USER_HOME_DIR>\.jboss-cli.truststore -storepass cli_

truststore -noprompt (for example keytool -import -file

server.cer -keystore C:\Users\Administrator\.jboss-

cli.truststore -storepass cli_truststore -noprompt).

Do not forget to include the leading period in .jboss-cli.truststore.

You should now be able to stop your server.


5 Troubleshooting

Redeploy EBICS Gateway Server application (embedded application server)The deployment directory of the embedded application server is server/EmbeddedServer/standalone/deployments.

Deploy a new bankrechner.ear fileTo deploy a new bankrechner.ear file:

1. Stop the embedded application server.

2. Remove all the EAR files from the deployment directory (make sure you do not leave any old EAR files here).

3. Copy the new bankrechner.ear to the deployment directory.

4. Start the embedded application server.

Redeploy an existing bankrechner.ear fileTo redeploy an existing bankrechner.ear file from the deployment directory:

1. Stop the embedded application server.

2. Go to the deployment directory and search for a file named bankrechner.ear.<SOMETHING> (for example, bankrechner.ear.deployed,

bankrechner.ear.failed, ...). Note that this is NOT the application file

bankrechner.ear. Rename the file to bankrechner.ear.dodeploy (do NOT back

up this file!).

3. Start the embedded application server.

Errors when deploying EBICS Gateway Server applicationTemporary and cached files on an application server can sometimes cause a new deployment to fail. If the deployment was not successful, you should clean the application server cache and remove any temporary files. Then attempt to redeploy the application.


5 Troubleshooting

Log messages when deploying EBICS Gateway Server application on WebSphereOnly valid for EBICS Gateway 3.1.0 SP2 onwards.

When deploying the EBICS Gateway Server application on WebSphere, the following log messages are generated:

[1/16/18 18:30:46:984 CET] 000000a4 annotations E CWWAM0003E: An exception occurred while validating an annotation: com.ibm.wsspi.amm.validate.ValidationException: CWWAM1303E: The interface de.businesslogics.bankrechner.bank.EbicsBankRemote does not define a valid remote business interface; the method generateEncPKCS10CertificationRequest does not conform to RMI rules.

com.ibm.wsspi.amm.validate.ValidationException: CWWAM1303E: The interface de.businesslogics.bankrechner.bank.EbicsBankRemote does not define a valid remote business interface; the method generateEncPKCS10CertificationRequest does not conform to RMI rules

These messages are harmless. You can safely ignore them.

HibernateException messageProblem: You cannot purge large files or perform a post-processing operation and the EBICS Server log file shows an exception with the following cause:

org.hibernate.HibernateException: Transaction was rolled back in a different thread!

Cause: WildFly and EAP have a feature that monitors active database transactions and closes them if they take too much time.

Solution: Increase the recovery timeout value as follows:

1. Open the XML for your application server:

l <EBICS Gateway

dir>/server/EmbeddedServer/standalone/configuration/stand

alone.xml for WildFly embedded, or

l <EBICS Gateway dir>/server/EAP_components/conf/EAP/ebics-

domain.xml for EAP

2. Locate the following block and update the default-timeout value (seconds):

<subsystem xmlns="urn:jboss:domain:transactions:2.0">

<core-environment node-identifier="axwfs-00001">


5 Troubleshooting

<process-id>

<uuid/>

</process-id>

</core-environment>

<recovery-environment socket-binding="txn-recovery-environment"

status-socket-binding="txn-status-manager"/>

<coordinator-environment default-timeout="300"/>

</subsystem>

Note The optimum value depends on your usage and load.

Purge Send with zip does not create zip archiveProblem: You perform a purge and it is successful. However, no zip archive is created. The log contains a message such as:

2015-12-24 12:44:49,533 - [main] INFO (Purge.zipBackupDir:1330) - Nothing to archive, skipping zip creation

Cause: Purge binaries are not located on same disk as the files to purge.

Solution: Use the purge command --backupDirectory (-bdir) option to specify the directory used to store temporary files before archiving. This directory must be on the same disk as the files to purge.

For more details see Purge command line on page 157.


5 Troubleshooting

Log filesLogs are generated inside the following folders. These paths are the default paths, and may have been changed inside the related configuration files.

EBICS Server:

Main Server:

Embedded Server:

<EBICS Gateway dir>/server/ EmbeddedServer/standalone/log/server.log

EAP (cluster):

<EBICS Gateway dir>/server/ EAP_components/runtime/<Node name>/logs

WebSphere:

No default

Tools:

Injector:

<EBICS Gateway dir>/server/Injector/logs/injector.log

Supplier:

<EBICS Gateway dir>/server/Supplier/logs/supplier.log

Managed File Transfer:

<EBICS Gateway dir>/server/Send/tmp/*.trace

EBICS Client:

Main Server:

<EBICS Gateway dir>/client/log/ebicsClient*.log

Managed File Transfer:

<EBICS Gateway dir>/client/mft/tmp/*.trace


Appendix A: Configuration files

This appendix provides information about the EBICS Gateway configuration files:

EBICS Gateway Client configuration files on page 183

EBICS Gateway Server configuration file on page 187

EBICS Gateway Client configuration filesThis section describes the EBICS Gateway Client configuration files.

Important: All configuration should be done through the installer. The initial configuration is defined when you first install the product. At any time after installation you can use the installer's Configure function to reconfigure the product. Note that EBICS Gateway Client must be stopped before you use the Configure function. For details, and important notes, refer to "Configure an existing EBICS Gateway installation" in the EBICS Gateway Installation Guide.

The configuration files are described here for reference purposes only. If you modify these files manually you risk losing the changes!

Overview of configuration files on page 183

database.properties on page 184

ebicsclient.properties on page 184

jetty-secure.xml on page 184

secureRelayConf.xml on page 185

security.properties on page 185

Overview of configuration filesThe following files are used to configure EBICS Gateway Client.

File Description

conf/database.properties Contains the database properties

conf/ebicsclient.properties Contains general configuration properties for EBICS Gateway Client



File Description

conf/jetty/jetty-secure.xml Jetty configuration file. Contains network and TLS settings.

conf/secureRelay/secureRelayConf.xml Secure Relay-related configuration properties

conf/security/security.properties PassPort-related configuration properties

Most of the parameters are self explanatory and are commented inside the configuration files. In some cases, additional information is provided in this section.

database.propertiesThe database.properties file is located in <EBICS Gateway dir>/client/conf.

ebicsclient.propertiesThe ebicsclient.properties file contains general configuration properties. The file is located in <EBICS Gateway dir>/client/conf.

jetty-secure.xmlThe jetty-secure.xml file contains information related to network use and network security, such as TLS and related algorithms. The file is located in <EBICS Gateway dir>/client/conf/jetty.

jetty-secure.xml parameter information

Parameter Description

keyStorePath Path to the file that secures the API (to secure the connection between the UI and the API)

keyStorePassword Password that protects this keystore




host Binding address of the client.

Examples:

l 127.0.0.1 or localhost allows the client to listen only to connections coming from localhost.

l 0.0.0.0 accepts everything.

port API port (this is the port of the UI)

ExcludeProtocols List of HTTPS protocols that are forbidden.

IncludeCipherSuites List of cipher suites that are allowed, in order of preference.

For information about modifying the TLS settings, see EBICS Gateway Client TLS configuration on page 26.

secureRelayConf.xmlThe secureRelayConf.xml file contains Secure Relay-related configuration properties. The file is located in <EBICS Gateway dir>/client/conf/secureRelay.

security.propertiesThe security.properties file contains security-related configuration properties for PassPort and for the outbound (EBICS) connection. The file is located in <EBICS Gateway dir>/client/conf/security.

security.properties parameter information


psDomain The PassPort domain used to store the protocol-related credentials (certificates, key pairs, and so on) required by EBICS Gateway Client.

containerPrefix The prefix for the name of the PassPort entities (container) used to store the credentials.




componentInstance This is a standard PassPort configuration field. In EBICS Gateway Client it is used after containerPrefix to ensure unique names for

all PassPort entities.

https.supportedProtocols Supported TLS/SSL protocols for the HTTPS connection used for EBICS communications.

https.supportedCipherSuites Supported cipher suites for the HTTPS connection used for EBICS communications.

For information about modifying the TLS settings, see EBICS Gateway Client TLS configuration on page 26.

Refer to the PassPort Administrator Guide for information about the PassPort-specific parameters.



EBICS Gateway Server configuration fileThis section describes the EBICS Gateway Server configuration.properties file.

Overview on page 187

Sentinel tracking configuration on page 188

Gateway link configuration on page 189

PassPort configuration on page 190

XML security properties on page 192

Configure exits on page 193

Advanced EBICS Gateway Server configuration on page 194

OverviewThe configuration.properties file contains a set of attributes that determine the behavior of EBICS Gateway Server.

Important: All configuration that can be done through the installer must be done through the installer.

The initial configuration is defined when you first install the product. At any time after installation you can use the installer's Configure function to reconfigure the product. Note that EBICS Gateway Server must be stopped before you use the Configure function. For details, and important notes, refer to "Configure an existing EBICS Gateway installation" in the EBICS Gateway Installation Guide.

The configuration file properties are only described here for reference purposes. If you modify these properties manually you risk losing the changes!

By default, the configuration.properties file is located in:

<EBICS Gateway dir>/server/data/conf

For WebSphere Application Servers:

l You can copy the file anywhere on the host, as long as the classpath indicates its location.

l Alternatively, you can modify the configurationPath environment variable that contains

the full path to the configuration.properties file inside the WebSphere

configuration.



Sentinel tracking configurationHere are the properties related to the Sentinel configuration inside EBICS Gateway Server.


useSentinel Sentinel tracking:

l false: (default) No Sentinel tracking

l true: Sentinel for tracking activated

trackingOptions This property is only used if the "useSentinel" value is set to "true".

Should contain either or both of the values:

l TRANSFER (use with XFBTransfer Tracked Object)

l USER_INIT (use with EBICSINI Tracked Object)

If both values are used, the values are separated with a comma.

Example:

trackingOptions=TRANSFER,USER_INIT

Sentinel_hostname Hostname of the Sentinel Server.

Default = localhost

Change if useSentinel is set to true.

Sentinel_port Notification port of the Sentinel Server (auto port).

Default = 1305

Change if useSentinel is set to true.

EbicsLocalSite Enter an alias for the EBICS Gateway Server.

When the EBICS Gateway Server generates notifications for Sentinel, it uses this value in the LOCATION attribute of the XFBTransfer event message.

If it does not locate this value, the value defaults to the hostname of the EBICS Gateway Server configuration.

EbicsServerVersion This value is set by default to the correct version for the current release.

When the EBICS Gateway Server generates notifications for Sentinel, it uses this value in the MONITORVERSION attribute of the XFBTransfer event message.

It is mainly intended for use by Axway Support, in the event of operating incidents.




TrackedObjectName Name of the Sentinel Tracked Object to be used for tracking transfers.

One or both of the following:

l XFBTransfer

l Any Tracked Object compatible with EBICS tracking. This means that several attributes from XFBTransfer are used. We suggest you copy the XFBTransfer Tracked Object and rename the copy to use this feature.

For detailed information about Sentinel tracking services, refer to the Axway Sentinel documentation.

TrackedObjectVersion Version of the Sentinel Tracked Object.

For detailed information about Sentinel tracking services, refer to the Axway Sentinel documentation.

overflowFile Path name of the overflow file. EBICS Gateway Server must be granted write permission for this file.If the path name is empty, the overflow file is not defined.

overflowFileMaxLength Maximum allowed file length for the overflow file (in Megabytes).If the overflow file is full, new events will be lost.

Gateway link configurationHere are the properties related to the Gateway connectivity inside EBICS Gateway Server. These properties concern the triggering of a Gateway transfer following an EBICS Send transfer received by the EBICS Gateway Server.


useGateway Gateway triggering:

l false: (default) No Gateway triggering

l true: Gateway triggering activated

p_home_dir Gateway installation directory.

Change if useGateway is set to true.

mft_home_dir FEX_Ebics_Windows_MFTServer installation directory.

Change if useGateway is set to true.

client_home_dir EBICS Gateway Client installation directory



PassPort configurationHere are the properties for PassPort configuration inside EBICS Gateway Server.


passport.serverHostNames PassPort server host name

security.encoding.type The encryption algorithm: NONE, AES or B64. If any other value is used, the password is considered as a clear password.

The encryptor tool that was available in previous versions is no longer supplied. The Installer now manages password encryption (either during installation, or later when using the Configure function).


passport.serverPort PassPort unsecured server port. If this property is set and passport.securedServerPort is not set, the handshake between PassPort and EBICS Gateway Server is not secured. Default value is 6090.

passport.securedServerPort PassPort secured server port. If this property is set, the handshake between PassPort and EBICS Gateway Server is secured. Default value is 6453.

passport.sharedSecret PassPort shared secret used to authenticate EBICS Gateway Server in PassPort. This parameter is set during the installation of PassPort. This value can be modified on the PassPort side using the Configure function of the Installer.

passport.tsPath Path to the truststore used to secure the PassPort communication. A truststore is provided inside <EBICS

Gateway dir>/server/data/conf/passport/

passport_truststore.jks. This path must be

accessible from the application server.

passport.tsType Type of truststore. Default value is jks.




passport.ksPath Path to the keystore used to secure the PassPort communication. This keystore is not provided and is generated during the handshake with PassPort. The path must represent a non existing file (for example <EBICS Gateway

dir>/server/data/conf/passport/ passport_

keystore.jks and must be accessible from the application

server.

passport.ksType Type of keystore. Default value is jks.

passport.ksPassword The keystore password

passport.csdPath Path to the CSD file. The CSD file is provided inside <EBICS

Gateway dir>/server/data/conf/passport/

Ebics_CSD.xml. This path must be accessible from the

application server.

passport.defaultUsersDomain Default PassPort user domain to use if, during the login, no domain is specified. If a domain is specified during the login (domain/login), then the value set in this parameter is ignored.

Note: This value is case sensitive.

Optional propertiesThe following properties are optional and do not usually require changing:


passport.sslVerifyHostname Enables the TLS hostname verification. Default value is false.

passport.cacheSize Cache size of the requests performed by the EBICS Gateway Server to PassPort. Default value is 1000.

passport.connectionTimeout Time out of the PassPort connection. Default value is 0.

passport.inactiveCache Disable the cache. Default value is false.

passport.maxConnectionsPerHost Maximum connections per hosts. Default value is 10.

passport.maxTotalConnections Maximum number of connections to PassPort. Default value is 20.



XML security propertiesHere are the properties related to the encryption of data on disk in EBICS Gateway Server. Truststore credentials are used for encryption, while keystore credentials are used for decryption. All parameters are mandatory.


xmlsec.encryptionMethod Possible values:

l NONE (default)

l XMLEncryption

If NONE, all other parameters are ignored.

xmlsec.keystore Filename of the keystore to use

xmlsec.ksType Keystore type.

Possible values: JKS

xmlsec.ksPassword Password used to access the keystore

xmlsec.keyAlias Alias used to retrieve the private key

xmlsec.keyPassword Password used to access the private key

xmlsec.truststore File name of the truststore to use. This is where recipients' certificates are stored.

xmlsec.tsPassword Password used to access the truststore

xmlsec.recipientAlias List of recipient aliases in the truststore. Each value is separated by a comma.

Example: ebicsserver,integrator,cft

xmlsec.encryptionAlgorithm Possible values:

l AES_128

l AES_192

l AES_256 (default)

l AES_128_GCM

l AES_192_GCM

l AES_256_GCM




xmlsec.keyIdentifier Possible values:

l IssuerSerial (default)

l KeyValue

l X509KeyIdentifier

xmlsec.keyEncryptionAlgorithm Possible values:

l RSA_V1_5

l RSA_OAEP

l RSA_OAEP_MGF1P (default)

xmlsec.keyMGFAlgorithm Possible values:

l SHA_1

l SHA_224

l SHA_256 (default)

l SHA_384

l SHA_512

xmlsec.keyDigestAlgorithm Possible values:

l SHA_1

l SHA_224

l SHA_256 (default)

l SHA_384, SHA_512

For details about encryption, see Encrypt data at rest in EBICS Gateway Server on page 124.

Configure exitsEBICS Gateway Server proposes two different File copy exits to enable custom handling on Payment Status Report (PSR) fetch. More details are available upon request from Axway Support.



Advanced EBICS Gateway Server configuration

Show/hide Servlet versionTo show/hide the EBICS Gateway Server version in the servlet (https://yourserverhost:yourportnumber/ebics/EbicsServlet ), set the following property in the configuration.properties file:


servlet.version.hide false (by default) displays the version of the EBICS Gateway Server when accessing the servlet URL: (https://yourserverhost:yourportnumber/ ebics/EbicsServlet)

true displays a blank page for this URL


Documents

Axway EBICS Gateway Administrator Guide