Electronic Signature Version March Administrator Guide

Transcription

1 Electronic Signature Version March 2018 Administrator Guide

2 Copyright 2018 Axway All rights reserved. This documentation describes the following Axway software: Axway Electronic Signature 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.

3 Contents Preface 8 Who should read this guide 8 Electronic Signature documentation set 8 Related documentation 8 Support services 8 Training services 9 Accessibility 10 Screen reader support 10 Support for high contrast and accessible use of colors 10 1 Overview 11 Installation configurations 11 EBICS Client functionality 12 Electronic Signature functionality 12 Electronic Signature processing 12 Financial Integration products 13 2 Configure Electronic Signature 14 Configuration tool 14 Configure security tokens 14 Configure log levels 14 Configure TLS 15 Electronic Signature directory structure 15 Use the Electronic Signature Configuration tool 15 General settings 15 Security settings 16 Database settings 17 Access manager settings 18 Transporter configuration settings 19 Optional settings for Sentinel and Secure Relay 19 Final configuration step 21 Secure Electronic Signature 21 Configure Electronic Signature security tokens 21 Protect Electronic Signature against path manipulation 22 Change default certificates 23 Configure inbound Electronic Signature TLS connection 24 Modify outbound Electronic Signature TLS configuration 25 Secure database connection with TLS 26 Axway Electronic Signature Administrator Guide 3

4 Modify TLS connection with PassPort 28 Configure the TLS connection between Electronic Signature and Sentinel 28 3 Use Electronic Signature with Interchange 30 Prerequisites 30 Configure Interchange 30 Send EBICS requests using MMD files 31 MMD XML file examples 31 Inline processing for Interchange / Electronic Signature integration 33 About inline processing 33 How to format PeSIT metadata for Electronic Signature 34 Copy the JAR file 35 Configure Interchange for inline processing 35 Configure Payment Status Report inline 36 Modify the default inline implementations 36 Update payment status with PSR 37 About PSR 37 About PSR integration in Electronic Signature 37 Configure PSR integration with Interchange 38 Integrate Sentinel with Electronic Signature and Interchange 41 Introduction 41 Configure Electronic Signature for end-to-end Sentinel integration 42 Sentinel attribute names 42 4 Use Electronic Signature with Gateway 46 Prerequisites 46 Use Transfer CFT to connect to the back-end application 47 Behavior principles: User message 47 Send User message syntax 47 Fetch User message syntax 48 Configure Gateway to connect to Transfer CFT 48 Configure Gateway for Send and Fetch 48 Configure Gateway 48 Configure Transfer CFT 51 Update payment status with PSR 52 About PSR 52 About PSR integration in Electronic Signature 53 Configure PSR integration with Gateway 54 Limitation for Bank and Customer names 54 Integrate Sentinel with Electronic Signature and Gateway 55 Introduction 55 Configure Electronic Signature for end-to-end Sentinel integration 56 Sentinel attribute names 56 Integrate Electronic Signature with Gateway and Sentinel 60 Axway Electronic Signature Administrator Guide 4

5 Configuration file contents 60 EBICS Client administration 61 About command lines 62 Syntax 62 Commands per use case 63 Parameter list 67 Import the TLS Bank certificate to the client keystore 69 General procedure to create an EBICS user 69 Deactivate a proxy server for a bank 70 Send and Fetch transactions with embedded EBICS Client 70 General behavior 70 Request definition 70 Explanation of tags 71 End of transfer callback variables 73 Use embedded EBICS Client with a DMZ proxy 74 About Secure Relay 74 Configure embedded EBICS Client for Secure Relay 74 Configure embedded EBICS Client with an HTTP proxy 75 5 Control Electronic Signature 76 Command scripts 76 Start Electronic Signature 77 Connect to the Electronic Signature UI 77 Stop Electronic Signature 78 Check the Electronic Signature status 78 Start and stop Electronic Signature in Windows service mode 78 Start Electronic Signature 78 Stop Electronic Signature 79 6 Manage Electronic Signature Agent 80 Preparation 80 Download Electronic Signature Agent 80 Install Electronic Signature Agent 81 Graphical mode 81 Silent mode 81 Console mode 82 Change the port value 82 Change the port value in Electronic Signature Agent 82 Change the port value in Electronic Signature 83 Display the port used by the Agent at startup 83 How to import certificates 83 Import a certificate via the REST API 83 Start Electronic Signature Agent 84 Stop Electronic Signature Agent 84 Axway Electronic Signature Administrator Guide 5

6 Access the log files 84 Troubleshooting 85 7 Extend support to other formats 86 Payload parser 86 Modify the parser exit 86 8 Develop exits for Electronic Signature 88 Overview of the exit framework 88 Description of the exit framework API 88 Development 90 Prerequisites 90 Develop exits 91 Sample exit 94 9 Use PassPort with Electronic Signature 97 Post-installation 97 Start Electronic Signature for the first time 97 Create Administrator and Signer users in PassPort 98 Update PassPort properties 98 Import Signer users from PassPort 98 Define users who will receive notifications 99 PassPort self-registration 99 Renew PassPort certificates 100 Default certificates provided by PassPort 100 Non-PassPort certificates Purge payments in Electronic Signature 101 Command syntax 101 Parameter usage 102 Database records Single sign-on using SAML 104 Service Provider 104 Identity Provider 104 User Agent 104 Security Assertion Markup Language (SAML) 104 An assertion 105 Electronic Signature implementation behavior 105 SAML 2.0 compliance 105 Login sequence 105 User authentication use cases 106 Logout sequence 106 Logout initiated by Electronic Signature 106 Axway Electronic Signature Administrator Guide 6

7 Logout initiated by the Identity Provider 107 SAML SSO configuration 107 Prerequisites 107 Configure SAML SSO 107 Configure sso-service-provider.xml for Electronic Signature 110 Service Provider metadata 111 SAML SSO post-configuration tasks 111 New Electronic Signature installation 111 Migration from existing Electronic Signature installation 111 SAML SSO troubleshooting 112 Cannot access my application even after a successful login 112 After I login to the Identity Provider page I am not redirected to the application page 112 Appendix A: configuration.properties file 113 Electronic Signature 114 Electronic Signature configuration section 114 Database configuration section 117 UI configuration section 117 Parser configuration section 118 Payment details section 118 configuration section 118 Transporter configuration section 120 Interchange configuration section 120 PSR scanning configuration section 121 Common SSO configuration section 122 PassPort configuration section 122 Sentinel configuration section 124 Sizing configuration section 125 Exit configuration section 125 Cipher Key Configuration 126 Configuration for accepted file system paths 127 EBICS Client 128 Configuration of the signature protocols section 128 Configuration of order type counter section 128 Configuration of scanning file system section 128 Network configuration section 130 Appendix B: Directory structure 132 Appendix C: securerelayconf reference 134 Master Agent 134 Router Agent 135 Axway Electronic Signature Administrator Guide 7

8 Preface This guide describes how to configure and administer Electronic Signature. The guide includes details of the different configuration files. Who should read this guide This guide is intended for administrators who integrate and manage Electronic Signature in their production environment. It is assumed that you have a good understanding of networks and Java environments. Electronic Signature documentation set To find all available documents for this product version: 1. Go to 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 documentation The following reference documents are available on the Axway Documentation portal at Axway Supported Platforms Lists the different operating systems, databases, browsers, and thick client platforms supported by each Axway product. Axway Interoperability Matrix Provides product version and interoperability information for Axway products. Support services The Axway Global Support team provides worldwide 24 x 7 support for customers with active support agreements. support@axway.com or visit Axway Support at Axway Electronic Signature Administrator Guide 8

9 Preface Training services Axway offers training across the globe, including on-site instructor-led classes and self-paced online learning. For details, go to: Axway Electronic Signature Administrator Guide 9

