Electronic Signature Administrator Guide

Electronic SignatureVersion 2.10.03 February 2021

Administrator Guide

Copyright © 2021 Axway

All rights reserved.

This documentation describes the following Axway software:

Axway Electronic Signature 2.10.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 8Who should read this guide 8Electronic Signature documentation set 8Related documentation 8Support services 9Training services 9

Accessibility 10Screen reader support 10Support for high contrast and accessible use of colors 10

1 Overview 11Installation configurations 11EBICS Client functionality 12Electronic Signature functionality 12Electronic Signature processing 12Financial Integration products 13

2 Configure Electronic Signature 14Configuration tool 14Configure security tokens 14Configure log levels 14Configure TLS 15Electronic Signature directory structure 15Use the Electronic Signature Configuration tool 15General settings 15Security settings 16Database settings 17Access manager settings 18Transporter configuration settings 19Optional settings for Sentinel and Secure Relay 19Final configuration step 21

Secure Electronic Signature 21Configure Electronic Signature security tokens 21Protect Electronic Signature against path manipulation 22Change default certificates 23Configure inbound Electronic Signature TLS connection 24Modify outbound Electronic Signature TLS configuration 25Secure database connection with TLS 26

AxwayElectronic Signature 2.10.0 Administrator Guide 3

Modify TLS connection with PassPort 28Configure the TLS connection between Electronic Signature and Sentinel 28

3 Use Electronic Signature with Interchange 30Prerequisites 30Configure Interchange 30Send EBICS requests using MMD files 31MMD XML file examples 31

Inline processing for Interchange / Electronic Signature integration 33About inline processing 33How to format PeSIT metadata for Electronic Signature 34Copy the JAR file 35Configure Interchange for inline processing 35Configure Payment Status Report inline 36Modify the default inline implementations 36

Update payment status with PSR 37About PSR 37About PSR integration in Electronic Signature 37Configure PSR integration with Interchange 38

Integrate Sentinel with Electronic Signature and Interchange 41Introduction 41Configure Electronic Signature for end-to-end Sentinel integration 42Sentinel attribute names 42

4 Use Electronic Signature with Gateway 46Prerequisites 46Use Transfer CFT to connect to the back-end application 47Behavior principles: User message 47Send – User message syntax 47Fetch – User message syntax 48

Configure Gateway to connect to Transfer CFT 48Configure Gateway for Send and Fetch 48Configure Gateway 48Configure Transfer CFT 51

Update payment status with PSR 52About PSR 52About PSR integration in Electronic Signature 53Configure PSR integration with Gateway 54Limitation for Bank and Customer names 55

Integrate Sentinel with Electronic Signature and Gateway 56Introduction 56Configure Electronic Signature for end-to-end Sentinel integration 57Sentinel attribute names 57

Integrate Electronic Signature with Gateway and Sentinel 61


Configuration file contents 61EBICS Client administration 62About command lines 63Syntax 63Commands per use case 64Parameter list 68Import the TLS Bank certificate to the client keystore 70General procedure to create an EBICS user 70Deactivate a proxy server for a bank 71

Send and Fetch transactions with embedded EBICS Client 71General behavior 71Request definition 71Explanation of tags 72End of transfer callback variables 74

Use embedded EBICS Client with a DMZ proxy 75About Secure Relay 75Configure embedded EBICS Client for Secure Relay 75Configure embedded EBICS Client with an HTTP proxy 76

5 Control Electronic Signature 77Command scripts 77Start Electronic Signature 78Connect to the Electronic Signature UI 78Stop Electronic Signature 79Check the Electronic Signature status 79Start and stop Electronic Signature in Windows service mode 79Start Electronic Signature 79Stop Electronic Signature 80

6 Manage Electronic Signature Agent 81Preparation 81Download Electronic Signature Agent 81Install Electronic Signature Agent 82Graphical mode 82Silent mode 82Console mode 83

Change the port value 83Change the port value in Electronic Signature Agent 83Change the port value in Electronic Signature 84

Display the port used by the Agent at startup 84How to import certificates 84Import a certificate via the REST API 84

Start Electronic Signature Agent 85Stop Electronic Signature Agent 85


Access the log files 85Troubleshooting 86

7 Extend support to other formats 87Payload parser 87Modify the parser exit 87

8 Develop exits for Electronic Signature 89Overview of the exit framework 89Description of the exit framework API 89Development 91Prerequisites 91Develop exits 92Sample exit 95

9 Use PassPort with Electronic Signature 98Post-installation 98Start Electronic Signature for the first time 98Create Administrator and Signer users in PassPort 99Update PassPort properties 99Import Signer users from PassPort 99Define users who will receive email notifications 100PassPort self-registration 100

Renew PassPort certificates 101Default certificates provided by PassPort 101Non-PassPort certificates 101

10 Purge payments in Electronic Signature 102Command syntax 102Parameter usage 103Database records 104

11 Single sign-on using SAML 105Service Provider 105Identity Provider 105User Agent 105Security Assertion Markup Language (SAML) 105An assertion 106Electronic Signature implementation behavior 106SAML 2.0 compliance 106Login sequence 106User authentication use cases 107

Logout sequence 107Logout initiated by Electronic Signature 107


Logout initiated by the Identity Provider 108SAML SSO configuration 108Prerequisites 108Configure SAML SSO 108Configure sso-service-provider.xml for Electronic Signature 111Service Provider metadata 112

SAML SSO post-configuration tasks 112New Electronic Signature installation 112Migration from existing Electronic Signature installation 112

SAML SSO troubleshooting 113Cannot access my application even after a successful login 113After I login to the Identity Provider page I am not redirected to the application page 113

Appendix A: configuration.properties file 114Electronic Signature 115Electronic Signature configuration section 115Database configuration section 118UI configuration section 118Parser configuration section 119Payment details section 119Email configuration section 119Transporter configuration section 121Interchange configuration section 121PSR scanning configuration section 122Common SSO configuration section 123PassPort configuration section 123Sentinel configuration section 125Sizing configuration section 126Exit configuration section 126Cipher Key Configuration 127Configuration for accepted file system paths 128

EBICS Client 129Configuration of the signature protocols section 129Configuration of order type counter section 129Configuration of scanning file system section 129Network configuration section 131

Appendix B: Directory structure 133

Appendix C: secureRelayConf reference 135Master Agent 135Router Agent 136


Preface

This guide describes how to configure and administer Electronic Signature. The guide includes details of the different configuration files.

Who should read this guideThis 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 setThe Electronic Signature 2.10.0 documentation set includes the following documents:

l Axway Electronic Signature 2.10.0 Release Notes

l Axway Electronic Signature 2.10.0 Administrator Guide

l Axway Electronic Signature 2.10.0 Installation Guide

l Axway Electronic Signature 2.10.0 Upgrade Guide

l Axway Electronic Signature 2.10.0 User Guide

l Axway Electronic Signature 2.10.0 Security Guide

To 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.


https://docs.axway.com/bundle

https://docs.axway.com/

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

Preface

l Axway Interoperability Matrix

Provides product version and interoperability information for Axway products.

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.

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


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

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.

This documentation provides the following accessibility features:

l Screen reader support

l Support for high contrast and accessible use of colors

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.


1 Overview

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 configurationsVarious 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.


1 Overview

EBICS Client functionalityEBICS 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 functionalityElectronic 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 processingThe following figure shows the general workflow for payment files being processed by Electronic Signature.


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 productsElectronic Signature is used as part of the Financial Integration solution with the following Axway products:

l Interchange (or Gateway)

l 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.


2 Configure Electronic Signature

This chapter explains how to configure Electronic Signature.

Configuration toolAfter 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 fileThe 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 114.

Configure security tokensFor details about security tokens, see Configure Electronic Signature security tokens on page 21.

Configure log levelsTo 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.



Configure TLSImportant: 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 structureFor information about the location of directories and files in Electronic Signature, see Directory structure on page 133.

Use the Electronic Signature Configuration toolYou can run the Configuration tool in:

l Graphical mode

l 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:

l configure.sh -c

l 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.



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 emails

Override Domain Name and Port

When you select this option, the address of the server differs from the address Electronic Signature uses to send emails

Domain Name New domain name of the server

New HTTP Port New TCP port used by Electronic Signature to send emails

Security settingsSpecify 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



Field Description

Truststore Password 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

Oracle database URL connection

TLS connection When you select this option, the application secures the connection to the database through TLS

Oracle settingsIf you selected Oracle, this is an overview of the database options.

Field Description

l SID Oracle database instance name

l Service Name Oracle TNS Alias

l Hostname Database hostname

l Port Number Database port number

l Connection User Database connection user

l Connection Password Database connection password



Field Description

If you selected the Use custom URL option:

l Custom URL Database custom URL



MySQL settingsIf you selected MySQL, this is an overview of the database options.

Field Description

l Database Name Database schema name

l Hostname Database hostname

l Port Number Database port number



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



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 settingsSelect 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

Enter hostname, port, user and password information corresponding to your configuration of Interchange.

Interchange Port

Interchange Username

Interchange Password

Optional settings for Sentinel and Secure RelayYou can specify settings for Sentinel or Secure Relay.

Sentinel settingsIf 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



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 settingsIf 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

Enter a path for the Secure Relay Master Agent certificate

Certificate Password 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 75.



Final configuration stepClick Configure to exit Setup.

The Configuration tool configures Electronic Signature with your settings.

Secure Electronic SignatureAt 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 tokensTo 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 Client to use

SafeNet SafeNet Authentication Client 8.0 SP2

Certinomis Gemalto RegTool

Keynectis Gemalto RegTool

Ces@mOr SafeNet Authentication Client 8.0 SP2

Keynectis K.Sign Sagem Launcher



Token Type Client to use

SWIFT 3Skey 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 APIBefore 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:

http://localhost:8085/esignagent/api/v1/certificate

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:

l A PKCS#12 certificate encoded in base64

l 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 pathsPath 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:



Parameter Description Example

payload.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 2.10.0, 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 2.9.2 or if you are using Gateway as transporter.

data/mft/files

mft.directory 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.

program/mft

trace.directory 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/tmp

Change default certificatesElectronic 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:



Password Description

ksPassword 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 connectionConnection 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:

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 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 114.

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.



By default, the following cipher suites are supported:

l TLS_RSA_WITH_AES_256_CBC_SHA256


l TLS_RSA_WITH_AES_256_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 configurationBy 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:

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 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 114.

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:







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 TLSYou can configure Electronic Signature to support a secured channel (TLS connection) between Electronic Signature and a MySQL or Oracle database.

Prerequisites l You are using a MySQL or Oracle database. Refer to "Software prerequisites" in the Electronic Signature Installation Guide for compatible versions.

l 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 SignaturePrerequisite: You selected the TLS option for the database using the Configuration tool.

Import TLS server certificateThe 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



Database connection error messagesThe 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.



Modify TLS connection with PassPortBy 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:

l Oracle JRE 1.7 or higher

l 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 SentinelBy default, Electronic Signature supports TLSv1.2. Electronic Signature also supports the following protocols, however it is not recommended to use these weaker protocols:

l TLSv1

l 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.



l sentinel.tls.connection.enabled: Flag that indicates whether the TLS connection with Sentinel is enabled.

l 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.

l server.truststore.file: The path to the truststore of the Sentinel certificate.

l 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


3 Use Electronic Signature with Interchange

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 l Interchange must be installed (refer to the Interchange Installation Guide).

l Interchange must be installed with a license key intended for non FIPS compliance usage.

Configure InterchangeThis 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.



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:

l 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.

l EBICS Bank Settings: Choose the protocol version of the bank (France is H003).

l Choose Signature version. Electronic Signature handles only A005 signature version.

l Configure the HTTP settings: Enter the URL of the remote EBICS bank.

l Delivery exchange name: Enter a meaningful name for this delivery exchange.

l Save your delivery exchange.

12. Import TLS certificate of the remote EBICS server:

l Go to your community, click certificates, and TLS trusted root certificates.

l Add this TLS certificate.

For more information about configuring Interchange, refer to the Interchange documentation.

Send EBICS requests using MMD filesIn 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">



<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.001.001.02.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="IDFD2234555600">

<MimeContentId>[email protected]</MimeContentId>

<MimeContentType>text/plain</MimeContentType>

<Location type="filePath">C:\pain.001.001.03.xml</Location>

</Payload>

</MessagePayloads>

</MessageMetadataDocument>

where:

l From is the EBICS HostId of the Bank

l To is the EBICS customerID

l message.waitUpdate is "true" if the send has to go via Electronic Signature

l ebics.action is the EBICS request action type (send or fetch)

l ebics.orderType is the full EBICS order type

l ebics.domain is the domain of the payload. The domain is the organizational entity within a company.

l ebics.sender is the sender of the payload. The sender is the application that initiates a payment flow.

l 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.

l 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.

l ebics.user.userId is the EBICS userID of the transport user (optional)

l 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).



l Payload id is the id of the payload, this parameter is mandatory

l Location type is the location and type of payload

Fetch


<MessageMetadataDocument documentId="Test_B2" protocol="generic">



<Metadata name="ebics.action" type="string">fetch</Metadata>


type="string">FDL.camt.002.001.02.ara</Metadata>

<Metadata name="ebics.user.userId" type="string">USER</Metadata>


where:

l From is the EBICS customerID

l To is the EBICS HostId of the Bank

l message.waitUpdate is "true" if the send has to go via Electronic Signature

