electronic signature administrator guide
TRANSCRIPT
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
AxwayElectronic Signature 2.10.0 Administrator Guide 4
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
AxwayElectronic Signature 2.10.0 Administrator Guide 5
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
AxwayElectronic Signature 2.10.0 Administrator Guide 6
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
AxwayElectronic Signature 2.10.0 Administrator Guide 7
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 8
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
AxwayElectronic Signature 2.10.0 Administrator Guide 9
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 10
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 11
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 12
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 13
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 14
2 Configure Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 15
2 Configure Electronic Signature
Field Description
HTTP Port Port for the GUI
Control Port Local port for the command line
SMTP Hostname SMTP server host name
SMTP Port SMTP server port number
SMTP User Optional login for the SMTP Server
SMTP Password Password of the user login for the SMTP Server
SMTP Sender The application uses this account to send 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
AxwayElectronic Signature 2.10.0 Administrator Guide 16
2 Configure Electronic Signature
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
AxwayElectronic Signature 2.10.0 Administrator Guide 17
2 Configure Electronic Signature
Field Description
If you selected the Use custom URL option:
l Custom URL Database custom URL
l Connection User Database connection user
l Connection Password Database connection password
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
l Connection User Database connection user
l Connection Password Database connection password
Access manager settings 1. Select PassPort, Electronic Signature or Common SSO as access manager.
2. If you selected PassPort, specify the PassPort AM connection parameters:
Field Description
Hostname PassPort hostname
Main SSL/TLS Port PassPort secured port
Shared Secret Shared secret password defined during PassPort installation
Product Instance Electronic Signature instance name in PassPort
PassPort API Keystore Password
Password that protects the auto-generated keystore
AxwayElectronic Signature 2.10.0 Administrator Guide 18
2 Configure Electronic Signature
Field Description
Use SSO Select this check box if you want to activate the SSO (Single Sign On) mode
Product SSO Port PassPort SSO Agent port
SSO KeystorePassword Password that protects the SSO keystore
Transporter configuration 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
AxwayElectronic Signature 2.10.0 Administrator Guide 19
2 Configure Electronic Signature
Field Description
Enable TLS with Sentinel
Select this check box to enable TLS with Sentinel
Sentinel Hostname Enter a Sentinel hostname
Sentinel Port Enter a Sentinel port number
Sentinel Overflow Directory Path
Enter a Sentinel overflow directory path
Sentinel Overflow File Size in MB
Enter a Sentinel overflow file size in MB
Sentinel Universal Agent Directory
Enter a Sentinel Universal Agent directory
Secure Relay 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.
AxwayElectronic Signature 2.10.0 Administrator Guide 20
2 Configure Electronic Signature
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
AxwayElectronic Signature 2.10.0 Administrator Guide 21
2 Configure Electronic Signature
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:
AxwayElectronic Signature 2.10.0 Administrator Guide 22
2 Configure Electronic Signature
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:
AxwayElectronic Signature 2.10.0 Administrator Guide 23
2 Configure Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 24
2 Configure Electronic Signature
By default, the following cipher suites are supported:
l TLS_RSA_WITH_AES_256_CBC_SHA256
l TLS_RSA_WITH_AES_128_CBC_SHA256
l TLS_RSA_WITH_AES_256_CBC_SHA
l TLS_RSA_WITH_AES_128_CBC_SHA
You can remove or add cipher suite items as required. Use a comma to separate multiple values but do not include a space before or after the comma.
Modify outbound Electronic Signature TLS 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:
AxwayElectronic Signature 2.10.0 Administrator Guide 25
2 Configure Electronic Signature
l TLS_RSA_WITH_AES_256_CBC_SHA256
l TLS_RSA_WITH_AES_128_CBC_SHA256
l TLS_RSA_WITH_AES_256_CBC_SHA
l TLS_RSA_WITH_AES_128_CBC_SHA
You can remove or add cipher suite items as required. Use a comma to separate multiple values but do not include a space before or after the comma.
Secure database connection with 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
AxwayElectronic Signature 2.10.0 Administrator Guide 26
2 Configure Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 27
2 Configure Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 28
2 Configure Electronic Signature
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
AxwayElectronic Signature 2.10.0 Administrator Guide 29
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 30
3 Use Electronic Signature with Interchange
7. Set up an integration delivery exchange for routing received messages to integration. Delivery exchange for routing received messages to integration corresponds to the way to retrieve messages fetched in EBICS. Those files must go to the back-end (Integrator for example).
8. Set up a pickup/delivery exchange. In order to communicate with a bank using EBICS, the message protocol must be set to EBICS.
9. Configure inline processing. See Inline processing for Interchange / Electronic Signature integration on page 33. Note that this step is important for integration with Electronic Signature.
10. Create a partner for the community. The partner corresponds to the EBICS Bank that you want to exchange with. The Routing ID corresponds to the EBICS HostId of the remote Bank.
11. Set up EBICS communication between the community and the partner:
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">
AxwayElectronic Signature 2.10.0 Administrator Guide 31
3 Use Electronic Signature with Interchange
<Metadata name="From" type="string">CUSTOMER</Metadata>
<Metadata name="To" type="string">BANK</Metadata>
<Metadata name="message.waitUpdate" type="string">true</Metadata>
<Metadata name="ebics.action" type="string">send</Metadata>
<Metadata name="ebics.orderType"
type="string">FUL.pain.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).
AxwayElectronic Signature 2.10.0 Administrator Guide 32
3 Use Electronic Signature with Interchange
l Payload id is the id of the payload, this parameter is mandatory
l Location type is the location and type of payload
Fetch
<?xml version="1.0" encoding="UTF-8"?>
<MessageMetadataDocument documentId="Test_B2" protocol="generic">
<Metadata name="From" type="string">CUSTOMER</Metadata>
<Metadata name="To" type="string">BANK</Metadata>
<Metadata name="ebics.action" type="string">fetch</Metadata>
<Metadata name="ebics.orderType"
type="string">FDL.camt.002.001.02.ara</Metadata>
<Metadata name="ebics.user.userId" type="string">USER</Metadata>
</MessageMetadataDocument>
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).
AxwayElectronic Signature 2.10.0 Administrator Guide 33
3 Use Electronic Signature with Interchange
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 34
3 Use Electronic Signature with Interchange
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).
AxwayElectronic Signature 2.10.0 Administrator Guide 35
3 Use Electronic Signature with Interchange
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 36
3 Use Electronic Signature with Interchange
3. Copy the newly-generated jar file into the Interchange jars folder: <Interchange install dir>/jars.
Update payment status with 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.
AxwayElectronic Signature 2.10.0 Administrator Guide 37
3 Use Electronic Signature with Interchange
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:
<?xml version="1.0" encoding="UTF-8"?>
<MessageMetadataDocument documentId="Test_B2"
protocol="generic">
<Metadata name="From" type="string">CUSTOMER</Metadata>
<Metadata name="To" type="string">BANK</Metadata>
<Metadata name="ebics.action" type="string">fetch</Metadata>
<Metadata name="ebics.orderType"
type="string">FDL.camt.002.001.02.ara</Metadata>
<Metadata name="ebics.user.userId"
type="string">USER</Metadata>
</MessageMetadataDocument>
3. Change the BANK/CUSTOMER/USER as required.
AxwayElectronic Signature 2.10.0 Administrator Guide 38
3 Use Electronic Signature with Interchange
The value of the metadata ebics.user.userId corresponds to the transport user used for fetching the PSR. If the Bank has defined the PSR handler as user-based then the transport user used for sending payments must be specified. If no transport user has been explicitly defined, then the first signer is used as a transport user and this user must be specified in the fetch XML file.
Configure Interchange integration 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.
AxwayElectronic Signature 2.10.0 Administrator Guide 39
3 Use Electronic Signature with Interchange
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 40
3 Use Electronic Signature with Interchange
Integrate Sentinel with Electronic Signature and Interchange
This section explains how to configure Electronic Signature to send events to Sentinel.
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 41
3 Use Electronic Signature with Interchange
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)
ü ü
AxwayElectronic Signature 2.10.0 Administrator Guide 42
3 Use Electronic Signature with Interchange
Attribute name Description
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
ü ü ü ü ü
AxwayElectronic Signature 2.10.0 Administrator Guide 43
3 Use Electronic Signature with Interchange
Attribute name Description
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
AxwayElectronic Signature 2.10.0 Administrator Guide 44
3 Use Electronic Signature with Interchange
Attribute name Description
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
ü ü ü ü
AxwayElectronic Signature 2.10.0 Administrator Guide 45
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 46
4 Use Electronic Signature with Gateway
Use Transfer CFT to connect to the back-end application
The installation package includes a set of sample files that enable you to link Gateway and Electronic Signature to Transfer CFT to connect to the back-end application.
The sample files that are provided in the installation package enable you to:
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 47
4 Use Electronic Signature with Gateway
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
AxwayElectronic Signature 2.10.0 Administrator Guide 48
4 Use Electronic Signature with Gateway
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].
AxwayElectronic Signature 2.10.0 Administrator Guide 49
4 Use Electronic Signature with Gateway
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
AxwayElectronic Signature 2.10.0 Administrator Guide 50
4 Use Electronic Signature with Gateway
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:
AxwayElectronic Signature 2.10.0 Administrator Guide 51
4 Use Electronic Signature with Gateway
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 52
4 Use Electronic Signature with Gateway
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 53
4 Use Electronic Signature with Gateway
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 54
4 Use Electronic Signature with Gateway
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 55
4 Use Electronic Signature with Gateway
Integrate Sentinel with Electronic Signature and Gateway
This section explains how to configure Electronic Signature to send events to Sentinel.
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 56
4 Use Electronic Signature with Gateway
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.
Attribute name Description
CREATIONDATE Event creation date (dd/mm/yyyy)
ü ü ü
CREATIONTIME Event creation time (hh:mm:ss)
ü ü ü
CYCLEID CycleID of EBICS transfer
ü ü ü ü ü ü ü
AxwayElectronic Signature 2.10.0 Administrator Guide 57
4 Use Electronic Signature with Gateway
Attribute name Description
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)
ü ü ü ü
AxwayElectronic Signature 2.10.0 Administrator Guide 58
4 Use Electronic Signature with Gateway
Attribute name Description
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)
ü ü ü ü ü
AxwayElectronic Signature 2.10.0 Administrator Guide 59
4 Use Electronic Signature with Gateway
Attribute name Description
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)
ü ü ü ü ü ü
AxwayElectronic Signature 2.10.0 Administrator Guide 60
4 Use Electronic Signature with Gateway
Attribute name Description
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.
Parameter Description Example
GTW_HOME mandatoryPath to the Gateway installation directory
c:\Axway\Gateway
AxwayElectronic Signature 2.10.0 Administrator Guide 61
4 Use Electronic Signature with Gateway
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 62
4 Use Electronic Signature with Gateway
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>
AxwayElectronic Signature 2.10.0 Administrator Guide 63
4 Use Electronic Signature with Gateway
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,
signatureVersionB:CredentialTypeB>]
Update customer -a updateCustomer -bn <bankName> -cid <customerId> [-on <orderNumber>] [-d <true/false>] [-sigalg <signatureVersionA:CredentialTypeA,
signatureVersionB:CredentialTypeB>]
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>
AxwayElectronic Signature 2.10.0 Administrator Guide 64
4 Use Electronic Signature with Gateway
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
<encryptionCertificate>] [-ep
<encryptionPassword>] [-ac
<authenticateCertificate>] [-ap
<authenticatePassword>] [-r
<numberOfRetries>]
Send signature key to a user
-a ini -bn <bankName> -cid <customerId> -
uid <userId> [-on <orderNumber>] [-sc
<signatureCertificate>] [-sp
<signaturePassword>] [-r <numberOfRetries>]
AxwayElectronic Signature 2.10.0 Administrator Guide 65
4 Use Electronic Signature with Gateway
Action Command
Send authentication and encryption keys to a user
-a hia -bn <bankName> -cid <customerId> -
uid <userId> [-on <orderNumber>] [-ec
<encryptionCertificate>] [-ep
<encryptionPassword>] [-ac
<authenticateCertificate>] [-ap
<authenticatePassword>] [-r
<numberOfRetries>]
Initialize a user with H3K -a h3k -bn <bankName> -cid <customerId> -
uid <userId> [-sc <signatureCertificate>]
[-sp <signaturePassword>] [-ec
<encryptionCertificate>] [-ep
<encryptionPassword>] [-ac
<authenticateCertificate>] [-ap
<authenticatePassword>] [-r
<numberOfRetries>]
Update the keys used with the bank
-a renewKeys -bn <bankName> -cid
<customerId> -uid <userId> [-sc
<signatureCertificate>] [-sp
<signaturePassword>] [-ec
<encryptionCertificate>] [-ep
<encryptionPassword>] [-ac
<authenticationCertificate>] [-ap
<authenticatePassword>] [-r
<numberOfRetries>]
Update the signature key used with the bank
-a renewSigkey -bn <bankName> -cid
<customerId> -uid <userId> [-sc
<signatureCertificate>] [-sp
<signaturePassword>] [-r <numberOfRetries>]
Update the encryption and authentication keys used with the bank
-a renewAuthkey -bn <bankName> -cid
<customerId> -uid <userId> [-ec
<encryptionCertificate>] [-ep
<encryptionPassword>] [-ac
<authenticationCertificate>] [-ap
<authenticatePassword>] [-r
<numberOfRetries>]
AxwayElectronic Signature 2.10.0 Administrator Guide 66
4 Use Electronic Signature with Gateway
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
AxwayElectronic Signature 2.10.0 Administrator Guide 67
4 Use Electronic Signature with Gateway
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
AxwayElectronic Signature 2.10.0 Administrator Guide 68
4 Use Electronic Signature with Gateway
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
AxwayElectronic Signature 2.10.0 Administrator Guide 69
4 Use Electronic Signature with Gateway
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 70
4 Use Electronic Signature with Gateway
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 71
4 Use Electronic Signature with Gateway
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
AxwayElectronic Signature 2.10.0 Administrator Guide 72
4 Use Electronic Signature with Gateway
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
AxwayElectronic Signature 2.10.0 Administrator Guide 73
4 Use Electronic Signature with Gateway
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 74
4 Use Electronic Signature with Gateway
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 75
4 Use Electronic Signature with Gateway
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 76
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 77
5 Control Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 78
5 Control Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 79
5 Control Electronic Signature
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
AxwayElectronic Signature 2.10.0 Administrator Guide 80
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 81
6 Manage Electronic Signature Agent
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 82
6 Manage Electronic Signature Agent
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 83
6 Manage Electronic Signature Agent
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 84
6 Manage Electronic Signature Agent
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
AxwayElectronic Signature 2.10.0 Administrator Guide 85
6 Manage Electronic Signature Agent
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 86
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 87
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 88
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 89
8 Develop exits for Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 90
8 Develop exits for Electronic Signature
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
AxwayElectronic Signature 2.10.0 Administrator Guide 91
8 Develop exits for Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 92
8 Develop exits for Electronic Signature
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:
######################################
AxwayElectronic Signature 2.10.0 Administrator Guide 93
8 Develop exits for Electronic Signature
#### 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.
AxwayElectronic Signature 2.10.0 Administrator Guide 94
8 Develop exits for Electronic Signature
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/.
AxwayElectronic Signature 2.10.0 Administrator Guide 95
8 Develop exits for Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 96
8 Develop exits for Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 97
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
AxwayElectronic Signature 2.10.0 Administrator Guide 98
9 Use PassPort with Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 99
9 Use PassPort with Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 100
9 Use PassPort with Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 101
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
AxwayElectronic Signature 2.10.0 Administrator Guide 102
10 Purge payments in Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 103
10 Purge payments in Electronic Signature
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 104
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 105
11 Single sign-on using SAML
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 106
11 Single sign-on using SAML
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 107
11 Single sign-on using SAML
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
AxwayElectronic Signature 2.10.0 Administrator Guide 108
11 Single sign-on using SAML
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
AxwayElectronic Signature 2.10.0 Administrator Guide 109
11 Single sign-on using SAML
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>
AxwayElectronic Signature 2.10.0 Administrator Guide 110
11 Single sign-on using SAML
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 111
11 Single sign-on using SAML
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 112
11 Single sign-on using SAML
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 113
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
AxwayElectronic Signature 2.10.0 Administrator Guide 114
Appendix A: configuration.properties file
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.
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 115
Appendix A: configuration.properties file
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 116
Appendix A: configuration.properties file
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 117
Appendix A: configuration.properties file
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.
Parameter Description Example
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.
Parameter Description Example
ui.session.expiration The time in minutes when the UI session will expire in case of inactivity
5
AxwayElectronic Signature 2.10.0 Administrator Guide 118
Appendix A: configuration.properties file
Parser configuration sectionThis section enables you to add external parsers in order to support additional file formats.
Parameter Description Example
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.
Parameter Description Example
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.
Parameter Description Example
email.admin.enabled This option controls whether administrators receive email when new payments do not match any rule
true
AxwayElectronic Signature 2.10.0 Administrator Guide 119
Appendix A: configuration.properties file
Parameter Description Example
email.general.senderAddress email address to display for the sent email
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
AxwayElectronic Signature 2.10.0 Administrator Guide 120
Appendix A: configuration.properties file
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
60000 [milliseconds]
paymentOrderIdImporter.pollingFrequency
Frequency of order ID scanner for sent payments
60000 [milliseconds]
paymentScheduler.pollingFrequency
Frequency of retries on payment to resubmit in case of errors
60000 [milliseconds]
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.
Parameter Description Example
interchange.encryptedPassword Password (encrypted) of Interchange user
AxwayElectronic Signature 2.10.0 Administrator Guide 121
Appendix A: configuration.properties file
Parameter Description Example
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.
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 122
Appendix A: configuration.properties file
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.
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 123
Appendix A: configuration.properties file
Parameter Description Example
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 124
Appendix A: configuration.properties file
Sentinel configuration sectionThis section contains information for the connection with Sentinel.
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 125
Appendix A: configuration.properties file
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.
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 126
Appendix A: configuration.properties file
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 127
Appendix A: configuration.properties file
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
AxwayElectronic Signature 2.10.0 Administrator Guide 128
Appendix A: configuration.properties file
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
AxwayElectronic Signature 2.10.0 Administrator Guide 129
Appendix A: configuration.properties file
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 130
Appendix A: configuration.properties file
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
30000 [milliseconds]
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
AxwayElectronic Signature 2.10.0 Administrator Guide 131
Appendix A: configuration.properties file
Parameter Description Example
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
AxwayElectronic Signature 2.10.0 Administrator Guide 132
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 133
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
AxwayElectronic Signature 2.10.0 Administrator Guide 134
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 135
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.
AxwayElectronic Signature 2.10.0 Administrator Guide 136