10 Accessibility Axway strives to create accessible products and documentation for users. This documentation provides the following accessibility features: Screen reader support Support for high contrast and accessible use of colors Screen reader support Alternative text is provided for images whenever necessary. The PDF documents are tagged to provide a logical reading order. Support for high contrast and accessible use of colors The documentation can be used in high-contrast mode. There is sufficient contrast between the text and the background color. The graphics have the right level of contrast and take into account the way color-blind people perceive colors. Axway Electronic Signature Administrator Guide 10

11 Overview 1 Axway Electronic Signature is an optional product that can be used in Financial Integration. The Electronic Signature product includes an embedded EBICS Client. This version is able to handle EBICS T as well as EBICS TS protocols. You must install Electronic Signature if you require EBICS Client functionality. The exact functionality depends on your license key and the installed options. This is an overview of the chapter: Installation configurations on page 11 EBICS Client functionality on page 12 Electronic Signature functionality on page 12 Electronic Signature processing on page 12 Financial Integration products on page 13 Installation configurations Various installation configurations are possible depending on whether you require EBICS T or EBICS TS functionality and which file transfer product you are using. File transfer product For EBICS T, use: For EBICS TS, use: Axway Gateway EBICS Client (embedded in Electronic Signature) Electronic Signature + EBICS Client (embedded in Electronic Signature) Axway Interchange EBICS functionality in Interchange* Electronic Signature + EBICS functionality in Interchange* * For information about the EBICS functionality in Interchange, refer to the Interchange documentation. Axway Electronic Signature Administrator Guide 11

12 1 Overview EBICS Client functionality EBICS Client in Electronic Signature provides the support for the EBICS protocol in Gateway on the client side (typically in Financial Integration for corporates). You must start Electronic Signature in order to manage the embedded EBICS Client and use it for transfers. Electronic Signature functionality Electronic Signature enables authorized users to sign and/or validate electronic payments. There are two types of users: transport users and signer users. A transport user must be selected in the case of validation-only payments. The UI includes two distinct parts. One is designed for signers (for example, the corporate treasurer) and the other for the administrator. Signers use a security token to sign payments. The administrator manages users and signing rules. Before being able to send a signed file, the end-user must initialize the connection with the bank. The Electronic Signature application provides services to manage this initialization. After initializing with a bank, a payment file can be sent to the Electronic Signature application, through the Communication layer, using the PeSIT protocol for example. A user can sign the payment file which is then sent to the bank. Electronic Signature processing The following figure shows the general workflow for payment files being processed by Electronic Signature. Axway Electronic Signature Administrator Guide 12

13 1 Overview Steps Description 1 A back-end application sends a payment file that has to be signed and validated before it is sent to the bank. 2 The incoming file is integrated into the Electronic Signature function. This suspends the routing process of the file. 3, 4 Authorized users view the file, validate, sign or reject it. This step is repeated until the required number of signatures has been reached. 5, 6 When the file has been signed with the required number of signatures, it is sent via the Communication layer to the bank. Financial Integration products Electronic Signature is used as part of the Financial Integration solution with the following Axway products: Interchange (or Gateway) EBICS Server The Communication layer function is managed by either Interchange or Gateway. Several tasks (for configuration and administration) depend on which of these two products you are using with Electronic Signature. Electronic Signature also requires an Oracle or MySQL database. Axway Electronic Signature Administrator Guide 13

14 Configure Electronic Signature 2 This chapter explains how to configure Electronic Signature. Configuration tool After you install Electronic Signature you must use the Configuration tool to configure it before use. You can also use the Configuration tool at any time after the initial configuration to change the settings. For details on how to use the tool, and a list of the parameters that you can set, see Use the Electronic Signature Configuration tool on page 15. configuration.properties file The configuration.properties file is located in <Electronic Signature install dir>/data/conf. When you use the Configuration tool, it modifies the Electronic Signature server configuration.properties file. This file contains many parameters that control the behavior of Electronic Signature and the embedded EBICS Client. You can modify this file directly using a text editor. This is convenient if you just want to check the configuration details or make one or two quick changes. For information about the contents of the configuration file, see configuration.properties file on page 113. Configure security tokens For details about security tokens, see Configure Electronic Signature security tokens on page 21. Configure log levels To access the log files, go to: <Electronic Signature install dir>/data/log The Electronic Signature log configuration file is located in: <Electronic Signature install dir>/data/conf/log4j.properties. You can set the levels of various logs. Axway Electronic Signature Administrator Guide 14

15 2 Configure Electronic Signature Configure TLS Important: Electronic Signature is shipped with a default TLS configuration to help you start testing immediately. However, before using Electronic Signature in a production environment, you must personalize this configuration to make it secure. See Change default certificates on page 23. Electronic Signature directory structure For information about the location of directories and files in Electronic Signature, see Directory structure on page 132. Use the Electronic Signature Configuration tool You can run the Configuration tool in: Graphical mode Console mode Electronic Signature must be stopped before you use the Configuration tool. To start the Configuration tool in graphical mode, go to the Electronic Signature installation directory and run the configure.sh (UNIX) or configure.exe (Windows) file. If you prefer to use console mode, use the command line for your OS: configure.sh -c start /wait configure.exe -c Click Next to customize the configuration of Electronic Signature. You might not see all of the screens listed here. The exact sequence of screens and fields depends on your license key and the choices you make during installation. The database tables are created when you start Electronic Signature. General settings 1. Enter a valid license key for Electronic Signature. 2. Specify a key directory. The key directory is the location for storing the key used to encrypt passwords. Important: Access to this folder must be protected. 3. Enter or modify the values for the configuration parameters. Axway Electronic Signature Administrator Guide 15

16 2 Configure Electronic Signature Field Description HTTP Port Port for the GUI Control Port Local port for the command line SMTP Hostname SMTP server host name SMTP Port SMTP server port number SMTP User Optional login for the SMTP Server SMTP Password Password of the user login for the SMTP Server SMTP Sender The application uses this account to send s Override Domain Name and Port When you select this option, the address of the server differs from the address Electronic Signature uses to send s Domain Name New domain name of the server New HTTP Port New TCP port used by Electronic Signature to send s Security settings Specify the following keystore parameters. Field Description Select Keystore File File that contains private certificates used to secure the connection between the server and the UI Keystore Password Password that enables access to the keystore. The default password for the default keystore is axway12345 Certificate Password Password that enables access to the private certificate. The default password for the default certificate is axway12345 Select Truststore File File that contains public certificates used to secure the connection between Electronic Signature and various products (Sentinel or a database). The truststore is empty by default Axway Electronic Signature Administrator Guide 16

17 2 Configure Electronic Signature Field Truststore Password Description Password that enables access to the truststore. You can provide an optional password for the truststore. The default password for the default truststore is axway12345 Database settings 1. Select the type of database to use: Oracle or MySQL. 2. Select the database options of your choice. The following tables show an overview of the general database options, as well as the options related to each database. Field Description Verify database configuration When you select this option, the application verifies the database parameters For Oracle only Use custom URL TLS connection Oracle database URL connection When you select this option, the application secures the connection to the database through TLS Oracle settings If you selected Oracle, this is an overview of the database options. Field Description SID Oracle database instance name Service Name Oracle TNS Alias Hostname Database hostname Port Number Database port number Connection User Database connection user Connection Password Database connection password Axway Electronic Signature Administrator Guide 17