l ebics.action is the EBICS request action type (send or fetch)

l ebics.orderType is the full EBICS order type

l 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 processingPayment 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).



Inline processing performs the following functions:

l 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

l 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 SignatureThe 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:

l message.comment is optional metadata that might help treasurers when signing a payment.



Copy the JAR fileThe 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 inlineProceed 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).



Configure Payment Status Report inlineProceed 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.002.001.02.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 copiedExample: c:\Axway\ElectronicSignature\psr\incoming

11. Click Finish.

Modify the default inline implementationsThe 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-app-inline-sample-{version}.jar file are generated.



3. Copy the newly-generated jar file into the Interchange jars folder: <Interchange install dir>/jars.

Update payment status with PSRThis 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 PSRThe 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:

l Payment Transfer Status Parser (PSRv2)

l Payment Transfer Status Parser (HAC/PSRv3)

l Payment Transfer Status Parser (PTK)

By default, Electronic Signature is configured to support Payment Status Report PSRv2 with the file format FDL.camt.002.001.02.ara. Therefore, to use the other payment status report types along with their parsers, you need to configure them.

About PSR integration in Electronic SignaturePSR 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:

l Interchange fetches PSR files from the EBICS Server at regular intervals

l The fetched files are placed in a monitoring directory configured in Electronic Signature

l 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).

l 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:

l After a PSR is fetched, it is stored in the delivery pickup configured in Interchange

l Electronic Signature monitors this directory

l Electronic Signature parses the file retrieved and extracts the PSR(s). A file may contain several PSRs.



l Corresponding PSR entries are created in the database (HostID, CustomerID, OrderType, OrderId, Date, Result)

l Electronic Signature selects orderId in Interchange based on the coreId and the send status

l Electronic Signature selects the corresponding entry in the PSR which has been stored in the database

l The payment status is updated based on what is stored in the PSR

Updated payment status l If the server has accepted the payment then the payment status will be updated to ACCEPTED.

l 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.

l 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:


<MessageMetadataDocument documentId="Test_B2"

protocol="generic">



<Metadata name="ebics.action" type="string">fetch</Metadata>


type="string">FDL.camt.002.001.02.ara</Metadata>

<Metadata name="ebics.user.userId"

type="string">USER</Metadata>


3. Change the BANK/CUSTOMER/USER as required.



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 deliveryThe 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 deliveryEdit 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.002.001.02.ara

HPB files go in: <Interchange install dir>/data/in/ebics/HPB

Two file systems integration deliveryThe 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.002.001.02.ara

PSR fetch schedulingPSR 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.



PSR inlineCreate 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.



Integrate Sentinel with Electronic Signature and Interchange

This section explains how to configure Electronic Signature to send events to Sentinel.

IntroductionBy 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:

l ES_PENDING – The payment has been sent to Electronic Signature awaiting signature.

l ES_SIGNED – The payment has been signed in Electronic Signature and sent back to Interchange integration.

l 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.



Configure Electronic Signature for end-to-end Sentinel integrationYou need to select the Sentinel monitoring option when you install Electronic Signature.

Sentinel attribute namesThe 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 Description

CREATIONDATE Event creation date (dd/mm/yyyy)

ü ü

CREATIONTIME Event creation time (hh:mm:ss)

ü ü

CYCLEID CycleID of EBICS transfer:

l I for Initial CycleID sent by Interchange

l ES for Electronic Signature CycleID (core ID of payload)

l EB for EBICS CycleID

I ES ES ES EB

DIRECTION Direction of transfer:

l E for Emission

l R for Reception

E E E E E

ENDDATE Transfer end date (dd/mm/yyyy)

ü ü

ENDTIME Transfer end time (hh:mm:ss)

ü ü




EVENTDATE Event date (dd/mm/yyyy)

ü ü ü ü ü

FILENAME File name of payload ü ü ü ü ü

ISALERT Indicates if transaction is in an alert state.

l 0 = not alert

l 1 = alert, not resolved

l 2 = alert, resolved

0 0 1 0 or 1

ISEND Indicates whether the transaction is completed.

l 0 = transaction not completed

l 1 = transaction completed

l 2 = transaction rejected or in error

0 0 2 1 or 2

LOCATION Machine from which events come (host name)

ü ü ü ü ü

MACHINE Machine hosting the event sender (host name)

ü ü ü ü ü

MONITOR Event sender INTR ES ES ES INTR

MONITORVERSION Event sender version and build

ü ü ü ü ü

PRODUCTNAME Name of event sender:I = "Interchange"ES = "Electronic Signature"

I ES ES ES I

PRODUCTOS Name of the OS running on the machine

ü ü ü ü ü




PROTOCOL Protocol:

l E = EBICS

l O = Original other protocol

O E E E E

RECEIVERID Routing ID of receiver (Host ID)

ü ü ü ü ü

RETURNCODE Message type:

l -1 = rejected

l 0 = unknown

l 1 = request

l 2 = receipt

l 3 = request and receipt

1 or -1 0 0 -1 1 or -1

RETURNMESSAGE Rejection reason ü ü ü

SENDDATE Event date (dd/mm/yyyy)

ü ü ü ü ü

SENDERID Routing ID of sender (CustomerID)

ü ü ü ü ü

SENDTIME Event time (hh:mm:ss) ü ü ü ü ü

SIGNENTITYOBJECTID EBICS User ID of sender or rejector separated by semi-colon

ü ü ü

STATE Event state:

l INT = Interchange event

l ESP = ES_PENDING

l ESS = ES_SIGNED

l ESR = ES_REJECTION

l ESE = ES_ERROR

INT ESP ESS ESR or ESE

INT




TRADEDESTINATION Host ID for outbound messageCustomer ID for inbound message

ü ü ü ü ü

TRADEDESTINATIONALIAS Host ID for outbound messageCustomer ID for inbound message

ü ü ü ü ü

TRADEORIGINATOR Customer ID for outbound messageHost ID for inbound message

ü ü ü ü ü

TRADEORIGINATORALIAS Customer ID for outbound messageHost ID for inbound message

ü ü ü ü ü

TRADEREQUESTTYPE EBICS file format ü ü ü ü ü

TRADESERVICE EBICS Order type ü ü ü ü ü

USERID EBICS User ID of last sender or rejector

ü ü ü ü


4 Use Electronic Signature with Gateway

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 56

EBICS Client administration on page 62

Send and Fetch transactions with embedded EBICS Client on page 71

Use embedded EBICS Client with a DMZ proxy on page 75

Prerequisites l Gateway must be installed (refer to the Gateway Installation Guide).

l Gateway must be installed on the same machine as Electronic Signature.

l Sentinel Universal Agent must be installed on the same machine as Electronic Signature.



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:

l Automate a Send request (for example, to EBICS 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>#<Paylo

adId>#<Domain>#<sender>#<amount>#<nb_operations>#<comment>

where:

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

l <bankId> is the EBICS HostId of the Bank.

l <CustomerId> is the EBICS customerID.

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

l <userIdTransport> is the EBICS userID of the transport user (optional).

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

l <Domain> is the domain of the payload. The domain is the organizational entity within a company.

l <sender> is the sender of the payload. The sender is the application that initiates a payment flow.

l <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.



l <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.

l <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.

l <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:

l <CustomerId> and <userIdTransport> are mandatory unless a default Customer for the Bank and a default User for the Customer are defined.

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

Configure Gateway to connect to Transfer CFT

See the following sections:

l Send and Fetch: Configure Gateway for Send and Fetch on page 48

l Fetch PSR: Update payment status with PSR on page 52

Configure Gateway for Send and FetchThis 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 GatewayTo 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

You can either configure Gateway using sample scripts or configure Gateway manually. This section explains both methods.

Configure Gateway using sample scriptsThe 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 Modification

GTW_HOME Set 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 Windows: obj_gateway_client_ebics.bat

l 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].



Configure Gateway manuallyCreate the following Gateway objects:

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

In Gateway Navigator, create a new Remote Site object.

ApplicationIn 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 SiteThis 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 FetchIn Gateway Navigator, create a Decision Rule that points to one of the scripts:

l Windows: EbicsFetchClient_GTW.bat

l 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:

l test

l real

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

Example on Windows:

EbicsFetchClient_GTW.bat ModelName test



For EBICS TS:

See Update payment status with PSR on page 52.

Decision Rule – for SendIn Gateway Navigator, create a Decision Rule that points to one of the scripts:

l Windows: EbicsSendClient_GTW.bat

l 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:

l test

l 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:

l real

l 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 CFTThe 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:



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.

5. From the same directory, execute the script:

l Windows: CFTUTIL #cft_ebics_client.cfg

l UNIX: CFTUTIL @cft_ebics_client.cfg

Update payment status with PSRThis 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 PSRThe 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:

l Payment Transfer Status Parser (PSRv2)

l Payment Transfer Status Parser (HAC/PSRv3)

l Payment Transfer Status Parser (PTK)

By default, Electronic Signature is configured to support Payment Status Report PSRv2 with the file format FDL.camt.002.001.02.ara. Therefore, to use the other payment status report types along with their parsers, you need to configure them.



PSR type availability l Fetch with PTK is only available for order types with three characters.

l Fetch with PSR v2 is only available for order type + file format, for example: FUL.xxxx.yyyy.

l Fetch with PSR v3 supports both order type and order type + file format.

About PSR integration in Electronic SignaturePSR 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:

l Gateway fetches PSR files from the EBICS Server at regular intervals using a Decision Rule.

l The fetched files are placed in a monitoring directory configured in Electronic Signature.

l 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).

l 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:

l After a PSR is fetched, it is stored in the directory configured in Gateway

l Electronic Signature monitors this directory

l Electronic Signature parses the file retrieved and extracts the PSR(s). A file may contain several PSRs.

l Corresponding PSR entries are created in the database (HostID, CustomerID, OrderType, OrderId, Date, Result)

l Electronic Signature selects the corresponding entry in the PSR which has been stored in the database

l The payment status is updated based on what is stored in the PSR

Updated payment status l If the server has accepted the payment then the payment status will be updated to ACCEPTED.

l 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.



l 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.

Configure PSR integration with Gateway

Fetch a PSR fileIn Gateway Navigator, create a Decision Rule that points to the script:

l Windows: EbicsPsrFetchClientWithParam_GTW.bat real <orderType> <BANK> <CUSTOMER> <USER> <path_to_PSR_Dir>

l 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:

l <OrderType> is the full EBICS OrderType of the PSR (example: FDL.camt.002.001.02.ara)

l <BANK> is the name of the EBICS Bank

l <CUSTOMER> is the name of the EBICS customer

l <USER> is the name of the EBICS user

l <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 schedulingPSR 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 previously-created Decision Rules in a schedule-type Rule Table in the Event Management/Scheduling menu of the Gateway GUI.



Limitation for Bank and Customer namesWhen 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.



Integrate Sentinel with Electronic Signature and Gateway

This section explains how to configure Electronic Signature to send events to Sentinel.

IntroductionAutomated 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. With Electronic Signature, you can also monitor the complete EBICS TS (Transport and Signature) flow.

Electronic Signature sends event for:

l ES_PENDING – The payment has been sent to Electronic Signature awaiting signature.

l ES_SIGNED – The payment has been signed in Electronic Signature and sent back to Gateway integration.

l 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.



Configure Electronic Signature for end-to-end Sentinel integrationYou must select the Sentinel Monitoring option when you install the Electronic Signature product.

You must also activate Sentinel Monitoring in the configuration file located in <Electronic Signature install dir>/data/bin. The exact name of this file depends on your platform:

Platform Configuration file

UNIX data/bin/config

Windows data\bin\config.bat

Edit the file as follows:

1. Change the value of the SENTINEL variable to TRUE.

2. Change the value of TRKHOME to the installation directory of Sentinel Universal Agent.

Note To use Sentinel, XFBTransfer must be defined inside the Sentinel Server.To get full benefit of the Sentinel tracking, Gateway should be Sentinel-enabled too.

Sentinel attribute namesThe 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.


CREATIONDATE Event creation date (dd/mm/yyyy)

ü ü ü

CREATIONTIME Event creation time (hh:mm:ss)

ü ü ü

CYCLEID CycleID of EBICS transfer

ü ü ü ü ü ü ü




DIRECTION Direction of transfer:

l E for Emission

l R for Reception

E E E R

ENDDATE Transfer end date (dd/mm/yyyy)

ü ü ü

ENDTIME Transfer end time (hh:mm:ss)

ü ü ü

FILENAME File name of payload

ü ü ü ü ü ü ü

ISALERT Indicates if transaction is in an alert state.

l 0 = not alert

l 1 = alert, not resolved

l 2 = alert, resolved

0 0 1 0

ISEND Indicates whether the transaction is completed.

l 0 = transaction not completed

l 1 = transaction completed

l 2 = transaction rejected or in error

0 0 2 2

LOCATION Machine from which events come (host name)

ü ü ü ü




MACHINE Machine hosting the event sender (host name)

ü ü ü ü

MONITOR Event sender GTW ES ES ES GTW

MONITORVERSION Event sender version

ü ü ü ü ü

PRODUCTNAME Name of event sender. EC = Axway EBICS Client

EC EC

PRODUCTOS Name of the OS running on the machine

ü ü ü ü

PROTOCOL Protocol:

l E = EBICS

l O = Original other protocol

E E E E E E O

PROTOCOLPARAMETER Parameter used to notify elements to ES