18 2 Configure Electronic Signature Field Description If you selected the Use custom URL option: Custom URL Database custom URL Connection User Database connection user Connection Password Database connection password MySQL settings If you selected MySQL, this is an overview of the database options. Field Description Database Name Database schema name Hostname Database hostname Port Number Database port number Connection User Database connection user Connection Password Database connection password Access manager settings 1. Select PassPort, Electronic Signature or Common SSO as access manager. 2. If you selected PassPort, specify the PassPort AM connection parameters: Field Description Hostname PassPort hostname Main SSL/TLS Port PassPort secured port Shared Secret Shared secret password defined during PassPort installation Product Instance Electronic Signature instance name in PassPort PassPort API Keystore Password Password that protects the auto-generated keystore Axway Electronic Signature Administrator Guide 18

19 2 Configure Electronic Signature Field Description Use SSO Select this check box if you want to activate the SSO (Single Sign On) mode Product SSO Port PassPort SSO Agent port SSO KeystorePassword Password that protects the SSO keystore Transporter configuration settings Select Gateway or Interchange as communication layer for Electronic Signature. The following table shows an overview of the transporter parameters. Field Description If you selected Gateway: Gateway Installation Directory Modify the default installation directory for Gateway if required. If you selected Interchange: Interchange Hostname Interchange Port Interchange Username Enter hostname, port, user and password information corresponding to your configuration of Interchange. Interchange Password Optional settings for Sentinel and Secure Relay You can specify settings for Sentinel or Secure Relay. Sentinel settings If you want to use Sentinel monitoring, activate this option and enter values that correspond to your configuration of Sentinel. Field Description Activate Sentinel Select this check box to activate Sentinel Axway Electronic Signature Administrator Guide 19

20 2 Configure Electronic Signature Field Description Enable TLS with Sentinel Select this check box to enable TLS with Sentinel Sentinel Hostname Enter a Sentinel hostname Sentinel Port Enter a Sentinel port number Sentinel Overflow Directory Path Enter a Sentinel overflow directory path Sentinel Overflow File Size in MB Enter a Sentinel overflow file size in MB Sentinel Universal Agent Directory Enter a Sentinel Universal Agent directory Secure Relay settings If you want to use Secure Relay, activate this option and enter values that correspond to your configuration of Secure Relay. Field Description Use Secure Relay Select this check box to activate Secure Relay Master Agent Configuration CA certificate Enter a path for the Secure Relay root certificate Master Agent certificate Certificate Password Enter a path for the Secure Relay Master Agent certificate Enter a password. The default value is test Router Agent Configuration Router Agent Hostname Enter the hostname of the Router Agent Administration Port Enter the administration port of the Router Agent Communication Port Enter the communication port of the Router Agent For information about advanced configuration for Secure Relay, for example if you have more than one Router Agent, see Use embedded EBICS Client with a DMZ proxy on page 74. Axway Electronic Signature Administrator Guide 20

21 2 Configure Electronic Signature Final configuration step Click Configure to exit Setup. The Configuration tool configures Electronic Signature with your settings. Secure Electronic Signature At installation time, Electronic Signature is set to restrict inbound and outbound TLS connections to TLS version 1.2 and a limited set of secure cipher suites. This corresponds to today's best security practices. Important: Electronic Signature is shipped with a default TLS configuration to help you start testing immediately. However, before using Electronic Signature in a production environment, you must personalize this configuration to make it secure. The following sections will help you in this process. Configure Electronic Signature security tokens on page 21 Protect Electronic Signature against path manipulation on page 22 Change default certificates on page 23 Configure inbound Electronic Signature TLS connection on page 24 Modify outbound Electronic Signature TLS configuration on page 25 Secure database connection with TLS on page 26 Modify TLS connection with PassPort on page 28 Configure the TLS connection between Electronic Signature and Sentinel on page 28 Configure Electronic Signature security tokens To be able to sign payments, a user needs a valid security token. As an alternative to a security token, for example for testing purposes, you can use a PKCS12 file. The following token types have been tested for use with this version of Electronic Signature: Token Type SafeNet Certinomis Keynectis Ces@mOr Keynectis K.Sign Client to use SafeNet Authentication Client 8.0 SP2 Gemalto RegTool Gemalto RegTool SafeNet Authentication Client 8.0 SP2 Sagem Launcher Axway Electronic Signature Administrator Guide 21

22 2 Configure Electronic Signature Token Type SWIFT 3Skey Client to use Etoken PKI Client Note With the current version, only one of these token types can be used at a time. To use a PKCS12 file, you must import it, using an HTTP Client. Import a certificate via the REST API Before you import a certificate, you must have an HTTP client, such as Postman. To import a certificate via the REST API: 1. Start the Electronic Signature Agent. 2. Open your HTTP client. 3. Make an HTTP PUT request to the URL. This is the request used by default: 4. In the parameter section, select the JSON format. 5. Add your JSON content in the provided text area. This parameter contains strings that are required to import certificates: A PKCS#12 certificate encoded in base64 A clear password associated with this certificate If the certificate is not imported, the HTTP Client returns an error message. Here is an example of JSON content: {"base64encoded":"miikiaibazccclig [ base64 of the certificate which is here truncated ] CgKMM1aR5Q","password":"axway"} Important: Be careful when using a base64 tool. The base64 data must not contain any Carriage Returns or Line Feeds. Protect Electronic Signature against path manipulation Configuration for accepted file system paths Path manipulation issues are security vulnerabilities where an attacker can manipulate a file path to tamper with sensitive files. Electronic Signature includes properties to deal with this type of security vulnerability. Whenever the product needs to access a file or a script from the file system, it will check that the file or the script is inside a safe directory known by the application. Below is the list of the new properties with their default values: Axway Electronic Signature Administrator Guide 22

23 2 Configure Electronic Signature Parameter Description Example payload.directory mft.directory trace.directory This property defines a safe directory that stores the payload. You must have direct access to the payload in this secure directory, otherwise Electronic Signature throws an error. Note: If you are using Interchange as transporter and you performed a fresh install of Electronic Signature , you must create this folder manually and update the payload.directory path in the configuration.properties file. This step is not necessary if you migrated from Electronic Signature or if you are using Gateway as transporter. This property defines a safe directory for all the mft scripts that Axway Gateway uses during the interoperability. You must have direct access to the scripts in this secure directory, otherwise Gateway throws an error. This property defines a safe directory for all the traces the mft scripts generate. You must have direct access to the trace file in this secure directory. Also ensure the trace directory path is inside the mft scripts. data/mft/files program/mft data/mft/tmp Change default certificates Electronic Signature is delivered with a default certificate and keystore, which can be used for test purposes. Before production, you must replace it with a certificate and keystore created specifically for your environment and network configuration. If the new Electronic Signature UI certificate is in a PKCS#12 format, the following procedure explains how to import it in a new keystore, using the standard keytool utility provided in the <jre>/bin directory. If the certificate is already wrapped into a Java keystore, you can skip this procedure. 1. Enter: keytool -keystore <esign.keystore> -storepass <kspassword> -importkeystore -srckeystore <p12_file> -srcstoretype pkcs12 srcstorepass <p12_password> destkeypass keypassword 2. Note the name of your keystore file and the passwords. In this example, the passwords are: Axway Electronic Signature Administrator Guide 23

24 2 Configure Electronic Signature Password kspassword Description corresponds to the keystore password keypassword corresponds to the key password of the imported certificate 3. Replace the original esign.keystore from the data/conf folder with the newly created keystore. 4. Launch the Configuration tool to update the keystore and the key passwords. Configure inbound Electronic Signature TLS connection Connection to the Electronic Signature UI is restricted to TLS version 1.2 by default. In some cases, for compatibility reasons, you might need to lower the HTTPS security level. Important: Be careful when modifying your configuration, as it can lead to weaker security. Any changes that you make will take effect after you restart Electronic Signature. The inbound HTTPS connection (Admin UI) is controlled through parameters in the Electronic Signature configuration section of the configuration.properties file. For information about the parameters in this file, see configuration.properties file on page 113. You can modify the supported TLS protocols and cipher suites for the HTTPS connection by editing the configuration.properties file. At installation time, the file contains the following lines: server.ssl.supportedprotocols=tlsv1.2 server.ssl.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 server.ssl.supportedprotocols The server.ssl.supportedprotocols parameter indicates the supported TLS protocols for the inbound HTTPS connection used for accessing the UI. 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 but do not include a space before or after the comma. server.ssl.supportedciphersuites The server.ssl.supportedciphersuites parameter indicates which cipher suites are supported for the inbound HTTPS connection used for accessing the UI. Axway Electronic Signature Administrator Guide 24

25 2 Configure Electronic Signature By default, the following cipher suites are supported: 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 You can remove or add cipher suite items as required. Use a comma to separate multiple values but do not include a space before or after the comma. Modify outbound Electronic Signature TLS configuration By default, Electronic Signature is configured to use TLS 1.2 for the outbound HTTPS connections for EBICS communications. In some cases, for compatibility reasons, you might need to lower the HTTPS security level. Important: Be careful when modifying your configuration, as it can lead to weaker security. Any changes that you make will take effect after you restart Electronic Signature. The outbound HTTPS connection (EBICS channel) is controlled through parameters in the Network configuration section of the configuration.properties file. For information about the parameters in this file, see configuration.properties file on page 113. You can modify the supported TLS protocols and cipher suites for the HTTPS connection by editing the configuration.properties file. At installation time, the file contains the following lines: conf.supportedprotocols=tlsv1.2 conf.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 conf.supportedprotocols The conf.supportedprotocols parameter indicates the supported TLS protocols for the outbound 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 but do not include a space before or after the comma. conf.supportedciphersuites The conf.supportedciphersuites parameter indicates which cipher suites are supported for the outbound HTTPS connection used for EBICS communications. By default, the following cipher suites are supported: Axway Electronic Signature Administrator Guide 25

26 2 Configure Electronic Signature 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 You can remove or add cipher suite items as required. Use a comma to separate multiple values but do not include a space before or after the comma. Secure database connection with TLS You can configure Electronic Signature to support a secured channel (TLS connection) between Electronic Signature and a MySQL or Oracle database. Prerequisites You are using a MySQL or Oracle database. Refer to "Software prerequisites" in the Electronic Signature Installation Guide for compatible versions. Your database server has been enabled for TLS connection. Check with your database administrator. Enable the use of TLS for the DB connection with Electronic Signature Prerequisite: You selected the TLS option for the database using the Configuration tool. Import TLS server certificate The trusted certificate(s) of the database TLS server(s) for the secured channel must be stored in the truststore. Import the certificate to the truststore as follows: 1. Go to: <Electronic Signature install dir>/data/conf/ 2. Run the command (adapt as required for your environment): keytool -importcert -trustcacerts -file ca.pem -alias dbservercacert -keystore esign.truststore -storepass axway12345 Axway Electronic Signature Administrator Guide 26

27 2 Configure Electronic Signature Database connection error messages The following are common error messages that you may encounter, with a brief explanation of the possible cause of the error. java.sql.sqlrecoverableexception: IO Error: Connection reset Invalid protocol (tcp instead of tcps) specified in URL. java.sql.sqlrecoverableexception: IO Error: The Network Adapter could not establish the connection Invalid Hostname specified in URL. java.net.connectexception: Connection refused: connect Invalid port number specified in URL. java.sql.sqlexception: invalid username/password; logon denied Invalid username/password specified in URL. sun.security.provider.certpath.suncertpathbuilderexception: unable to find valid certification path to requested target Invalid or no truststore path specified in configuration.properties or truststore is not physically present. java.security.unrecoverablekeyexception: Password verification failed Invalid truststore password in configuration.properties. java.io.ioexception: Invalid keystore format Invalid or non-supported truststore type. Cannot be handled by existing security provider. java.io.filenotfoundexception: The system cannot find the file specified The truststore is not present at the path provided in configuration.properties. java.security.nosuchalgorithmexception: SSO KeyStore not available Invalid or non-supported truststore type. No registered SSO provider, for example, OraclePKIProvider is not registered. java.lang.noclassdeffounderror: oracle/security/pki/oraclepkiprovider OraclePKIProvider is used but not defined in PATH. Axway Electronic Signature Administrator Guide 27

28 2 Configure Electronic Signature Modify TLS connection with PassPort By default, Electronic Signature is configured to connect to PassPort using only TLSv1.2. A prerequisite for this TLSv1.2 connection is that PassPort must be running on either: Oracle JRE 1.7 or higher IBM JRE 1.6 or higher. In this case, the PassPort version must be 4.6 SP11 or higher. If needed, you can relax the security requirement by editing the configuration.properties file. However, this is not recommended. The supported TLS version(s) is controlled by the following configuration property: # The PassPort connection is restricted to TLSv1.2 by default. If you wish to relax this restriction, # add the desired protocols separated by a comma. For example: TLSv1,TLSv1.1,TLSv1.2 passport.supported.tls.version=tlsv1.2 As mentioned in the comment, you can add other TLS versions, separated by commas but do not include a space before or after the comma. Configure the TLS connection between Electronic Signature and Sentinel By default, Electronic Signature supports TLSv1.2. Electronic Signature also supports the following protocols, however it is not recommended to use these weaker protocols: TLSv1 TLSv1.1 Configure a secured channel between Electronic Signature and Sentinel as follows: 1. Stop Sentinel. 2. Modify the Sentinel configuration file <Sentinel>/conf/trkServer.xml to use a secure service endpoint. By default, the security is turned off. a. Locate the SocketEventReceiver class. Change the class name to SecuredSocketEventReceiver to enable security. b. Start Sentinel and verify that the secured service is enabled. 3. Modify the Electronic Signature configuration properties <Electronic Signature install dir>/data/conf/configuration.properties to enable the secured channel connection. Axway Electronic Signature Administrator Guide 28

29 2 Configure Electronic Signature sentinel.tls.connection.enabled: Flag that indicates whether the TLS connection with Sentinel is enabled. sentinel.supported.tls.version: The TLS protocol version to use. Default is TLSv1.2. To relax this restriction, uncomment the line and set it to the required TLS version. Possible values: TLSv1, TLSv1.1, TLSv1.2. server.truststore.file: The path to the truststore of the Sentinel certificate. server.truststore.password: The mandatory truststore password. The password must be plain text, but will be encrypted. Note If the server truststore file is not provided, then the default value <Electronic Signature install dir>/data/conf/esign.truststore is used. 4. Export the Sentinel certificate, using the command: keytool -export -keystore keystore.jks -alias tomcat -file sentinel.cer 5. Locate the esign.truststore file at: <Electronic Signature install dir>/data/conf/ 6. Import sentinel.cer into esign.truststore, using the command: keytool -import -alias sentinelservercacert -file sentinel.cer -keystore esign.truststore Axway Electronic Signature Administrator Guide 29

30 Use Electronic Signature with Interchange 3 This chapter applies only if you are using Interchange as the communication layer for Electronic Signature. Prerequisites on page 30 Configure Interchange on page 30 Send EBICS requests using MMD files on page 31 Inline processing for Interchange / Electronic Signature integration on page 33 Update payment status with PSR on page 37 Integrate Sentinel with Electronic Signature and Interchange on page 41 Prerequisites Interchange must be installed (refer to the Interchange Installation Guide). Interchange must be installed with a license key intended for non FIPS compliance usage. Configure Interchange This section explains how to configure Interchange for Electronic Signature. The information provided is just an example. You need to adapt this according to your own requirements. For full details about creating objects, refer to the Interchange Administrator Guide. 1. From the Interchange Start menu folder, launch the Admin shortcut. 2. In the System Management menu, create a Trading Engine (TE). 3. Run the Trading Engine. 4. Create a community. The Routing ID corresponds to the CustomerID of the remote Bank. 5. Define certificate usage. In the community definition, the signing certificate corresponds to the EBICS identification and authentication certificate. The encryption certificate corresponds to the EBICS encryption certificate. 6. Set up an integration pickup exchange for picking up messages from integration. This corresponds to the entry point where files to be sent in EBICS are deposited. This depends on the way Interchange is integrated to the back-end. Examples are: a simple directory scan, an integration through Integrator, an incoming PeSIT message, and so on. Axway Electronic Signature Administrator Guide 30