ü

RECEIVERID HID = Host ID of the bankLS = Local Site on Gateway

HID HID HID HID HID HID LS

RETURNCODE Return code 0 0 0 0 0 0

RETURNMESSAGE Rejection reason: Free text entered by the signer to explain his reason for rejecting

ü

SAPPL Not available

SENDDATE Event send date (dd/mm/yyyy)

ü ü ü ü ü




SENDERID Name of sender ü

SENDTIME Event send time (hh:mm:ss)

ü ü ü ü ü

SIGNENTITYOBJECTID EBICS User ID of sender or rejector

ü ü

STARTDATE Event start date (dd/mm/yyyy)

ü ü ü

STARTTIME Event start time (hh:mm:ss)

ü ü ü

STATE Event state:

l TOE = TO_EXECUTE

l PRO = PROCESSING

l ESP = ES_PENDING

l ESS = ES_SIGNED

l ESR = ES_REJECTION

l TER = TERMINATED

l ROU = ROUTED

TOE PRO ESP ESS ESR TER ROU

TRADEDESTINATION Host ID of EBICS Bank

ü ü ü ü ü ü

TRADEDESTINATIONALIAS Host ID of EBICS Bank

ü ü ü ü ü ü

TRADEORIGINATOR EBICS Customer ID ü ü ü ü ü ü

TRADEREQUESTTYPE EBICS file format ü ü ü ü ü ü

TRADESERVICE EBICS Order type (FUL or FDL)

ü ü ü ü ü ü




USERID EBICS User ID of sender or rejector

ü ü

Integrate Electronic Signature with Gateway and Sentinel

Check that Sentinel monitoring is activated in the configuration file located in <Electronic Signature install dir>/data/bin. The exact name of this file depends on your platform:

Platform Configuration file

UNIX data/bin/config

Windows data\bin\config.bat

Open the config file in a text editor. Check the values and modify them if necessary.

Configuration file contentsThis section displays the list of parameters contained in the configuration file.


GTW_HOME mandatoryPath to the Gateway installation directory

c:\Axway\Gateway




SENTINEL Usage of Sentinel

l TRUE: Sentinel is used

l FALSE: Sentinel not usedThis parameter must be set to TRUE if you intend to track the transfer behavior with Sentinel. Parameters TRKHOME and TRKCONF must match the Sentinel configuration, namely the Universal Agent directory and the connection configuration file.

TRUE

TRKHOME Path to the home of trkapi c:\Axway\trkapi

TRKCONF Path to the trkapi conf file %TRKHOME%\conf\trkapi.cfg

FILE_ROUTING

Used to send back the fetched file to the back-end application via Gateway (using a Model)ROUTE = transferIf "ROUTE=", in other words empty, no transfer is triggered to the back-end application. The file is kept in the Gateway temporary directory.

ROUTE

TRACE Enable traces of Gateway interoperability scripts execution.

TRUE

EBICS Client administrationAbout command lines on page 63

Syntax on page 63

Commands per use case on page 64

Parameter list on page 68

Import the TLS Bank certificate to the client keystore on page 70

General procedure to create an EBICS user on page 70

Deactivate a proxy server for a bank on page 71



About command lines This section provides information about the administration commands for the embedded EBICS Client. For more information, refer to the command help available in the command line interface (adminClient.bat --help or adminClient.sh --help).

Commands to administer Electronic Signature (including the embedded EBICS Client) are available inside the program/bin directory.

Unless stated otherwise, the command must be launched from within the bin directory.

File names should be defined with their full path.

SyntaxThe general syntax of a line command is:

OS Command

Windows adminClient.bat --[action] --[parameter 1] --[parameter

2] --[parameter n]

UNIX adminClient.sh --[action] --[parameter 1] --[parameter

2] --[parameter n]

Note When using an abbreviated parameter name (short name), use one dash before the parameter (instead of two dashes).

ExamplesadminClient.sh --action selectBank --bankName <XYZBank>

adminClient.sh -a selectBank -bn <XYZBank>



Commands per use caseAction Command

Create a new bank

-a createBank -bn <bankName> -hid <hostId> -url <url> [-ph <hostName>] [-pp <portNumber>] [-puser <user>] [-ppwd

<password>] [-na <true/false>] [-sigalg <signatureVersionA:CredentialTypeA,

signatureVersionB:CredentialTypeB>]

Create a new customer

-a createCustomer -bn <bankName> -cid <customerId> [-d

<true/false>] [-on <orderNumber>] [-sigalg <signatureVersionA:CredentialTypeA,


Update customer -a updateCustomer -bn <bankName> -cid <customerId> [-on <orderNumber>] [-d <true/false>] [-sigalg <signatureVersionA:CredentialTypeA,


Create a new user -a createUser -bn <bankName> -cid <customerId> -uid

<userId> [-protv <H00n> ] [-sigv <A00n>] [-cert

<true/false>] [-nosig <true/false>] [-d <true/false >]

Update a user -a updateUser -bn <bankName> -cid <customerId> -uid

<userId> [-nuid <newUserId>] [-protv <H00n> ]

[-sigv <A00n>] [-cert <true/false>] [-d <true/false>]

Delete a user -a deleteUser -bn <bankName> -cid <customerId> -uid

<userId>

Delete a customer -a deleteCustomer -bn <bankName> -cid

<customerId>



Action Command

Delete a bank -a deleteBank -bn <bankName>

Select a bank -a selectBank -bn <bankName> [-dh

<true/false> ]

Select all banks -a selectBank [-dh <true/false> ]

Update a bank -a updateBank -bn <bankName> [-hid <hostId>] [-url <url>]

[-ph <hostname> / none] [-pp <portNumber>] [-pu <user>]

[-ppwd <password>] [-sigalg <signatureVersionA:CredentialTypeA,

signatureVersionB:CredentialTypeB> ]

Initialize a user -a initialize -bn <bankName> -cid

<CustomerId> -uid <userId> [-on

<orderNumber>] [-sc <signatureCertificate>

] [-sp <signaturePassword>] [-ec

<encryptionCertificate>] [-ep

<encryptionPassword>] [-ac

<authenticateCertificate>] [-ap

<authenticatePassword>] [-r

<numberOfRetries>]

Reset user initialization -a resetInitialization -bn <bankName> -cid

<CustomerId> -uid <userId> [-sc

<signatureCertificate> ] [-sp

<signaturePassword>] [-ec





<numberOfRetries>]

Send signature key to a user

-a ini -bn <bankName> -cid <customerId> -

uid <userId> [-on <orderNumber>] [-sc

<signatureCertificate>] [-sp

<signaturePassword>] [-r <numberOfRetries>]



Action Command

Send authentication and encryption keys to a user

-a hia -bn <bankName> -cid <customerId> -

uid <userId> [-on <orderNumber>] [-ec





<numberOfRetries>]

Initialize a user with H3K -a h3k -bn <bankName> -cid <customerId> -

uid <userId> [-sc <signatureCertificate>]

[-sp <signaturePassword>] [-ec





<numberOfRetries>]

Update the keys used with the bank

-a renewKeys -bn <bankName> -cid

<customerId> -uid <userId> [-sc


<signaturePassword>] [-ec



<authenticationCertificate>] [-ap


<numberOfRetries>]

Update the signature key used with the bank

-a renewSigkey -bn <bankName> -cid

<customerId> -uid <userId> [-sc


<signaturePassword>] [-r <numberOfRetries>]

Update the encryption and authentication keys used with the bank

-a renewAuthkey -bn <bankName> -cid

<customerId> -uid <userId> [-ec



<authenticationCertificate>] [-ap


<numberOfRetries>]



Action Command

Lock a user account -action lock -bn <bankName> -cid <customerId> -uid <userId> [-r <numberOfRetries>]

Limitation: This command only works for an EBICS transport user. For security reasons the application does not store the private key of any EBICS signer user. Because this command needs the private key, you cannot lock an EBICS signer user.

Update the bank keys -action updateBankKeys -bn <bankName> -cid

<customerId> -uid <userId> [-eh

<encryptionHash>] [-ah

<authenticationHash>]

Reset order number for a customer

-a resetOrderNumber -bn <bankName> -cid

<customerId> [-on <orderNumber>]

Replay erroneous send orders

-a restartErroneous

Replay erroneous send order

-a restartErroneousTransfer -xfer

<transferFileName>

Enable EBICS XML traces -a enableTraces -trace <pathToTraces>

Disable EBICS XML traces -action disableTraces

Retrieve TLS certificate -a retrieveSSLServerCert -bn <bankName>

Migrate EBICS Client -a migrate -dir <<home_

dir>\Axway\Synchrony\EbicsClient> -v <260>

-a migrate -propPath <<home_

dir>\Axway\Synchrony\EbicsClient\properties

-propName BANK> -v <version251>, where

<path>\BANK.properties is the migration

file

Display this help --help | -h



Parameter listParameter short name

Parameter long name

Value(s)

-a --action See the previous section, Commands per use case on page 64.

-ac --authenticateCertificate Path to the PKCS#12 or PKCS#8 for authentication

-ah --authenticateHash <certificate file> Authentication Bank key hash

-ap --authenticatePassword Password of signature certificate/key

-bn --bankName <bank name>

-cert --certificate If certificates used in place of keys

-cid --customerId <customer ID>

-d --default Make the current User the default User for the given Customer, or make the current Customer the default Customer for the given Bank.

-dh --displayHash optional parameterWhen this parameter is specified, the Bank certificate hash is displayed. If this parameter is not specified, the whole Bank certificate is displayed in the bank information.This feature allows the user to check the database bank certificates against the PDF file the bank has sent.

-dir --directory The directory path of the EBICS Client to migrate

-ec --encryptionCertificate Path to the PKCS#12 or PKCS#8 for encryption

-eh --encryptionHash Encryption Bank key hash

-ep --encryptionPassword Password of encryption certificate/key

-h --help Displays help

-hid --hostId <host ID> Bank hostID

-na --negativeAcknowledgments Send negative acknowledgments when running from-to fetches

-nosig --noTransportSignature If the signature of a transport user is in a transfer that involves personal signatures, it must be omitted.

-nuid --newUserId The new EBICS user ID

-on --orderNumber <order Number> Set a specific order number

-ph --proxyHost <Hostname> Host of the HTTPS proxy server or none to remove the proxy



Parameter short name

Parameter long name

Value(s)

-pp --proxyPort <PortNumber> Port of the HTTPS proxy server

-ppwd --proxyPassword <password> Corresponding password if needed

-propName --propertyName The name of the migration database property

-propPath --propertyPath The path of the migration database property

-protv --protocolVersion <H002|H003>

-puser --proxyUser <Username> User name used for login if needed

-r --retries <NumberOfRetries> Set number of retries

-sc --signatureCertificate <Certificate file> Path to the PKCS#12 or PKCS#8 for signature

-sigalg --signatureAlgorithm The list of supported signature algorithms separated by a comma.Example: A004:KEYPAIR,A005:KEYPAIR,A005:CERTIFICATE

Supported values include:

l signatureVersion: A004, A005, A006

l credentialType: certificate, keyNote: A004:CERTIFICATE is not a supported combination

-sigv --signatureVersion <A004|A005|A006> EBICS protocol signature version

-sp --signaturePassword <password> Password of authentication certificate/key

-trace --ebicsTraces <Directory> Enable EBICS XML traces to the Directory

-uid --userId <EBICS user ID> User Id.

-url --URL <URL>URL on which the EBICS Server is running.

Format for the URL:https://<hostname>:<port>/path

where:

l <hostname> is the host name of the remote EBICS Server

l <port> is the TCP port of the remote EBICS Server

l <path> is the location of the EBICS application on the remote server

Example:-url https://localhost:8443/ebics/EbicsServlet



Parameter short name

Parameter long name

Value(s)

-v --version The version of the EBICS Client to migrate

-xfer --transfer The transfer file name

Note All Boolean options passing an invalid Boolean value will be treated as having a "false" value.

Import the TLS Bank certificate to the client keystoreThe EBICS protocol relies on TLS. To accept and trust the TLS certificate from the Bank, you need to install the TLS certificate as a trusted certificate.

To do this, you need to:

1. Create the Bank on the EBICS Client (with the createBank command).

2. Request the TLS certificate (with the retrieveSSLServerCert command).

General procedure to create an EBICS userTo set up an EBICS user, the general procedure is:

1. Retrieve the EBICS protocol parameters from the corresponding EBICS server. This includes the EBICS Host ID, Customer ID, EBICS User ID, URL of the EBICS connection, Hash of the Bank certificates keys.

2. Create a Bank.

3. Create the Customer inside the Bank.

4. Create the User inside the Customer.

5. Retrieve the TLS Bank certificate.

6. Initialize the user.

This step registers the user inside the EBICS server. It requires previous EBICS server settings to declare the user inside the EBICS server. The EBICS server must then accept the user definition. This acceptance is referred to as a "release".

7. Retrieve the EBICS Bank certificates.

8. Request Send or Fetch transfers.

This step refers to previously-created Bank/Customer/User, but also to a RequestType, which defines the format of the file.

Step 1 is part of the commercial agreement between the company that acts as an EBICS client and the company that manages the EBICS server.

Steps 2 to 7 are related to a dedicated command line.



Step 8 is triggered by the automated file transfer through Gateway.

Deactivate a proxy server for a bankTo deactivate a proxy server, run the following administration command:

adminClient.[sh or bat] --action updateBank --bankName <bankName> --proxyHost "" --proxyPort 0

Send and Fetch transactions with embedded EBICS Client

General behaviorThe embedded EBICS Client is a process that runs continuously, waiting for Transfer Requests.

EBICS requests are defined as an XML file set inside the 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: program/mft/Send/order.xsd

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

Samples of XML files are provided with the XML schema.



Explanation of tagsTag 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 the EBICS server as 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. There might be several user IDs for Send requests. Fetch: EBICS User name that requests the transfer. There might be only one for Fetch requests.

systemID User name that is used to transport the files without any signature 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



Tag name Description

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

signatureFile Full path name of the externally-generated signature file of the transferred data. This signature file is the signature as defined by the EBICS protocol. It contains protocol-specific data, such as CustomerId and userId. This XML file must be compliant with the program/mft/Send/ebics_signature.xsd



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|N 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.



Use embedded EBICS Client with a DMZ proxyYou can install Electronic Signature in a corporate network and use either Axway Secure Relay or an HTTP proxy in a DMZ in order to provide maximum security for your connections.

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. The embedded EBICS 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 the embedded EBICS Client. All file transfer dialog (protocol, authentication, and so on) is handled by the embedded EBICS Client. 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 Secure Relay documentation.

Configure embedded EBICS Client for Secure RelayThe embedded EBICS Client can be configured with Secure Relay to go through a DMZ configuration. The Secure Relay configuration is global for the embedded EBICS Client installation.

If you want to activate the use of Secure Relay, or modify any settings, use the Configuration tool. For details, see Use the Electronic Signature Configuration tool on page 15.

For an advanced configuration of Secure Relay settings, see secureRelayConf reference on page 135.

Activate the use of Secure Relay as follows:

1. Open the configuration.properties file located in the <Electronic Signature install dir>/data/conf directory.

2. Set the variable conf.enable.secureRelay.proxy to "true".

3. Open the secureRelayConf.xml file located in the <Electronic Signature install dir>/data/conf directory.

4. Update this file based on the configuration of the Secure Relay Router Agent located in the DMZ.



Configure embedded EBICS Client with an HTTP proxyThe embedded EBICS Client can be configured with an HTTP proxy in order to go through a DMZ configuration. The proxy configuration is stored at the EBICS Bank side. You can configure several HTTP proxies for the same Electronic Signature (with embedded EBICS Client) installation.

When you create an EBICS Bank, you need to provide the following information:

l Proxy hostname

l Proxy TCP port

l Login of the proxy user (this parameter is optional)

l Password of the proxy user (this parameter is optional)

Details of the Bank creation command:

adminClient.bat --action createBank --bankName <bankName> --url <url> --hostId <hostId> [--negativeAcknowledgments] [--proxyHost <hostname> --proxyPort <PortNumber> [--proxyUser <id>] [--proxyPassword <pwd>] ]

Note Secure Relay and http proxy configuration cannot be used at the same time.


5 Control Electronic Signature

This chapter describes how to perform basic tasks, such as starting Electronic Signature or connecting to the UI.

Command scripts on page 77

Start Electronic Signature on page 78

Connect to the Electronic Signature UI on page 78

Stop Electronic Signature on page 79

Check the Electronic Signature status on page 79

Start and stop Electronic Signature in Windows service mode on page 79

Command scriptsThe <Electronic Signature install dir>/program/bin directory contains several scripts that control Electronic Signature:

Command name(.bat or .sh)

Description

esPurge.bat Purge old payments in Electronic Signature. See Purge payments in Electronic Signature on page 102.

esStart.bat Start Electronic Signature.The command will not return until the process is ended.

esStatus.bat Check if Electronic Signature is started or not

esStop.bat Stop Electronic Signature

adminClient.bat Used for administration of the embedded EBICS Client

Note You must start Electronic Signature in order to use the embedded EBICS Client and to allow administration or transfers.



The <Electronic Signature install dir>/data/bin directory contains several scripts that control Electronic Signature:

Command name(.bat or .sh)

Description

config or config.bat Configuration script for integration with Gateway and Sentinel

profile Used to define the Java parameters

Start Electronic Signature

On WindowsFrom the Windows Start menu, select Start Electronic Signature.

Alternatively, double-click the Start Electronic Signature icon on your desktop.

On UNIXRun the script esStart.sh located in the <Electronic Signature install dir>/program/bin directory.

Connect to the Electronic Signature UI 1. From the Windows Start menu, select Electronic Signature UI.

The Electronic Signature UI opens.

2. Log in as administrator.

l Default user ID: admin

l Default password: Secret1

For information about administration tasks, such as creating users or rules, refer to the Electronic Signature User Guide.



Stop Electronic Signature

On WindowsRun the script esStop.bat located in the <Electronic Signature install dir>\program\bin directory.

On UNIXRun the script esStop.sh located in the <Electronic Signature install dir>/program/bin directory.

If for any reason this does not function, use esStop.sh -f. This will kill the server process.

Check the Electronic Signature status

On WindowsRun the script esStatus.bat located in the <Electronic Signature install dir>\program\bin directory.

On UNIXRun the script esStatus.sh located in the <Electronic Signature install dir>/program/bin directory.

Start and stop Electronic Signature in Windows service mode

Prerequisite: When Electronic Signature was installed, the Run as a Windows service option was selected.

Start Electronic SignatureUse the Windows Services application to start the service:

1. From the Windows Control Panel, select Administrative Tools > Services.



Windows displays the Services window.

2. Scroll down the Services list and right-click the Electronic Signature service.

3. From the context menu, select Start.

Alternatively you can use the shortcut in the Windows Start menu:

Axway Software > Electronic Signature > Start Electronic Signature

Stop Electronic SignatureUse the Windows Services application to stop the service:

1. From the Windows Control Panel, select Administrative Tools > Services.

Windows displays the Services window.

2. Scroll down the Services list and right-click the Electronic Signature service.

3. From the context menu, select Stop.

Alternatively you can use the shortcut in the Windows Start menu:

Axway Software > Electronic Signature > Stop Electronic Signature


6 Manage Electronic Signature Agent

This chapter explains how to manage the Electronic Signature Agent. This agent replaces the Java applet that was used in earlier versions of Electronic Signature and can be used to sign payments.

PreparationBefore you install the Electronic Signature Agent, ensure that:

l Electronic Signature is installed on a server

l You work in a Windows-based environment

l You have either signer rights or administrator and signer rights. If you have signer rights, the following tabs display: File Signature and Bank management.

Download Electronic Signature AgentTo download the installer:

1. Log in to the Electronic Signature GUI.

2. In the top-left corner of the GUI, click the Bank Management tab.

3. In the top-right corner, click the Agent tab to download the Electronic Signature agent.

4. Save the file.



Install Electronic Signature AgentYou can run the installer in any of the following three modes.

Graphical modeYou can access the Electronic Signature Agent in the Downloads folder. After you double-click the ElectronicSignatureAgent.exe application, follow the on-screen instructions.

Step Description

Welcome screen After you have started the installer on your machine, you access the welcome screen.

License agreement

Accept the software license agreement.

Destination directory

Accept the default destination directory or specify a new one. The specified folder must be empty.

Desktop shortcut

Windows only (not available for Windows service mode)Specify whether or not you want to create a desktop shortcut and a shortcut in the Start menu.

Installation The installation process is shown as a progress bar.

When the installation has finished, you will be redirected to the last screen of the installer.Click Finish to exit the installer.

Silent modeSilent mode (unattended mode) enables you to perform an installation in a non-interactive mode. You do not have to enter any parameters in the interface or console.

Silent mode installationWhen you install the Electronic Signature Agent on one machine, the installer automatically generates a response.varfile in the .install4j folder of the installation directory. This installation response.varfile contains all the data that is necessary to create duplicate installations on other machines.



Example of response.varfile contents:

# install4j response file for Axway Electronic Signature Agent 2.10.0

sys.adminRights$Boolean=true

sys.installationDir=C\:\\Axway\\ElectronicSignatureAgent

sys.languageId=en

sys.programGroupAllUsers$Boolean=true

sys.programGroupDisabled$Boolean=false

sys.programGroupName=Axway Software\\Electronic Signature Agent

To install the Electronic Signature Agent on another machine, run the following command in the command line:

ElectronicSignatureAgent.exe -q -varfile response.varfile

Console modeConsole mode enables you to display a series of prompts that require user responses or actions.

To install the Electronic Signature Agent in console mode:

1. Run the following install command in the command line:

start /wait ElectronicSignatureAgent.exe -c

2. Follow the installation steps.

Change the port valueThe Electronic Signature Agent is configured by default to communicate with Electronic Signature through port 8085. If you do not want to use this port, you can change its value. You have to modify this value for the agent and for Electronic Signature, otherwise Electronic Signature cannot communicate with the Agent.

Note Stop the agent before changing the port value.

Change the port value in Electronic Signature Agent 1. Go to: <Electronic Signature Agent install dir>/program/bin

2. Open the start.bat file.

3. Add --server.port=8085 at the end of the last line.

4. Replace 8085 with the required port number.



Change the port value in Electronic Signature 1. In the <Electronic Signature install dir>/data/conf directory, open the

configuration.properties file.

2. Change the value for the server.restAgentPort parameter.

Display the port used by the Agent at startup 1. Go to: <Electronic Signature Agent install dir>/program/bin

2. Open the start.bat file.

3. Add -Dlogging.level.root=INFO before -jar %EXECUTABLE_JAR%

4. Save the changes.

When the agent starts up, it will display its listening port in the log and on the command line.

How to import certificatesWhen you start the agent, you can automatically load certificates that are stored in:

l Your Windows OS

l A USB token or a key that you plug into your computer

If you want to import a certificate that is not stored in your machine or your USB token, you must use the REST API of the agent.

Import a certificate via the REST APIImportant: This is an easy way of adding certificates for testing. Do not use this option in a production environment.

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:

http://localhost:8085/esignagent/api/v1/certificate

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:

l A PKCS#12 certificate encoded in base64

l 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.

Start Electronic Signature AgentIf you created a shortcut during the installation (on the desktop, for example), double-click the shortcut to start the agent.

Alternatively, go to <Electronic Signature Agent install dir>program/bin and run the start.bat file.

Stop Electronic Signature AgentIf you created a shortcut during the installation (on the desktop, for example), double-click the shortcut to stop the agent.

Alternatively, go to <Electronic Signature Agent install dir>program/bin and run the stop.bat file.

Warning: When you stop the agent, all imported certificates disappear from the list that displays in Electronic Signature.

Access the log filesTo access the log files:

1. Go to <Electronic Signature Agent install dir>/data/log

2. Open the following log file: electronic_signature_agent.log



Troubleshooting

Electronic Signature UI error during communication with the agent using Google ChromeIssue: If you are using a recent version of Google Chrome, you might not be able to use the agent with your Electronic Signature UI. This is because the browser attempts to pass the HTTP requests from the UI using HTTPS. However, this is not supported by the agent.

Workaround 1: To prevent Chrome from using HTTPS for the communication between the Electronic Signature UI and the agent, you need to delete some HSTS settings in Chrome as follows:

1. Enter the following command in the address bar:

chrome://net-internals/#hsts

2. In the section "Delete domain security policies", enter localhost and click Delete.

Your browser will no longer force an HTTPS connection for this connection.

Workaround 2: It is also recommended to clear your browser's cache.

Electronic Signature UI error during communication with the agent using FirefoxIssue: If you are using a recent version of Firefox, you might not be able to use the agent with your Electronic Signature UI. This is because the browser attempts to pass the HTTP requests from the UI using HTTPS. However, this is not supported by the agent.

Workaround 1: To prevent Firefox from using HTTPS for the communication between the Electronic Signature UI and the agent, you need to delete some HSTS settings in Firefox as follows:

1. Close all open tabs in Firefox.

2. Open the full History window with the keyboard shortcut Ctrl + Shift + H. You must use this window or the sidebar for the below options to be available.

3. Find the site for which you want to delete the HSTS settings. You can search for the site at the upper right if needed.

4. Right-click the site from the list of items and click Forget About This Site. This should clear the HSTS settings (and other cache data) for that domain.

5. Restart Firefox and visit the site.

Workaround 2: It is also recommended to clear your browser's cache.


7 Extend support to other formats

This chapter explains how to use the parser exit to create your own parser implementation. This determines how the payment details are displayed in the Electronic Signature UI.

Payload parserPayload files contain information such as the number of payment operations, payment amount, account information, and so on. The parser provides methods to allow parsing of the payload files and retrieve the information.

Axway provides default implementation for the following parsers:

l Cfonb160 Transfer

l Cfonb160 Debit

l Cfonb320

l SEPA Transfer

l SEPA Debit

l Raw

The Raw parser only reads the payload file and displays the information as text. For large files the information is truncated and the parser only stores the first and last 1000 characters.

All these parsers are delivered as samples for the implementation of the CFONB160, CFONB320 and SEPA file formats to show how to extend the file format support or just to customize the existing parser implementation.

Modify the parser exitThe parser samples are located in <Electronic Signature install dir>/program/devKit/parser.

1. Make sure 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-app-parser-sample-{version}.jar file are generated.


7 Extend support to other formats

3. To implement your own parser, consult the javadoc of the parser library, located in <Electronic Signature install dir>/program/devKit/parser/docs/ and analyze the sample.

4. After creating your own parser, edit the <Electronic Signature install dir>/data/conf/configuration.properties file and add your parser to the payload parser section:

l payLoad.parser.name.1=YourParserName

l payLoad.parser.class.1=com.axway.esign.app.java.core.samp

les.

parser.YourParserName

l Add the JAR file to the external.classpath property

l Check that these lines are not commented out with a # character

At startup, Electronic Signature will add the sample JAR file to the classpath.


8 Develop exits for Electronic Signature

Overview of the exit framework on page 89

Description of the exit framework API on page 89

Development on page 91

Overview of the exit frameworkIn the main use case of Electronic Signature, a signer user can sign or reject a payment. To enable you to add specific post-processing behavior in this use case (for example, adding a payload in a specific archiver, generating a signature proof, and so on), Electronic Signature provides an Exit Framework as an API.

This framework is an asynchronous events dispatcher. When a payment is signed or rejected, a corresponding event is created and placed in a persisted queue. A periodic timer dispatches all these events to the registered implementation of the API. After being dispatched, an event is removed from the queue. For each event a post-processor instance is launched which enables you to post-process several events simultaneously. As such, the exit is not processed immediately after the signature or rejection action.

The success or failure of the post-processing is of no significance to the framework. It only ensures that all the events are correctly dispatched to post-processors. The error management is in charge of the exit implementation that you develop.

Description of the exit framework APIThere are two kinds of event: Sign Event and Reject Event. Each one is dispatched to a specialized class of post-processing: SignExitOperation and RejectExitOperation. An event is a set of properties such as payment signer, received date, payment number and so on. A property is defined by a unique String key and a value which together constitute a Java Object. The list below describes the main interfaces and classes of the API. For more information, refer to the Exit API Javadoc.

The main interfaces and classes of the API are:

l com.axway.esign.app.java.exit.IExitOperation

This is the main interface of the API. It globally defines an Exit Operation: a post-processing operation on an event. It must not be directly implemented and is created for architectural purposes only.



Two kinds of event are provided: sign event and reject event. For each kind, a specific IExitOperation is called to process it. Likewise, there are also two kinds of IExitOperation to process them which are abstract classes: SignExitOperation and RejectExitOperation.

The framework ensures that a sign event is dispatched to a SignExitOperation and does the same for a reject event. Custom implementations of a SignExitOperation or a RejectExitOperation only have to be registered in the configuration of Electronic Signature.

Custom implementation has to be a derived class from one of these abstract classes. Be careful, an IExitOperation implementation MUST respect the following properties:

o Thread safe: an IExitOperation is launched in a Thread and several instances of the same IExitOperation may run simultaneously.

o Stateless: an IExitOperation is a one time execution meaning that the framework creates a new instance of the IExitOperation for each event. When the event is post-processed, the corresponding IExitOperation is "destroyed".

The framework sends an event to an IExitOperation. An event is basically a set of properties such as the date of the rejection of a payload, the name of the user who rejects it, the file name of the payload, and so on. So an event is represented by a HashMap containing all its properties. Each property is indexed in the HashMap by a String Key which is defined in the IExitPropertiesKey.

l com.axway.esign.app.java.exit.IExitPropertiesKeys

List of all the keys that can be used in a HashMap event. The type of indexed Object in the HashMap is provided in the documentation of the Key. Refer to the Exit API Javadoc.

l com.axway.esign.app.java.exit.sign.SignExitOperation

Abstract class representing a SignExitOperation that executes the post-processing for a signed payload. This class can be derived to provide custom post-processing on a sign event. It contains an abstract method named executeSignPostProcessing which is called by Electronic Signature. Redefine this method to provide custom post-processing implementation.

l com.axway.esign.app.java.exit.reject.RejectExitOperation

Abstract class representing a RejectExitOperation and executes the post-processing for a rejected payload. This class can be derived to provide custom post-processing on a reject event. It contains an abstract method named executeRejectPostProcessing which is called by Electronic Signature. Redefine this method to provide custom post-processing implementation.



Development

PrerequisitesElectronic Signature provides a sample implementation of the Exit Framework. This sample is developed in Java and its environment based on Maven and Eclipse.

Oracle Java 1. Installation:

a. Download Oracle Java JDK6 from: http://www.oracle.com/technetwork/java/javase/downloads/jdk-6u25-download-346242.html.

b. Install Oracle Java JDK6 on your system.

c. Accept the license agreement and select a delivery in the list for your platform.

2. Setting the path

Set up your path environment variable:

On Windows:

a. Right-click the Computer Icon on your desktop and click Properties.

b. If using Windows 7, in the ControlPanel, select Advanced System Settings on the left.

c. In the System Properties window, click the Advanced tab then click Environment Variables.

d. Create a new User Variable by clicking New.

e. Name it JAVA_HOME and set the value to the Java installation directory path, usually in C:\Program Files\Java\jdk1.6.XXX if you did not specify another location.

Note that the XXX represents the version of your Java installation.

f. Click OK.

g. Go to the Systems Variables list and select the variable named PATH. Then click Edit.

h. At the end of the value line add: ";%JAVA_HOME%\bin". (Without the " and do not forget the ; at the beginning ).

On Linux:

To set up the PATH on a Linux system, edit the file ~/.bashrc. Add the following lines at the end of the file:

export JAVA_HOME=<YOUR JAVA INSTALL DIR>

export PATH=$PATH:$JAVA_HOME/bin


http://www.oracle.com/technetwork/java/javase/downloads/jdk-6u25-download-346242.html

http://www.oracle.com/technetwork/java/javase/downloads/jdk-6u25-download-346242.html


Apache MavenThe sample is packaged with Apache Maven.

1. Go to http://maven.apache.org/download.html.

2. Select a Maven version 2.2.1 in the Mirrors list and download it.

3. To install Maven, go to http://maven.apache.org/maven-1.x/start/install.html. For Linux users, remember to define your MAVEN_HOME and add it to the PATH, see Setting the path on page 91.

EclipseThe sample is packaged for Eclipse IDE. If you do not have it:

1. Download the Classic distribution from: http://www.eclipse.org/downloads/.

2. Select your platform and select a mirror.

The download starts.

3. Unzip the Eclipse Archive file wherever you want.

The executable eclipse file is <Eclipse install dir>/eclipse/eclipse.

Develop exits

Getting startedIn your development environment, make sure you are using Java 1.6 and Maven 2. After creating your project add the following jars into your build path:

l log4j-1.2.16.jar. The logger used by the Exit API. If you do not have the file, go to http://logging.apache.org/log4j/1.2/download.html, unzip the archive and put the jar in your build path. Install is not necessary.

l esign-app-java-exit.jar. The Exit API. It is located in <Electronic Signature install dir>/program/devKit/exit/lib.

l esign-app-java-exit-javadoc.jar. The Exit API Javadoc. It is located in <Electronic Signature install dir>/program/devKit/exit/lib. Link it as Javadoc archive for esign-app-java-exit.jar. If you want to access the Javadoc from a web browser, copy this jar to a directory, open a terminal and run jar xvf esign-app-java-exit-javadoc.jar. This will extract all the Javadoc in the current directory.

l sentinel-ua.jar The Sentinel framework that allows you to send notification to Sentinel from your implementation, if required. It is located in <Electronic Signature install dir>/program/devKit/exit/lib.


http://maven.apache.org/download.html

http://maven.apache.org/maven-1.x/start/install.html

http://www.eclipse.org/downloads/

http://logging.apache.org/log4j/1.2/download.html


Now you can start your development. If you want to create a post-processing of a signature, create a class which extends SignExitOperation (or for a reject post-processing extend RejectExitOperation).

Then override the following methods:

@Override

public void setEvent(HashMap<String, Object> event) {

/*

* This method is called by Electronic Signature to send the event

to your IExitOperation.

* At least you should store the event.

*/

}

@Override

public void executeSignPostProcessing() { // Or

executeRejectPostProcessing() for a RejectExitOperation.

/*

* This method is called by Electronic Signature after setEvent.

* Put your custom post-processing there.

*/

Note: All implementations are, in fact, stateless because an instance of your IExitOperation is created for each event. Remember to ensure thread safety. Several instances of your IExitOperation may run at the same time in different threads.

You can pack several IExitOperation in the same jar. However, only one SignExitOperation class and only one RejectExitOperation class will be loaded in Electronic Signature.

Note that the runtime directory of Electronic Signature (and that of your implementation) is <Electronic Signature install dir>.

Install and configure exit implementation in Electronic Signature 1. Place your jar and all its dependencies in <Electronic Signature install

dir>/program/lib without the Exit API jars, Sentinel API jar and log4j.

2. To configure Electronic Signature to run your implementation, open the configuration.properties file located in <Electronic Signature install dir>/data/conf.

3. Navigate to the Exit Configuration part:

######################################



#### Exit Configuration ####

######################################

# frequency of exit scanner, default 60 seconds

# the value is in milliseconds

exit.pollingFrequency=60000

# size of the thread pool used for reject exit processing

exit.reject.thread.pool.size=2

# size of the thread pool used for sign exit processing

exit.sign.thread.pool.size=5

# activate the reject exit post-processing

exit.useReject=false

# the name of the implementation class of the reject exit

exit.reject.classname=

# the classpath with all the dependencies of the reject

exit

# all jars must be separated by ; example:

file:jars/signExit.jar;file:lib/dependency1.jar;file:lib/d

ependency2.jar

exit.reject.classpath=

# activate the sign exit post-processing

exit.useSign=false

# the name of the implementation class of the sign exit

exit.sign.classname=

# the classpath with all the dependencies of the sign exit

# all jars must be separated by ; example:

file:jars/signExit.jar;file:lib/dependency1.jar;file:lib/d

ependency2.jar

exit.sign.classpath=

where:

o exit.pollingFrequency defines the frequency of event dispatching. In this example, the queued events are dispatched every 60 seconds.

o exit.reject.thread.pool.size defines how many instances of your RejectExitOperation implementation can be run at the same time.

o exit.sign.thread.pool.size defines how many instances of your SignExitOperation implementation can be run at the same time.

o exit.useReject defines if Electronic Signature dispatches events to RejectExitOperation or not. Set to True if you want to register your own RejectExitOperation implementation.



o exit.reject.classname defines the name of the RejectExitOperation to be used in Electronic Signature. Use your implementation class full name with its packages (for example: com.axway.esign.app.java.exitsample.RejectSentinelNotifier

).

o exit.reject.classpath defines the necessary classpath to execute your RejectExitOperation. This list must be formatted: file:jars/signExit.jar;file:lib/dependency1.jar;file:lib/

dependency2.jar ("file:" is necessary). Do not add the Exit API jars to this list.

o exit.useSign defines whether Electronic Signature dispatches events to SignExitOperation or not. Set to True if you want to register your own SignExitOperation implementation.

o exit.sign.classname defines the name of the SignExitOperation to be used in Electronic Signature. Put your implementation class full name with its packages (for example: com.axway.esign.app.java.exitsample.XMLProofSignature).

o exit.sign.classpath defines the necessary classpath to execute your SignExitOperation. This list must be formatted: file:jars/signExit.jar;file:lib/dependency1.jar;file:lib/

dependency2.jar ("file:" is necessary). Do not add the Exit API jars to this list.

Now you can run Electronic Signature and test your implementations.

Sample exitElectronic Signature provides a sample of Exit API implementations. It is located in<Electronic Signature install dir>/program/devKit/exit/.

Import a sample project into Eclipse 1. Open a terminal and go to <Electronic Signature install

dir>/program/devKit/exit/.

2. Run mvn eclipse:eclipse.

This generates the .classpath and the .project files.

3. Import it into Eclipse using the import menu.

4. Set the root directory of the project to <Electronic Signature install dir>/program/devKit/exit/.



Build the sample 1. Open a terminal and go to <Electronic Signature install

dir>/program/devKit/exit/.

2. Launch an MVN clean install.

This builds the sample and at the end of the building phase you should find a target directory with the following:

l esign-app-exit-sample.jar. The jar of the sample.

l esign-app-exit-sample-javadoc.jar. The corresponding JavaDoc.

l esign-app-exit-sample-2.7.0-SNAPSHOT-bin.zip (and a .tar.gz one for UNIX platforms) which is the delivery of the sample.

Sample descriptionThe following sample contains two different implementations:

l XMLProofSignature which is a SignExitOperation.

This SignExitOperation creates a proof signature of a sign event. This proof is generated in XML using JAXB and is placed in a directory named "proofs". The XML proof is defined by an XML Schema (XSD) which is located in src/main/resources/xsd/signatureProof.xsd. This XSD basically defines the payment characteristics (bank id, customer id, order number, order type and so on) and its signature(s) (the signer user, certificates used to sign it, and so on). JAXB generates Java data types which correspond to the XSD definition (in src/main/generated). These data types contain the sign event properties and JAXB serializes it into an XML file in the proof directory.

l RejectSentinelNotifier which is a RejectExitOperation.

This RejectExitOperation uses the Sentinel API to send a notification to Sentinel. Sentinel is a monitoring software. When it gets a reject event, it places a copy of the rejected payload in a custom directory named "rejected". It then retrieves the SentinelAppender (which is the notification tool) from the reject event. A SentinelEvent is created with the HashMap reject event provided by Electronic Signature and this event is sent to Sentinel through the SentinelAppender.

Both are located in <Electronic Signature install dir>/program/devKit/exit/src/main/java/com/axway/esign/app/java/exitsample

Install the sample in Electronic Signature 1. Unzip the delivery archive generated during the build.

This generates an esign-app-exit-sample directory.



2. Copy all its subdirectories (lib/, doc/ and conf/) to <Electronic Signature install dir>.

3. Copy esign-app-java-exitsample.jar (from the root of <Electronic Signature install dir>/program/devKit/exit/) to <Electronic Signature install dir>/program/lib.

4. Configure the code in Electronic Signature in the directory <Electronic Signature install dir>/data/conf/configuration.properties.

5. Replace it with the following code in the "Exit configuration" section:

exit.useReject=true exit.reject.classname=com.axway.esign.app.java.exitsample.RejectSentinelNotifier exit.reject.classpath=file:program/lib/esign-app-java-exitsample.jar exit.useSign=true exit.sign.classname=com.axway.esign.app.java.exitsample.XMLProofSignature exit.sign.classpath=file:program/lib/esign-app-java-exitsample.jar

6. Create a file with the name exit-sample.properties and insert the following content:

Operating System

Content

Unix proof.output.dir=data/proofs

reject.output.dir=data/rejected

Windows proof.output.dir=data\\proofs

reject.output.dir=data\\rejected

7. Put the exit-sample.properties file in the <Electronic Signature install dir>/data/conf directory.

8. Start Electronic Signature.


9 Use PassPort with Electronic Signature

This chapter explains how to use Axway PassPort with Electronic Signature.

Post-installation on page 98

Renew PassPort certificates on page 101

Electronic Signature can use PassPort AM to store the following:

l User definition in PassPort AM repository or in an LDAP repository

l Role definition

l Link between users and roles

PassPort also provides a Single Sign On (SSO) feature. Single sign-on enables users to log in to multiple Axway products with just one user name and password. To use this feature you must enable SSO during the installation of PassPort. This means that users are not required to log in each time they access the Electronic Signature UI.

Note You can use the Configuration tool to reconfigure the Access Management installation. However, you cannot use the Configuration tool to switch from PassPort AM mode to Electronic Signature mode or vice versa. This would cause data inconsistency in the database.

Post-installationAfter installing Electronic Signature, you must:

l Start Electronic Signature

l Create admin and Signer users in PassPort

l Update PassPort properties

l Import users from PassPort

l Manage groups of users

Start Electronic Signature for the first timeStart Electronic Signature.

The first start of Electronic Signature automatically imports all required data into PassPort:

l Resources that can be protected by permissions

l Predefined privileges



l Predefined roles

Basically, Electronic Signature has two resources: Payment and Administration.

l Payment represents the payment files that can be signed in Electronic Signature.

l Administration is related to the application pages used to administer Electronic Signature.

Two predefined privileges are defined: Sign payments and Manage administration.

l Sign payments allows a user to sign, reject or validate a payment file or to initialize a bank.

l Manage administration allows a user to create basic objects (bank, file format, and so on) and create rules for payments or import a user from PassPort and define a group of signers.

Two predefined roles are defined: Electronic Signature Signer and Electronic Signature Administrator.

l All users assigned to Electronic Signature Signer role have Sign payments privileges. They can sign, validate or reject payments.

l All users assigned to Electronic Signature Administrator role are the administrators of the application. They have Manage administration privileges.

Note For more information about resources, predefined privileges and predefined roles, refer to the PassPort documentation.

Create Administrator and Signer users in PassPortLog in to the PassPort UI with an administrator userID and create all the users you need for Electronic Signature. You can then assign roles to the created users. You can assign Electronic Signature Signer and Electronic Signature Administrator roles. You have to create at least one user with Electronic Signature Administrator role and one with Electronic Signature Signer role. Refer to the PassPort Administrator Guide for more information about creating users and assigning roles.

Note Instead of storing user definitions in PassPort, you can use an external LDAP directory. You have to connect the LDAP directory to PassPort. Refer to the PassPort Administrator Guide for more information.

Update PassPort properties 1. Log in to the PassPort UI with an administrator user ID.

2. Browse to the System properties menu.

3. Set the property: am.users.by.domain.query=true

Import Signer users from PassPort 1. Connect to Electronic Signature with one of the administrator users you have created.

2. From the Administration menu, browse to the Users pane and click Add User.



3. Enter the userID of each signer user created in the previous step.

4. Assign those users to a group with Signer option.

Define users who will receive email notificationsIn Electronic Signature, some users must receive an email notification when a payment is imported but no rule matches. Those users should then correct the integration because wrong files have been generated or update the rule definition in order to take into account the new file.

1. From the Administration menu, browse to Group menu.

2. Create a new group with Administrator option.

3. Assign users to the group.

PassPort self-registrationWhen Electronic Signature connects for the first time to PassPort, it registers itself.

By default, the following files are provided:

l es_csd.xml: File to be imported into PassPort as a CSD in order to create Electronic Signature roles and privileges.

l es_sso.jks: Keystore that contains the SSO certificate. It is used with SSO integration with PassPort.

l passport_truststore.jks: Keystore that enables self-registration of Electronic Signature inside PassPort. It is used for securing the communication between Electronic Signature and PassPort.

The self-registration generates the following files:

l passport_csr.id

l passport_es_keystore.jks

l passport_es_pkey.p8

l passport_es_pkey.p8.pub

If Electronic Signature needs to renew the self-registration in order to connect to another PassPort server, the above files must be removed manually.



Renew PassPort certificatesIf the default PassPort certificates have expired it will not be possible to connect to PassPort in SSO mode. Perform the following procedure to renew your PassPort certificates.

Default certificates provided by PassPort 1. Stop Electronic Signature and PassPort.

2. Ensure that the certificates in PassPort are valid.

3. Remove the expired keystore es_sso.jks, located in <Electronic Signature install dir>/data/conf/passport, from Electronic Signature.

4. Copy the new keystore, PassPort/conf/security/ssl.jks, from PassPort to the following location in Electronic Signature: <Electronic Signature install dir>/data/conf/passport.

5. In Electronic Signature, rename ssl.jks to es_sso.jks.

6. Restart PassPort and Electronic Signature.

The connection between PassPort and Electronic Signature is now restored.

Non-PassPort certificates 1. Stop Electronic Signature and PassPort.

2. Create a new keystore for PassPort in PassPort/conf/security/ and name it ssl.jks.

3. Copy this keystore to the following location in Electronic Signature: <Electronic Signature install dir>/data/conf/passport.

4. In Electronic Signature, rename ssl.jks to es_sso.jks.

5. Restart PassPort and Electronic Signature.

The connection between PassPort and Electronic Signature is now restored.


10 Purge payments in Electronic Signature

After payments have been signed or rejected they remain visible in the Electronic Signature UI. After a while you should purge the old payments so that the list of payments remains manageable for the signer.

The esPurge command (located in the program/bin directory) enables you to perform this action by deleting the following:

l Payments from the database

l The payment index file (the file containing the payment details per payment)

l The payload file

l The associated XML file (Electronic Signature with Gateway case)

l PSR objects from the database, based on the PSR expiration day values in the configuration.properties file

On the command line, enter the esPurge command with the required parameters.

Command syntax on page 102

Parameter usage on page 103

Database records on page 104

Command syntaxesPurge -d <DD/MM/YYYY>

esPurge -d <DD/MM/YYYY> -s <status>

esPurge -id <payment id>

esPurge -ff <file format>

where:

l -d (date) is optional

l -s (status) is optional

l -id (payment identifier) is optional

l -ff (file format) is optional



Parameter usageIf you use the -d parameter only:

l The esPurge command purges all transfers before the specified date in the ACCEPTED, REFUSED, REJECTED, and SEND_ERROR states.

If you also use the –s parameter:

l The esPurge command purges all transfers before the specified date in the specified state. Available states:

o BEGINNING

o SIGNATURE_NEEDED

o SECOND_SIGNATURE_NEEDED

o VALIDATION_NEEDED

o SIGNED

o SENDING

o REJECTED

o SEND_ERROR

o SENDING

o SENT

o ACCEPTED

o REFUSED

The SIGNED and SENDING statuses are both shown in the UI as Sending.

If you want to purge payments that appear with SENDING status in the Electronic Signature UI, execute the command twice as follows:

1. Execute Purge with status parameter set to SIGNED.

2. Execute Purge with status parameter set to SENDING.

Once both command lines are executed, payments with SENDING status in the Electronic Signature UI will be removed.

The payload file related to the purged payment will be deleted from the disk. When Electronic Signature is configured in Gateway mode, the XML files used to import the payment will also be deleted from the disk.

The BEGINNING state corresponds to the payments without a workflow. These payments are not visible in the UI as no matching rule is found.

If you use the -id parameter only:

l The esPurge command purges all transfers by payment identifier.

If you use the -ff parameter only:

l The esPurge command purges all transfers by file format.



The payload file related to the purged payment will be deleted from the disk. When Electronic Signature is configured in Gateway mode, the XML files used to import the payment will also be deleted from the disk.

Database recordsThe esPurge command also purges fex_psr records from the database. Electronic Signature maintains these records in order to match payment files and PSRs. The command automatically removes records older than the expiration date.

The expiration date is defined in the configuration file, by the property psr.purge.expirationDays. By default, this property is set to 30 days. If you need to change it, choose a value that is:

l Big enough to ensure that the period is longer than the maximum time between sending a payment and fetching the corresponding PSR

l Small enough to maintain the fex_psr table within a reasonable size

Avoid setting expirationDays to 0 as the esPurge command could delete fex_psr records that have not yet been reconciled. A PSR fetch must be done within the expirationDays period. For example if the value is set to 7 then at least one PSR fetch must have been executed within the last week.


11 Single sign-on using SAML

Single sign-on (SSO) is a session/user authentication process in which a user enters one name and password to access multiple applications. Axway Electronic Signature supports SAML-based single sign-on (SSO).

The SAML 2.0 standard describes how to exchange authentication and authorization data between entities. This section describes some key concepts.

Service ProviderA Service Provider (SP) protects access to requested resources, such as websites and applications by applying a security policy. For example, the SP blocks all access to an unauthenticated user and routes the request to the Identity Provider. Electronic Signature acts as an SP.

Identity ProviderAn Identity Provider (IdP) is a system that creates, maintains, and manages identity information for users, services, or systems, and provides authentication to other service providers (applications) within a network. An IdP is a trusted entity that users and servers can rely on when they are establishing a dialog that must be authenticated. The IdP sends an attribute assertion containing trusted information about the user to the SP. In an Axway deployment, the IdP is a third party product.

User AgentA user agent is usually a web browser. The person who uses the browser can be referred to as a user or as a principal.

Security Assertion Markup Language (SAML)The Security Assertion Markup Language (SAML) is an XML-based solution for exchanging user security information (authentication, authorization) between an IdP and SP. SAML is a product of the OASIS Security Services Technical Committee. It supports W3C XML encryption.



An assertionAn assertion is a package of information that contains one or more statements made by an SAML authority. The SAML standard defines three types of assertion statement:

l Authentication: The specified subject was authenticated by a particular means at a particular time. This kind of statement is typically generated by an IdP.

l Attribute: The specified subject is associated with the supplied attributes.

l Authorization decision: A request to allow the specified subject to access the specified resource has been granted or denied.

Electronic Signature implementation behaviorWhen using SAML-based SSO, be aware of the following:

l The third-party IdP is used for authentication, not for authorization. Authorization details are configured in the Electronic Signature role definitions as before.

l Authorization is still checked by Electronic Signature. In the Electronic Signature user interface, you can specify the role groups that a user belongs to. This role group determines a user's authorized functional access.

l A user must be defined in both the IdP and Electronic Signature.

l User passwords are managed in the IdP. SSO-authenticated users cannot change their own passwords via the Electronic Signature UI.

SAML 2.0 complianceThe current version of Electronic Signature (2.10.0) supports the following features of the SAML 2.0 standard:

l Web SSO, AuthRequest, HTTP redirect

l Web SSO, Response, HTTP POST

l Single Logout (IdP initiated), HTTP redirect

l Single Logout (SP initiated), HTTP redirect

Login sequenceWhen Electronic Signature is configured for SSO, the following events occur during authentication between Electronic Signature, which acts as the SP, and the IdP:

1. The end user tries to access the Electronic Signature UI using a web browser.

2. Electronic Signature builds an SAML Authentication Request message and sends it to the IdP.



3. The IdP receives the request and checks if there is an active session for the user.

4. If no session for this user exists on the IdP, the user is prompted to enter their credentials.

5. The IdP analyzes the credentials and sends an SAML Response message, asserting that the user is authenticated.

6. The browser is redirected to the initially requested UI page.

User authentication use casesFollowing are some common use cases:

l When attempting to log on to Electronic Signature, the user is redirected to the IdP login page. The user must be defined in the IdP and validated by the IdP.

l The same user must also be defined in Electronic Signature, with the appropriate roles defined. The roles defined here determines the user's authorized access as usual.

l When a new user is defined in the Electronic Signature UI, no email notification is sent to the user to set their own password.

l When a user is updated in the Electronic Signature UI, the password update button is disabled: the user cannot change the password, which is managed centrally under the IdP.

l If a user is defined in the IdP but not in Electronic Signature, then an error message is displayed. The Administrator must then log in to the IdP/ Electronic Signature and create the user. The user will then be able to access Electronic Signature.

l If the user exists in Electronic Signature, but has no adequate roles defined, then a grayed panel is displayed. No further access is allowed. The Administrator must log in to update the user's profile.

Logout sequenceThis section describes two logout sequences:

l Logout initiated by Electronic Signature

l Logout initiated by the IdP

Logout initiated by Electronic SignatureWhen a user clicks the logout button in the Electronic Signature UI, a logout request is sent to IdP, and the used resources are freed.

On logout, if logoutRedirectUri= is coded in the SSO configuration file (sso-service-provider.xml) and the corresponding HTML page is displayed. Otherwise the IdP login page is displayed.

Important: The user must always end a session by clicking the logout button. If this is not done, some session resources are not freed and memory leakage might occur.



Logout initiated by the Identity ProviderElectronic Signature can also react to a logout requested by the IdP.

1. The IdP sends an SAML Logout Request to log out a user.

2. The browser sends the SAML Logout Request to Electronic Signature.

3. Electronic Signature removes the user session and sends an SAML Logout Response.

4. The browser sends the SAML Logout Response to the IdP.

SAML SSO configuration

PrerequisitesA third-party SAML 2.0 compliant Identity Provider (IdP) must be installed, configured for TLS connection, and running. For information about how to install, configure and run the IdP, refer to the official IdP documentation.

The following file must also be made available to the Service Provider (SP), in this case Electronic Signature:

l The IdP metadata.xml (to be used later in Electronic Signature's SP configuration file)

Configure SAML SSOThe following files are related to SAML SSO in Electronic Signature:

l configuration.properties: Electronic Signature global configuration file.

l sso-service-provider.xml: SSO service provider configuration file

l IdP metadata file: This file is exported from the IdP. The file is used in the Electronic Signature SP configuration file

l SP metadata file: This file is exported from the Electronic Signature SP. It needs to be imported in the IdP

configuration.propertiesThe configuration.properties file includes two new parameters for SSO:

l server.useCommonSSO=false | true

l commonSSO.config=data/conf/sso-service-provider.xml



To activate SAML SSO, edit the configuration.properties file and set:

server.useCommonSSO=true

commonSSO.config=data/conf/sso-service-provider.xml

For further detail on this file, refer to configuration.properties file on page 114

sso-service-provider.xmlA sample SSO SP configuration file is provided in <Electronic Signature install dir>/data/conf/sso-service-provider.xml.

This SP configuration file is used by the SSO agent. It is referenced in the configuration.properties file by the property commonSSO.config=data/conf/sso-service-provider.xml.

This configuration file is provided to help you start up quickly and easily. It defines a simple use case, a single SP, and a single IdP.

Sample SSO SP configuration file provided with Electronic Signature:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<!—

Sample SSO-service-provider.xml

The following items MUST be specified as is

- trustStoreInitializer=

"com.axway.esign.app.java.core.security.sso.SSOTrustStoreInitializer"

- useAppSessions="true"

- filterUri="/*"

- logoutUri="/logout"

- keystoreInitializer=

"com.axway.esign.app.java.core.security.sso.SSOKeyStoreInitializer"

The following items should be customized to meet your requirements

- entityId= (in ServiceProvider, Electronic Signature’s SAML entity ID)

- keyAlias=electronicsignaturesecured

- entityId= (in SamlIdentityProvider, IdP’s SAML entity ID)

- metadataUrl= (IdP metadata xml file)

All other items can stay as is, or you can adapt them to meet your

installation’s requirements.

-->

<SSOConfiguration>

<CertificateValidation



pathValidation="false"

trustStoreInitializer=

"com.axway.esign.app.java.core.security.sso.SSOTrustStoreInitializer" />

<ServiceProvider

entityId="http://www.example.com/esign/sso-sp"

useAppSessions="true"

filteredUri="/*"

logoutUri="/logout"

keyAlias="electronicsignaturesecured"

keystoreInitializer=

"com.axway.esign.app.java.core.security.sso.SSOKeyStoreInitializer"

>

<AssertionConsumerService

binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

location="/saml2/sso/post"/>

<AssertionConsumerService

binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"

location="/saml2/sso/redirect"/>

<SingleLogoutService

binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"

location="/saml2/slo/post"/>

<SingleLogoutService

binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect"

location="/saml2/slo/redirect"/>

<Features>

<Feature key="saml-metadata-endpoint-enabled" value="true"/>

<Feature key="saml-metadata-uri" value="/saml/metadata"/>

</Features>

</ServiceProvider>

<IdentityProviders>

<SamlIdentityProvider

entityId="https://localhost:8443/auth/realms/Axway"

metadataUrl="sso-idp-metadata.xml"

verifyAssertionExpiration="true"

sign="true">

<Features>

<Feature key="saml-allow-http-connection" value="false"/>

<Feature key="saml-verify-metadata-signature" value="false"/>

<Feature key="saml-allow-unsigned-assertion" value="false"/>

</Features>

</SamlIdentityProvider>

</IdentityProviders>

</SSOConfiguration>



Configure sso-service-provider.xml for Electronic SignatureEdit the sso-service-provider.xml file as follows:

1. Do not change the following parameters (leave the values defined in the sample file):

l useAppSessions="true"

l filterUri="/*"

l logoutUri="/logout"

l trustStoreInitializer="com.axway.esign.app.java.core.security.sso.SSOTrustStoreInitializer"

l keyAlias="electronicsignaturesecured"

l keystoreInitializer="com.axway.esign.app.java.core.security.sso.SSOKeyStoreInitializer"

2. Change the following according to your IdP configuration:

l entityId=<your service provider entityId> (in <ServiceProvider> section)

l entityId=<your IDP entityId> (in <IdentityProviders> section)

l metadataUrl=<your IDP metadata xml> (exported from your IDP)

This metadata file must be stored at this location: <electronic.signature.home>/data/conf/

For details of how to export IdP metadata, refer to your IdP documentation.

3. You can customize all other parameters according to your needs.

However, it is recommended to keep the default values for the following security parameters:

l secure-cookie=true

l sign=true

l saml-allow-http-connection=false

l saml-allow-unsigned-assertion=false

l saml-verify-metadata-signature=false (*)

l saml-signature-algorithm=rsa-sha256

* The recommended value for saml-verify-metadata-signature is true. However, this requires the IDP to sign their metadata, which is not always the case. In the sample provided with Electronic Signature you will find saml-verify-metadata-signature = false. This works with all received IDP metadata, whether it is signed or not.



Service Provider metadataYou must also export the SSO service provider metadata.xml file from Electronic Signature and import it to your IdP.

To export the SP metadata from Electronic Signature:

1. Start Electronic Signature by running esstart.sh (or esstart.bat on Windows).

2. Open a browser, and type:https://<Electronic Signature hostname>:9090/ui/saml/metadata

The metadata.xml file is downloaded to your browser's download folder.

3. Go to your IdP installation, and import the SP's metadata.xml. For details of how to import an SP metadata.xml file, refer to the IdP documentation.

SAML SSO post-configuration tasksAfter Electronic Signature has been installed and configured, you need to define all Electronic Signature user accounts in the IdP.

The procedure to follow depends on whether this is a new installation of Electronic Signature or a migration from an existing Electronic Signature installation.

New Electronic Signature installationFor a new Electronic Signature installation, a default user "admin", with password "Secret1", is created in the Electronic Signature local database. This is an administrator account with all authorized access in Electronic Signature.

1. In the IdP, define this "admin" user and assign a new password. This enables you to log in to Electronic Signature with "admin" to create all others user accounts with appropriate access privileges.

When you use SAML SSO, user authentication is delegated to the IdP, so the initial user password created in the Electronic Signature local database is ignored. The password defined in the IdP will be used during the login process.

2. In the IdP, create all other user accounts that can access Electronic Signature.

Migration from existing Electronic Signature installationIn the IdP, define all user accounts that already exist in Electronic Signature. The user passwords can be the same or different.



SAML SSO troubleshooting

Cannot access my application even after a successful loginVerify that there are no errors in the Electronic Signature log file due to a misconfiguration.

Make sure you are accessing Electronic Signature using the same hostname or IP address as the one specified in the Electronic Signature metadata XML file that you exported and that is used by the Identity Provider:

l Do not use localhost because some browsers cannot create cookies for this hostname.

l Do not mix hostname and IP address. Because cookies are linked to the string used in the URL for the host, there is no IP address resolution.

After I login to the Identity Provider page I am not redirected to the application pageVerify that the Identity Provider and Service Provider (Electronic Signature) system clocks are synchronized.


Appendix A: configuration.properties file

The tables in this appendix describe the parameters included in the configuration.properties file.

The Electronic Signature server configuration.properties file is located in <Electronic Signature install dir>/data/conf.

Some new parameters may have been added since the publication of this documentation. All parameters are commented inside the configuration file.

Electronic Signature:

l Electronic Signature configuration section on page 115

l Database configuration section on page 118

l UI configuration section on page 118

l Parser configuration section on page 119

l Payment details section on page 119

l Email configuration section on page 119

l Transporter configuration section on page 121

l Interchange configuration section on page 121

l PSR scanning configuration section on page 122

l Common SSO configuration section on page 123

l PassPort configuration section on page 123

l Sentinel configuration section on page 125

l Sizing configuration section on page 126

l Exit configuration section on page 126

l Cipher Key Configuration on page 127

l Configuration for accepted file system paths on page 128

EBICS Client:

l Configuration of the signature protocols section on page 129

l Configuration of order type counter section on page 129

l Configuration of scanning file system section on page 129

l Network configuration section on page 131



Electronic SignatureThe following sections of the configuration.properties file control Electronic Signature.

Electronic Signature configuration sectionThis section contains all processing directories, network configuration and general internal configuration such as usage of Sentinel or PassPort.


server.isOverride Specifies whether the server address and port should be overwritten. If the value is set to true, the address of the server will be different from the address used to send emails.New values will be server.newDomain and server.newPort.Default value is false

false

server.keystore.certificate.encryptedPassword

Encrypted password of the keystore certificate

server.keystore.encryptedPassword

Encrypted password of the SSL keystore

server.keystore.file Keystore containing certificate and private key for SSL connection

data/conf/esign.keystore

server.newDomain New domain name of the server. This value is used in emails sent by Electronic Signature

server.newPort New TCP port of the server. This value is used in emails sent by Electronic Signature

9090

server.port TLS port of the server UI 9090




server.readMaxIdleTime Maximum read idle time in milliseconds, which is the maximum time allowed before the connection shows any sign of progress

60000 [milliseconds]

server.ssl.disableRenegociation Enable or disable renegotiation in SSL. Default value is false

false

server.ssl.supportedCipherSuites Defines the supported cipher suites for the Server UI

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 TLS connections to the server UI are restricted to TLSv1.2 by default. If you want to relax this restriction, add the desired protocols separated by a comma. For example: TLSv1,TLSv1.1,TLSv1.2

TLSv1.2

server.sso.keystore.encryptedPassword

Encrypted passwords of the keystore

server.sso.keystore.path Keystore holding the private key for mutual SSL authentication to secure connection between Electronic Signature and PassPort in SSO mode

data/conf/passport/es_sso.jks

server.sso.keystore.type Type of keystore JKS




server.sso.port SSO port of the server. Used only with PassPort and the SSO option. Defines the port where users can connect in SSO

9091

server.sso.truststore.path Path to the truststore where SSL certificate of PassPort is used in SSO mode

data/conf/passport/passport_truststore.jks

server.truststore.file Path of the truststore used for TLS connection with the DB

Default value: data/conf/esign.truststore

server.truststore.password For TLS connection with the DB.Optional password for the truststore

server.useCommonSSO Activate the use of Commons SSONote: The use of Common SSO and PassPort are mutually exclusive

false

server.usePassPort Activate the use of PassPort

false

server.usePassPortSSO Activate the use of SSO with PassPort

false

server.useSentinel Activate the use of Sentinel

false



Database configuration sectionThis section contains pre-configuration information for the database. For example, to use MySQL you just have to uncomment the MySQL part and comment all others. However, you must specify the user, password, URL for the database and other specific customer system information.


jdbc.ConnectionProperties –

jdbc.DataCache – true

jdbc.DBDictionary – oracle(ConstraintNameMode=before,UseTriggersForAutoAssign=true,AutoAssignSequenceName=FEX_ES_SEQ)

jdbc.driver.className – oracle.jdbc.OracleDriver

jdbc.encryptedPassword –

jdbc.log – log4j

jdbc.RemoteCommitProvider – sjvm

jdbc.url –

jdbc.username –

UI configuration sectionThis section contains information relating to the Electronic Signature UI.


ui.session.expiration The time in minutes when the UI session will expire in case of inactivity

5



Parser configuration sectionThis section enables you to add external parsers in order to support additional file formats.


external.classpath Additional classpath for external dependencies. Separate jar names with a semi-colon (;)

file:jars/dependency1.jar;

file:jars/dependency2.jar

payLoad.parser.class.1 The parser class contained in the JAR file

com.axway.esign.app.java.core.samples.parser.ParserSample

payLoad.parser.name.1 Custom parsers you want to integrate with Electronic Signature

Sample Parser

Payment details sectionThis section enables you to change properties of the payment details storage.


payment.details.number.of.partitions

On Oracle, a unique set of partitioned tables is used for all payments. This value controls the number of partitions available

250

Email configuration sectionThis section contains information for the email sending service. This service will send an email to all concerned users every time a new payment has been taken into account by the server.


email.admin.enabled This option controls whether administrators receive email when new payments do not match any rule

true




email.general.senderAddress email address to display for the sent email

[email protected]

email.new_payment_message.template

Path of the new payment email template properties file

data/conf/templates/fr_FR/email_new_payment.template

email.new_passport_user_message.template

Path of the new user email template properties file, for PassPort mode

data/conf/templates/fr_FR/email_new_passport_user.template

email.new_payment_without_users_message.template

Path of the new payment without users email template properties file

data/conf/templates/fr_FR/email_new_payment_without_users.template

email.new_user_message.template

Path of the new user email template properties file

data/conf/templates/fr_FR/email_new_user.template

email.password_reset_message.template

Path of the user reset password email template properties file

data/conf/templates/fr_FR/email_password_reset.template

email.smtp.host.port SMTP server TCP port number 85

email.smtp.host.server SMTP server host name 58

email.smtp.user.encryptedPassword

Password if required - depending on SMTP server

email.smtp.user.login Login if required - depending on SMTP server

36

email.user.enabled This option controls whether Signers/Validators receive email when new payments are available

false



Transporter configuration sectionParameter Description Example

paymentImporter.detailParsingOnArrivalEnabled

This option enables you to disable payment detail parsing upon payment import. Default is enabled.Warning: Do not disable this if you use rule with "1 or 2 signature depending on a threshold"

true

paymentImporter.paymentIndex.directory

Folder where payment details are stored.This folder needs lots of space to store all payment details. For example, a payment of 70 000 records requires 30 MB.To purge this folder, use the purge command

data/paymentIndex

paymentImporter.pollingFrequency

Frequency of payments scanner


paymentOrderIdImporter.pollingFrequency

Frequency of order ID scanner for sent payments


paymentScheduler.pollingFrequency

Frequency of retries on payment to resubmit in case of errors


transporter.connector Transporter used for importing payments (Interchange or Gateway)

gateway

Interchange configuration sectionThis section contains information so that Electronic Signature can connect to Interchange to retrieve payments.


interchange.encryptedPassword Password (encrypted) of Interchange user




interchange.sessionRenewal Time in minutes when the web service session will be renewed. Must be less than the session expiration time

10 [minutes]

interchange.transitionTimeOverlap

Overlap time used for requesting payments to Interchange.The value is in milliseconds

interchange.url Interchange HTTP URL to connect to the web service

http://localhost:6080

interchange.user Login of Interchange user admin

PSR scanning configuration sectionThis section contains information about downloading and storing PSR.


psr.done.directory Processed directory data/psr/done

psr.error.directory Error directory data/psr/errors

psr.monitoring.directory Incoming directory for PSR files

data/psr/incoming

psr.processing.directory Processing directory for PSR files

data/psr/processing

psr.purge.expirationDays Expiration time of PSR records 30 [days]

psr.queue.size Size of the PSR parsing queue 10

psr.scan.interval Scan interval of the incoming directory

10 [seconds]

psr.thread.pool.size Size of the thread pool used for PSR parsing

10



Common SSO configuration sectionParameter Description Example

commonSSO.config Path of the service provider configuration file

data/conf/sso-service-provider.xml

PassPort configuration sectionThis section contains information for the PassPort connection such as host name, port number or TLS data.


passport.api.certificateRequestID.path

Path to Electronic Signature PassPort certificate request ID

data/conf/passport/passport_csr.id

passport.api.keystore.password

Keystore password

passport.api.keystore.path Path for Electronic Signature PassPort API certificate

data/conf/passport/passport_es_keystore.jks

passport.api.shared.secret PassPort shared secret (set by the Configuration tool)

passport.api.tmp.private.key.path

Path to Electronic Signature PassPort private key

data/conf/passport/passport_es_pkey.p8

passport.component.version Electronic Signature version (must match CSD)

2.6.1

passport.csd.path Path to the Electronic Signature PassPort CSD

data/conf/passport/es_csd.xml

passport.es.key.alias Key alias to use for Electronic Signature PassPort certificate

ES certificate

passport.instance.id Electronic Signature PassPort Instance ID

default




passport.locale.forced Forced locale. For SSO mode only. If this is set, Electronic Signature does not read or set user preferences for locales. This is useful when using external user store, as PassPort does not provide exit APIs for preferences. Supported locales are: en_US and fr_FR

passport.server.address PassPort server address localhost

passport.server.port PassPort TLS connection port 6453

passport.supported.tls.version

The PassPort connection is restricted to TLSv1.2 by default. If you want to relax this restriction, add the desired protocols separated by a comma. For example: TLSv1,TLSv1.1,TLSv1.2

TLSv1.2

passport.truststore.path Path to PassPort Truststore (to be changed if PassPort SSL server certificate changes)

data/conf/passport/passport_truststore.jks

passport.user.cacheTimeout

Time when the local users cache will be flushed

5 [minutes]

passport.user.useCache Enable or disable a local cache for retrieving users from PassPort

false

For information about renewing certificates, see Renew PassPort certificates on page 101.



Sentinel configuration sectionThis section contains information for the connection with Sentinel.


sentinel.overFlowFile.path Overflow file path to be used by Sentinel

sentinel.overFlowFile.size Overflow file size in MB

sentinel.server.address Host name of the Sentinel server

sentinel.server.port TCP port of the Sentinel server (HTTP/QLT server tracker for XNTF/XML data type)

sentinel.supported.tls.version If you want to relax this restriction, replace the TLSv1.2 default value and set the TLS version you need. The possible values are: SSL, SSLv2, SSLv3, TLS, TLSv1, TLSv1.2

TLSv1.2

sentinel.tls.connection.enabled establish a secured connection (TLS) between Electronic Signatureand Sentinel

false

sentinel.trackedObjectName Sentinel object to be tracked XFBTransfer

sentinel.trackedObjectVersion Sentinel object version to be tracked

3.9



Sizing configuration sectionThis section contains information related to the sizing of the internal queue or thread pools. These values have a direct impact on performance.


cache.size.paymentDetail Size of the payment detail cache. This cache is used to keep in memory some payment details instead of reading them from paymentImporter.paymentIndex.directory locationn

30 [number of payment files]

pool.parsers.size Number of payment files that can be processed in parallel to create payment details

5

Exit configuration sectionParameter Description Example

exit.pollingFrequency Frequency of exit scanner 60000 [milliseconds]

exit.reject.classname Name of the implementation class of the reject exit

exit.reject.classpath Classpath with all the dependencies of the reject exit.All jars must be separated by ; example: file:program/lib/signExit.jar;file:program/lib/dependency1.jar

exit.reject.thread.pool.size Size of the thread pool used for reject exit processing

2

exit.sign.classname Name of the implementation class of the sign exit.All jars must be separated by ; example : file:program/lib/signExit.jar;file:program/lib/dependency1.jar




exit.sign.classpath Classpath with all the dependencies of the sign exit. All jars must be separated by ; example : file:program/lib/signExit.jar;file:program/lib/dependency1.jar

exit.sign.thread.pool.size Size of the thread pool used for sign exit processing

5

exit.useReject Activate the reject exit post-processing

false

exit.useSign Activate the sign exit post-processing

false

Cipher Key ConfigurationParameter Description Example

cipher.key.directory Directory that contains the cipher key



Configuration for accepted file system pathsParameter Description Example

payload.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 2.10.0, 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 2.9.2 or if you are using Gateway as transporter.

data/mft/files

mft.directory 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.

program/mft

trace.directory 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/tmp



EBICS ClientThe following sections of the configuration.properties file control the embedded EBICS Client.

Configuration of the signature protocols sectionParameter Description Example

ebics.signatureList Allowed signature protocols. Comma-separated list, spaces not allowed.

Supported signature protocols:

l A005:CERTIFICATE

l A006:CERTIFICATE

l A004:KEYPAIR

l A005:KEYPAIR

l A006:KEYPAIR

A005:CERTIFICATE, A006:KEYPAIR

Configuration of order type counter sectionParameter Description Example

send.uniqueCounter Configuration of order type counter

false

Configuration of scanning file system sectionParameter Description Example

done.directory XML send files are moved to this directory in case of success

data/working/done

error.directory XML sent files are moved to that directory in case of error

data/working/error




fetch.queue.size Internal queue depth for fetch requests

10

fetch.thread.pool.size Size of the thread pool used for fetch operation

10

incoming.directory XML request are to be stored inside this directory

data/working/incoming

incoming.queue.size Internal queue depth for incoming requests

10

incoming.scan.interval Scan interval of the incoming directory

10 [seconds]

initialization.letters.dir Directory for initialization letters

data/iniLetter

processing.directory XML request are moved inside this directory while the transfer is ongoing

data/working/processing

send.queue.size Internal queue depth for send requests

10

send.retries Number of retries for send: when the EBICS error "order id already exists" is detected, several retries will be attempted

10

send.thread.pool.size Size of the thread pool used for send operation

10

signatureWaiting.directory XML send files are moved to this directory when a signature is needed from Electronic Signature

data/working/signatureWaiting



Network configuration sectionParameter Description Example

command.line.port Command line tcp port 7091

conf.allowAllCerts Allow all server SSL certificates. This should only be used for testing

false

conf.enable.secureRelay.proxy

Use Secure Relay for DMZ proxying

false

conf.httpConnection.connectionTimeout

Timeout value until the HTTP connection is established. Can be any value not equal to 0


conf.httpConnection.soTimeout

Socket timeout 60000 [milliseconds]

conf.httpConnection.tcpNoDelay

Determines whether Nagle's algorithm is to be used or not

true

conf.secureRelay.path Secure Relay configuration location

data/conf/secureRelayConf.xml

conf.supportedCipherSuites

Supported cipher suites for the HTTPS connection used for EBICS outbound communications. Comma-separated list, spaces not allowed.For information about modifying the TLS settings, see Modify outbound Electronic Signature TLS configuration on page 25

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 Supported TLS/SSL protocols for the HTTPS connection used for EBICS outbound communications. Comma-separated list, spaces not allowed.The supported values available depends on the java version:

l SSLv3,TLSv1 (java 6)

l SSLv3,TLSv1,TLSv1.1,TLSv1.2 (java 7)

l TLSv1,TLSv1.1,TLSv1.2 (java 8)

TLSv1.2


Appendix B: Directory structure

After you have installed Electronic Signature, some or all of the following directories are deployed on the system. You can access these directories in <Electronic Signature install dir>.

.install4j Files used by the installer and the Configuration tool

data bin Configuration script for integration with Gateway and Sentinel

cert Secure Relay certificates and the Server TLS certificates

conf Configuration files

log Log files

mft files Data files transferred

tmp Script execution logs and temporary files

iniLetter PDF initialization letters generated during the initialization step

psr errors Payment status requests detected as erroneous

done Payment status requests finished successfully

processing Ongoing parsing of the payment status requests

incoming Awaiting payment status requests. Should normally never be cleaned-up

working errors EBICS Requests detected as erroneous

done EBICS Requests finished successfully

processing Ongoing EBICS requests processed by the EBICS Client

incoming Awaiting EBICS Request. Should normally never be cleaned-up.


Appendix B: Directory structure

jre Java Runtime Environment

program ui UI application

bin service Windows Service Mode script

devKit exit Sample code for custom rowspan="3">development

inline

parser

lib Electronic Signature jar files

mft Send Script between EBICS Client and Gateway for Send transfers

Fetch Script between EBICS Client and Gateway for Fetch transfers

install/client Gateway and Transfer CFT settings (object creation)

install/samples Back-end sample command lines

install/files Backup for files before send


Appendix C: secureRelayConf reference

This section gives an overview of the advanced configuration parameters for Secure Relay.

Master AgentParameter Description

CACertificate Path to a PEM file containing the certificate for the authority authenticating the certificate received from the Router Agent for both HC (Hot Channel) and multiplexed connections. If omitted, the agent cannot start.

UserCertificate Path to a P12 file containing the certificate presented by the Master Agent to the Router Agent during authentication for both HC and multiplexed connections. If omitted, the agent cannot start.

Password Password for accessing the UserCertificate in encrypted form.

AuthorizedCallPortsRangeForHC Range of ports into which the socket used for establishing hot channels connections can be bound. If no value is given, the system will choose ports between all available on the system. If omitted, it is replaced (without warning) by its default value.

AuthorizedCallPortsRangeForComm Range of ports into which the socket used for establishing multiplexed connections can be bound. If no value is given, the system will choose ports between all available on the system. If omitted, it is replaced (without warning) by its default value.


Appendix C: secureRelayConf reference

Router AgentParameter Description

Id Router Agent identifier used as a reference to the agent when setting up a SAP on the Router Agent. The identifier must be unique among Router Agents, otherwise the Router Agent definition is ignored.

ListenAddress Network address of the Router Agent

AdminPort Router Agent connection port to use for administrative exchanges with the Master Agent.Default = 6810

CommPort Router Agent connection port to use for file exchanges with the Master Agent.Default = 6811

NbDataConnections Specifies the number of simultaneous connections that can be created between the Master Agent and the Router Agent.Integer: 1 - 100Default = 1

DataChannelCiphering Specifies whether to cipher the Communication channels between this Router Agent and the Master Agent in TLS.Default = 1 (ciphered)This internal ciphering is completely independent of whether the transported data is ciphered or not.

OutcallNetworkInterface Network interface used for outgoing data connection in client mode.

OutcallDataPortsRange Port range for outgoing data connections in client mode.


Documents

Electronic Signature Administrator Guide