31 3 Use Electronic Signature with Interchange 7. Set up an integration delivery exchange for routing received messages to integration. Delivery exchange for routing received messages to integration corresponds to the way to retrieve messages fetched in EBICS. Those files must go to the back-end (Integrator for example). 8. Set up a pickup/delivery exchange. In order to communicate with a bank using EBICS, the message protocol must be set to EBICS. 9. Configure inline processing. See Inline processing for Interchange / Electronic Signature integration on page 33. Note that this step is important for integration with Electronic Signature. 10. Create a partner for the community. The partner corresponds to the EBICS Bank that you want to exchange with. The Routing ID corresponds to the EBICS HostId of the remote Bank. 11. Set up EBICS communication between the community and the partner: In Partner detail, set up a delivery exchange. In order to communicate with a bank using EBICS, the message protocol must be set to EBICS. EBICS Bank Settings: Choose the protocol version of the bank (France is H003). Choose Signature version. Electronic Signature handles only A005 signature version. Configure the HTTP settings: Enter the URL of the remote EBICS bank. Delivery exchange name: Enter a meaningful name for this delivery exchange. Save your delivery exchange. 12. Import TLS certificate of the remote EBICS server: Go to your community, click certificates, and TLS trusted root certificates. Add this TLS certificate. For more information about configuring Interchange, refer to the Interchange documentation. Send EBICS requests using MMD files In Interchange, MMD XML files can be used as an alternative to inline processing. In order to use this method, you need to create a File system-type Integration pickup and place the XML files in the location defined for the pickup. Interchange will parse the files and trigger the send or fetch EBICS request. MMD XML file examples Send <?xml version="1.0" encoding="utf-8"?> <MessageMetadataDocument documentid="test_b2" protocol="generic"> Axway Electronic Signature Administrator Guide 31

32 3 Use Electronic Signature with Interchange <Metadata name="from" type="string">customer</metadata> <Metadata name="to" type="string">bank</metadata> <Metadata name="message.waitupdate" type="string">true</metadata> <Metadata name="ebics.action" type="string">send</metadata> <Metadata name="ebics.ordertype" type="string">ful.pain sct</metadata> <Metadata name="ebics.domain" type="string">geopost</metadata> <Metadata name="ebics.sender" type="string">fi-ap</metadata> <Metadata name="ebics.amount" type="string">1000</metadata> <Metadata name="ebics.operationnb" type="string">2</metadata> <Metadata name="message.comment" type="string">business comment</metadata> <MessagePayloads> <Payload id="idfd "> <MimeContentType>text/plain</MimeContentType> <Location type="filepath">c:\pain xml</location> </Payload> </MessagePayloads> </MessageMetadataDocument> where: From is the EBICS HostId of the Bank To is the EBICS customerid message.waitupdate is "true" if the send has to go via Electronic Signature ebics.action is the EBICS request action type (send or fetch) ebics.ordertype is the full EBICS order type ebics.domain is the domain of the payload. The domain is the organizational entity within a company. ebics.sender is the sender of the payload. The sender is the application that initiates a payment flow. ebics.amount is the global amount of the payment that is displayed in the Electronic Signature UI (optional). If a value is specified here it will override the amount parsed from the payload. ebics.operationnb is the number of operation of the given payment file. This value is displayed in the Electronic Signature UI (optional). If a value is specified here it will override the number of operations parsed from the payload. ebics.user.userid is the EBICS userid of the transport user (optional) message.comment is any business information that might help the treasurers to sign a payment. This value is displayed in the Electronic Signature UI (optional). Axway Electronic Signature Administrator Guide 32

33 3 Use Electronic Signature with Interchange Payload id is the id of the payload, this parameter is mandatory Location type is the location and type of payload Fetch <?xml version="1.0" encoding="utf-8"?> <MessageMetadataDocument documentid="test_b2" protocol="generic"> <Metadata name="from" type="string">customer</metadata> <Metadata name="to" type="string">bank</metadata> <Metadata name="ebics.action" type="string">fetch</metadata> <Metadata name="ebics.ordertype" type="string">fdl.camt ara</metadata> <Metadata name="ebics.user.userid" type="string">user</metadata> </MessageMetadataDocument> where: From is the EBICS customerid To is the EBICS HostId of the Bank message.waitupdate is "true" if the send has to go via Electronic Signature ebics.action is the EBICS request action type (send or fetch) ebics.ordertype is the full EBICS order type ebics.user.userid is the EBICS userid of the transport user Inline processing for Interchange / Electronic Signature integration This section provides information about inline processing for Interchange/Electronic Signature integration. About inline processing Payment files are sent to the Electronic Signature application, through Interchange, using the PeSIT protocol for example. Inline processing ensures that Electronic Signature parses the most recent version of the payload. It also enables Electronic Signature to obtain the path of the payload in case of integration different from MMD (Message Metadata Document). Axway Electronic Signature Administrator Guide 33

34 3 Use Electronic Signature with Interchange Inline processing performs the following functions: Reads and interprets the metadata from the transfer (PI 99 in the case of PeSIT) and adds it to the message in Interchange before being picked up by Electronic Signature in the delivery exchange Copies the payload to an Interchange temporary directory so that it is available for Electronic Signature ready for a user to sign the payment The general workflow for payment files is explained in Electronic Signature processing on page 12. In this figure, inline processing takes place inside Interchange between steps 1 and 2. How to format PeSIT metadata for Electronic Signature The PeSIT PI 99 metadata must be formatted as follows: key = value Each part of the data is separated by the semi-colon character (;) Example: ebics.action=send; ebics.ordertype=ful.pain.xxx.cfonb160.dco; message.waitupdate=true; ebics.domain=geopost; ebics.sender=fi-ap; PayloadId=IDYZ1234;message.comment=Business Data where: message.comment is optional metadata that might help treasurers when signing a payment. Axway Electronic Signature Administrator Guide 34

35 3 Use Electronic Signature with Interchange Copy the JAR file The inline processing jar file is <Electronic Signature install dir>/program/devkit/inline/esign-app-inline.jar. Copy the jar file into the Interchange jars folder: <Interchange install dir>/jars. Configure Interchange for inline processing Configure PeSIT inline Proceed as follows to configure a community in Interchange to use inline processing with Electronic Signature for PeSIT. 1. Click Message handler on the navigation graphic at the top of the community summary page. 2. Click the task Add a new message processing action. 3. Choose an attribute for the condition and click Next. 4. Specify an operator and value that is always true. This ensures that the inline processing is always performed. Example: "From exists". 5. Select Perform inline processing via a Java class. 6. Complete the fields: Parameter Description Class name Enter the following name: com.axway.esign.app.inline.pesitintegration Parameter Enter the name of the temporary directory where the payload file is to be copied. Example: c:\my_temporary_folder\ The inline process creates a file name with syntax "file_coreid" for each payload. This ensures that files are unique and cannot be overwritten. 7. Click Finish. Now, continue with the configuration of Interchange (see Configure Interchange on page 30). Axway Electronic Signature Administrator Guide 35

36 3 Use Electronic Signature with Interchange Configure Payment Status Report inline Proceed as follows to configure a community in Interchange to use inline processing with Electronic Signature to update the payment status. 1. Click Message handler on the navigation graphic at the top of the community summary page. 2. Click the task Add a new message attribute definition with criteria. 3. Click Add attribute. 4. Enter ebics.ordertype in the text field and click Add. 5. Click Cancel to go back to the Message handler processing page. The previous action added the required attribute to the list of available attributes. 6. Click the task Add a new message processing action. 7. Choose the attribute ebics.ordertype for the condition and click Next. 8. Leave the Operators as "Equals" and "Constant" and specify in the text field of the value, the payment status report order type. Example: "FDL.camt ara" and click Next. 9. Select Perform inline processing via a Java class 10. Complete the fields: Parameter Description Class name Enter the following name: com.axway.esign.app.inline.psrintegration Parameter Enter the name of the Electronic Signature PSR Incoming directory where the fetched payment status report file is to be copied Example: c:\axway\electronicsignature\psr\incoming 11. Click Finish. Modify the default inline implementations The default inline implementations can be modified. The samples located in <Electronic Signature install dir>/program/devkit/inline are delivered for custom development: 1. Ensure that you have Maven installed and the command line mvn is on the system path environment variable. 2. Enter: mvn clean install. The build creates a target directory where the compiled class and a new esign-appinline-sample-{version}.jar file are generated. Axway Electronic Signature Administrator Guide 36

37 3 Use Electronic Signature with Interchange 3. Copy the newly-generated jar file into the Interchange jars folder: <Interchange install dir>/jars. Update payment status with PSR This section explains how to configure Interchange in Financial Integration to retrieve Payment Status Report (PSR) data for EBICS payments and then use the PSR to update the payment status displayed in Electronic Signature. About PSR The Payment Status Report (PSR) is a file generated by the EBICS Server after every EBICS transaction (payment file sent). The PSR file contains the final status of a transaction at the bank side. Three types of Payment Status Reports are supported along with their corresponding parsers: Payment Transfer Status Parser (PSRv2) Payment Transfer Status Parser (HAC/PSRv3) Payment Transfer Status Parser (PTK) By default, Electronic Signature is configured to support Payment Status Report PSRv2 with the file format FDL.camt ara. Therefore, to use the other payment status report types along with their parsers, you need to configure them. About PSR integration in Electronic Signature PSR integration in Electronic Signature enables business users to view the up-to-date status of the payments they have sent as found in the PSR. To achieve this, the following actions are performed: Interchange fetches PSR files from the EBICS Server at regular intervals The fetched files are placed in a monitoring directory configured in Electronic Signature Electronic Signature parses the retrieved files. A parser must be configured according to the PSR file format used (In the Admin tab file format section). Electronic Signature updates the payment status displayed in the UI, based on the unique EBICS order id generated in the transaction Detailed description of PSR parsing and status update: After a PSR is fetched, it is stored in the delivery pickup configured in Interchange Electronic Signature monitors this directory Electronic Signature parses the file retrieved and extracts the PSR(s). A file may contain several PSRs. Axway Electronic Signature Administrator Guide 37

38 3 Use Electronic Signature with Interchange Corresponding PSR entries are created in the database (HostID, CustomerID, OrderType, OrderId, Date, Result) Electronic Signature selects orderid in Interchange based on the coreid and the send status Electronic Signature selects the corresponding entry in the PSR which has been stored in the database The payment status is updated based on what is stored in the PSR Updated payment status If the server has accepted the payment then the payment status will be updated to ACCEPTED. If the server has rejected the payment, due to a wrong signature or compression error or any asynchronous error, then the payment status will be updated to REFUSED. You can see the reason the payment was rejected in the audit part. Note that if the text is longer than 255 characters it will be truncated to fit 255 characters. To view the full text, refer to the payment status report file received. If an error occurred during the transaction from Interchange to EBICS Server the payment status will be updated to IN ERROR. To view the full text, refer to the payment status report file generated in the <Electronic Signature install dir>/data/psr/<done_ DIRECTORY> directory. Configure PSR integration with Interchange Fetch a PSR file 1. Configure Interchange for EBICS transfers. 2. Create an XML file based on the following example: <?xml version="1.0" encoding="utf-8"?> <MessageMetadataDocument documentid="test_b2" protocol="generic"> <Metadata name="from" type="string">customer</metadata> <Metadata name="to" type="string">bank</metadata> <Metadata name="ebics.action" type="string">fetch</metadata> <Metadata name="ebics.ordertype" type="string">fdl.camt ara</metadata> <Metadata name="ebics.user.userid" type="string">user</metadata> </MessageMetadataDocument> 3. Change the BANK/CUSTOMER/USER as required. Axway Electronic Signature Administrator Guide 38

39 3 Use Electronic Signature with Interchange The value of the metadata ebics.user.userid corresponds to the transport user used for fetching the PSR. If the Bank has defined the PSR handler as user-based then the transport user used for sending payments must be specified. If no transport user has been explicitly defined, then the first signer is used as a transport user and this user must be specified in the fetch XML file. Configure Interchange integration delivery The PSR files need to be placed in a folder reserved for PSR files only. There are two ways to do this: One file system integration delivery or Two file systems integration delivery. One file system integration delivery Edit the file system integration delivery. In the Message attributes tab create a new attribute ebics.ordertype and add this new attribute to the selected list. By doing this every EBICS file will be placed in a folder identified by the ebics.ordertype under the directory name specified in the file system settings. If the incoming message does not have the ebics.ordertype metadata then it will be placed in the file system directory. Example File system directory: <Interchange install dir>/data/in/ebics (all the files that do not have the ebics.ordertype metadata are placed here) PSR files go in: <Interchange install dir>/data/in/ebics/fdl.camt ara HPB files go in: <Interchange install dir>/data/in/ebics/hpb Two file systems integration delivery The first integration delivery needs to be the default one with no delivery criteria. For the second one, select a file system directory different from the first integration delivery and add a delivery comparison criteria: ebics.ordertype equals FDL.camt ara PSR fetch scheduling PSR files need to be fetched regularly in order to update the payment status in Electronic Signature. Create a script that will copy the XML file with the fetch PSR command in the configured pickup directory of Interchange. For Windows you can use the scheduler task. For example you can add a new task to execute the previously-created script every 60 seconds. Axway Electronic Signature Administrator Guide 39

40 3 Use Electronic Signature with Interchange PSR inline Create a new inline process that will copy the fetched PSR in the monitoring directory of Electronic Signature and rename the file BANK#CUSTOMER#ORDERTYPE#ID.xml. The bank, customer and ordertype are metadata found in the Message and the id is a counter or an identifier to ensure unique file names. The ordertype indicates to Electronic Signature which parser to use for the incoming PSR. This must be configured in the File format tab in Administration. Axway Electronic Signature Administrator Guide 40

41 3 Use Electronic Signature with Interchange Integrate Sentinel with Electronic Signature and Interchange This section explains how to configure Electronic Signature to send events to Sentinel. Introduction By default, Interchange sends events to Sentinel. These events represent the EBICS T (Transport only) flow. However, these events give no indication as to whether a payment has been signed or not. To overcome this you can configure Electronic Signature to send events to Sentinel in addition to the events sent from Interchange. These events represent the EBICS TS (Transport and Signature) flow. Electronic Signature sends events for: ES_PENDING The payment has been sent to Electronic Signature awaiting signature. ES_SIGNED The payment has been signed in Electronic Signature and sent back to Interchange integration. ES_REJECTION The payment has been rejected in Electronic Signature. Electronic Signature, by default, uses XFBTransfer as tracking object. The tracking object with the object version can be configured in the configuration.properties file. The Sentinel tracked object is XFBTransfer. Each time a message has a change in transfer state, Interchange or Electronic Signature generates and sends an XFBTransfer notification message to Sentinel. The following figure shows the flow of notification messages between Electronic Signature, Interchange and Sentinel. Axway Electronic Signature Administrator Guide 41

42 3 Use Electronic Signature with Interchange Configure Electronic Signature for end-to-end Sentinel integration You need to select the Sentinel monitoring option when you install Electronic Signature. Sentinel attribute names The following table shows Sentinel attribute names used by Electronic Signature and the messages sent to the Sentinel Server for different events. In this table, ES represents Electronic Signature. Attribute name CREATIONDATE CREATIONTIME CYCLEID DIRECTION Description Event creation date (dd/mm/yyyy) Event creation time (hh:mm:ss) CycleID of EBICS transfer: I for Initial CycleID sent by Interchange ES for Electronic Signature CycleID (core ID of payload) EB for EBICS CycleID Direction of transfer: E for Emission R for Reception ü ü ü ü I ES ES ES EB E E E E E ENDDATE Transfer end date ü ü (dd/mm/yyyy) ENDTIME Transfer end time ü ü (hh:mm:ss) Axway Electronic Signature Administrator Guide 42

43 3 Use Electronic Signature with Interchange Attribute name EVENTDATE Description Event date (dd/mm/yyyy) ü ü ü ü ü FILENAME File name of payload ü ü ü ü ü ISALERT ISEND LOCATION MACHINE Indicates if transaction is in an alert state. 0 = not alert 1 = alert, not resolved 2 = alert, resolved Indicates whether the transaction is completed. 0 = transaction not completed 1 = transaction completed 2 = transaction rejected or in error Machine from which events come (host name) Machine hosting the event sender (host name) or or 2 ü ü ü ü ü ü ü ü ü ü MONITOR Event sender INTR ES ES ES INTR MONITORVERSION PRODUCTNAME PRODUCTOS Event sender version and build Name of event sender: I = "Interchange" ES = "Electronic Signature" Name of the OS running on the machine ü ü ü ü ü I ES ES ES I ü ü ü ü ü Axway Electronic Signature Administrator Guide 43

44 3 Use Electronic Signature with Interchange Attribute name PROTOCOL RECEIVERID RETURNCODE Description Protocol: E = EBICS O = Original other protocol Routing ID of receiver (Host ID) Message type: -1 = rejected 0 = unknown 1 = request 2 = receipt 3 = request and receipt O E E E E ü ü ü ü ü 1 or or -1 RETURNMESSAGE Rejection reason ü ü ü SENDDATE SENDERID Event date (dd/mm/yyyy) Routing ID of sender (CustomerID) ü ü ü ü ü ü ü ü ü ü SENDTIME Event time (hh:mm:ss) ü ü ü ü ü SIGNENTITYOBJECTID EBICS User ID of sender or rejector separated by semi-colon ü ü ü Axway Electronic Signature Administrator Guide 44

45 3 Use Electronic Signature with Interchange Attribute name Description STATE Event state: INT ESP ESS ESR or INT INT = Interchange ESE event ESP = ES_PENDING ESS = ES_SIGNED ESR = ES_ REJECTION ESE = ES_ERROR TRADEDESTINATION TRADEDESTINATIONALIAS TRADEORIGINATOR TRADEORIGINATORALIAS Host ID for outbound message Customer ID for inbound message Host ID for outbound message Customer ID for inbound message Customer ID for outbound message Host ID for inbound message Customer ID for outbound message Host ID for inbound message ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü ü TRADEREQUESTTYPE EBICS file format ü ü ü ü ü TRADESERVICE EBICS Order type ü ü ü ü ü USERID EBICS User ID of last sender or rejector ü ü ü ü Axway Electronic Signature Administrator Guide 45

46 Use Electronic Signature with Gateway 4 This chapter applies only if you are using Gateway as the communication layer for Electronic Signature. After installing Electronic Signature with Gateway as communication layer, you have to configure Gateway in order to make the link with the back-end application. Prerequisites on page 46 Use Transfer CFT to connect to the back-end application on page 47 Behavior principles: User message on page 47 Configure Gateway to connect to Transfer CFT on page 48 Configure Gateway for Send and Fetch on page 48 Update payment status with PSR on page 52 Integrate Sentinel with Electronic Signature and Gateway on page 55 EBICS Client administration on page 61 Send and Fetch transactions with embedded EBICS Client on page 70 Use embedded EBICS Client with a DMZ proxy on page 74 Prerequisites Gateway must be installed (refer to the Gateway Installation Guide). Gateway must be installed on the same machine as Electronic Signature. Sentinel Universal Agent must be installed on the same machine as Electronic Signature. Axway Electronic Signature Administrator Guide 46

47 4 Use Electronic Signature with Gateway Use Transfer CFT to connect to the back-end application The installation package includes a set of sample files that enable you to link Gateway and Electronic Signature to Transfer CFT to connect to the back-end application. The sample files that are provided in the installation package enable you to: Automate a Send request (for example, to EBICS Server) Automate a scheduled Fetch and send result to a Transfer CFT monitor 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 message The 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>#<paylo adid>#<domain>#<sender>#<amount>#<nb_operations>#<comment> where: <ordertypebl> is the full EBICS order type (for example FUL.pain 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 (optional). <PayloadId> is the id of the payload, this parameter is mandatory. <Domain> is the domain of the payload. The domain is the organizational entity within a company. <sender> is the sender of the payload. The sender is the application that initiates a payment flow. <amount> is the global amount of the payment that is displayed in the Electronic Signature UI (optional). If a value is specified here it will override the amount parsed from the payload. Axway Electronic Signature Administrator Guide 47

48 4 Use Electronic Signature with Gateway <Nb_of_operation> is the number of operation of the given payment file. This value is displayed in the Electronic Signature UI (optional). If a value is specified here it will override the number of operations parsed from the payload. <comment> is any business information that might help the treasurers to sign a payment. This optional value is displayed in the Electronic Signature payments comment column. Note that special characters (!,?, etc.) cannot be used. <CustomerId> and <AdditionalUserId1> are mandatory unless a default Customer and User are defined inside the Bank. Fetch User message syntax <ordertypebl>#<ebicsbankhostid>#<customerid>#<useridtransport>#<fromdat e>#<todate> where: <CustomerId> and <useridtransport> are mandatory unless a default Customer for the Bank and a default User for the Customer are defined. <FromDate> and <ToDate> are optional. They are defined in the format YYMMDD. Configure Gateway to connect to Transfer CFT See the following sections: Send and Fetch: Configure Gateway for Send and Fetch on page 48 Fetch PSR: Update payment status with PSR on page 52 Configure Gateway for Send and Fetch This section explains how you configure Gateway to detect a Send or Fetch request and trigger the related action. Sample scripts are supplied that use Gateway and Transfer CFT. Configure Gateway To execute a Send or Fetch from a Transfer CFT client you require the following Gateway objects: Remote Site Application Local Site Axway Electronic Signature Administrator Guide 48

49 4 Use Electronic Signature with Gateway Model (only required for Fetch requests) Decision Rule You can either configure Gateway using sample scripts or configure Gateway manually. This section explains both methods. Configure Gateway using sample scripts The sample script obj_gateway_client_ebics[.bat.sh] creates all the required objects with the link to the required scripts. However you first need to customize the script. 1. Navigate to the Electronic Signature installation directory. 2. In the directory <Electronic Signature install dir>/program/mft/install/client, locate the file obj_gateway_client_ ebics.bat (or.sh for UNIX). 3. Open the file in a text editor, and modify the following parameters: Parameter GTW_HOME remote_cft_ebics_client_ address Modification Set the path to the Gateway installation directory. 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: Windows: obj_gateway_client_ebics.bat UNIX: obj_gateway_client_ebics.sh 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]. Axway Electronic Signature Administrator Guide 49

50 4 Use Electronic Signature with Gateway Configure Gateway manually Create 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: Windows: EbicsFetchClient_GTW.bat UNIX: EbicsFetchClient_GTW.sh These scripts are located in the directory <Electronic Signature install dir>/program/mft/fetch For EBICS T: When you enter the script in the Gateway field, add the name of the Model to use and add one of the following parameters: test real The test or real value sets the communication mode with EBICS Server. Example on Windows: EbicsFetchClient_GTW.bat ModelName test Axway Electronic Signature Administrator Guide 50

51 4 Use Electronic Signature with Gateway For EBICS TS: See Update payment status with PSR on page 52. Decision Rule for Send In Gateway Navigator, create a Decision Rule that points to one of the scripts: Windows: EbicsSendClient_GTW.bat UNIX: EbicsSendClient_GTW.sh These scripts are located in the directory <Electronic Signature install dir>/program/mft/send For EBICS T: When you enter the script in the Gateway field, add one of the following parameters: test real The test or real value sets the communication mode with EBICS Server. Example on Windows: EbicsSendClient_GTW.bat test For EBICS TS: When you enter the script in the Gateway field, add the following parameters: real waitupdate The waitupdate indicates that the Send must wait for a signature. Example on Windows: EbicsSendClient_GTW.bat real waitupdate For more details about creating Gateway objects, refer to the Gateway documentation. Configure Transfer CFT The sample script cft_ebics_client.cfg creates the required objects on the Transfer CFT side. 1. Navigate to the Electronic Signature installation directory. 2. In the directory <Electronic Signature install dir>/program/mft/install/client locate the file cft_ebics_client.cfg. 3. Open the file in a text editor, and modify the following parameters: Axway Electronic Signature Administrator Guide 51

52 4 Use Electronic Signature with Gateway Parameter SYST Modification Enter the type of platform. Example values: 'WINNT' 'UNIX' PROT Enter 'PESITANY' SAP Enter '6330' HOST Enter the Gateway HostName 4. Save the file. 5. From the same directory, execute the script: Windows: CFTUTIL #cft_ebics_client.cfg UNIX: Update payment status with PSR This section explains how to configure Gateway in Financial Integration to retrieve Payment Status Report (PSR) data for EBICS payments and then use the PSR to update the payment status displayed in Electronic Signature. About PSR The Payment Status Report (PSR) is a file generated by the EBICS Server after every EBICS transaction (payment file sent). The PSR file contains the final status of a transaction at the bank side. Three types of Payment Status Reports are supported along with their corresponding parsers: Payment Transfer Status Parser (PSRv2) Payment Transfer Status Parser (HAC/PSRv3) Payment Transfer Status Parser (PTK) By default, Electronic Signature is configured to support Payment Status Report PSRv2 with the file format FDL.camt ara. Therefore, to use the other payment status report types along with their parsers, you need to configure them. PSR type availability Fetch with PTK is only available for order types with three characters. Axway Electronic Signature Administrator Guide 52

53 4 Use Electronic Signature with Gateway Fetch with PSR v2 is only available for order type + file format, for example: FUL.xxxx.yyyy. Fetch with PSR v3 supports both order type and order type + file format. About PSR integration in Electronic Signature PSR integration in Electronic Signature enables business users to view the up-to-date status of the payments they have sent as found in the PSR. To achieve this, the following actions are performed: Gateway fetches PSR files from the EBICS Server at regular intervals using a Decision Rule. The fetched files are placed in a monitoring directory configured in Electronic Signature. Electronic Signature parses the retrieved files. A parser must be configured according to the PSR file format used (In the Admin tab file format section). Electronic Signature updates the payment status displayed in the UI, based on the unique EBICS order id generated in the transaction. Detailed description of PSR parsing and status update: After a PSR is fetched, it is stored in the directory configured in Gateway Electronic Signature monitors this directory Electronic Signature parses the file retrieved and extracts the PSR(s). A file may contain several PSRs. Corresponding PSR entries are created in the database (HostID, CustomerID, OrderType, OrderId, Date, Result) Electronic Signature selects the corresponding entry in the PSR which has been stored in the database The payment status is updated based on what is stored in the PSR Updated payment status If the server has accepted the payment then the payment status will be updated to ACCEPTED. If the server has rejected the payment, due to a wrong signature or compression error or any asynchronous error, then the payment status will be updated to REFUSED. You can see the reason the payment was rejected in the audit part. Note that if the text is longer than 255 characters it will be truncated to fit 255 characters. To view the full text, refer to the payment status report file received. If an error occurred during the transaction from Gateway to EBICS Server the payment status will be updated to IN ERROR. To view the full text, refer to the payment status report file generated in the <Electronic Signature install dir>/data/psr/<done_ DIRECTORY> directory. Axway Electronic Signature Administrator Guide 53

54 4 Use Electronic Signature with Gateway Configure PSR integration with Gateway Fetch a PSR file In Gateway Navigator, create a Decision Rule that points to the script: Windows: EbicsPsrFetchClientWithParam_GTW.bat real <ordertype> <BANK> <CUSTOMER> <USER> <path_to_psr_dir> UNIX: EbicsPsrFetchClientWithParam_GTW.sh real <ordertype> <BANK> <CUSTOMER> <USER> <path_to_the_monitoring_dir> These scripts are located in the directory <Electronic Signature install dir>/program/mft/fetch where: <OrderType> is the full EBICS OrderType of the PSR (example: FDL.camt ara) <BANK> is the name of the EBICS Bank <CUSTOMER> is the name of the EBICS customer <USER> is the name of the EBICS user <path_to_psr_dir> is the path to the monitoring directory of Electronic Signature. This must be the same value as the psr.monitoring.directory property defined in the Electronic Signature configuration file: <Electronic Signature install dir>/data/conf/configuration.properties. You need to create one Decision Rule for each Bank/Customer you have defined. The <USER> corresponds to a transport user. It can be omitted in the fetch XML file, in which case the default user for the BANK/CUSTOMER will be used. If the Bank has defined the PSR handler as user-based then the transport user used for sending payments must be specified. If no transport user has been explicitly defined, then the first signer is used as a transport user and this user must be specified in the fetch XML file. PSR fetch scheduling PSR files need to be fetched regularly in order to update the payment status in Electronic Signature. For example, you might want to fetch a PSR every 60 seconds. To do this, schedule the previouslycreated Decision Rules in a schedule-type Rule Table in the Event Management/Scheduling menu of the Gateway GUI. Limitation for Bank and Customer names When using Electronic Signature with Gateway, do not use the hash character '#' in Bank or Customer names. The PSR parser interprets the hash as a separator. Axway Electronic Signature Administrator Guide 54

55 4 Use Electronic Signature with Gateway Integrate Sentinel with Electronic Signature and Gateway This section explains how to configure Electronic Signature to send events to Sentinel. Introduction Automated EBICS Transfers are monitored by: Log messages inside Gateway 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. With Electronic Signature, you can also monitor the complete EBICS TS (Transport and Signature) flow. Electronic Signature sends event for: ES_PENDING The payment has been sent to Electronic Signature awaiting signature. ES_SIGNED The payment has been signed in Electronic Signature and sent back to Gateway integration. ES_REJECTION The payment has been rejected in Electronic Signature. Electronic Signature, by default, uses XFBTransfer as tracking object. The tracking object with the object version can be configured in the configuration.properties file. Each time a message has a change in transfer state, either Gateway or Electronic Signature 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 are linked to Sentinel with a Cycle link. The following figure shows the flow of notification messages between Electronic Signature, Gateway and Sentinel. Axway Electronic Signature Administrator Guide 55