TIBCO BusinessConnect EBICS Protocol User s Guide. Software Release 1.0 December 2011

Transcription

1 TIBCO BusinessConnect EBICS Protocol User s Guide Software Release 1.0 December 2011

2 Important Information SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE. USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE LICENSE FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME. This document contains confidential information that is subject to U.S. and international copyright laws and treaties. No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc. TIBCO, The Power of Now, TIBCO Hawk, TIBCO Rendezvous, TIBCO Runtime Agent, TIBCO ActiveMatrix BusinessWorks, TIBCO Administrator, and TIBCO Designer are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries. EJB, J2EE, JMS and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only. THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM. THIS DOCUMENT IS PROVIDED AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLY ADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME. THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY, BY OTHER DOCUMENTATION WHICH ACCOMPANIES THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO ANY RELEASE NOTES AND "READ ME" FILES.. Copyright TIBCO Software Inc. ALL RIGHTS RESERVED. TIBCO Software Inc. Confidential Information

3 Contents iii Contents Preface v Related Documentation vi Typographical Conventions viii Connecting with TIBCO Resources x Chapter 1 Introduction Overview TIBCO BusinessConnect as an EBICS Client Chapter 2 Setting Up Trading Hosts and Partners Overview Configuring a Host Configuring a Partner Chapter 3 Configuring Business Agreements Adding a New Business Agreement Configuring Agreement Protocol Binding for EBICS Operation Bindings Tab Document Security Tab Transports Tab Chapter 4 Key Management with bcebicsmanage Overview Initializing the TIBCO BusinessConnect User Suspending Bank Access of the TIBCO BusinessConnect User Updating TIBCO BusinessConnect User Keys Recovering From Upload Errors to TIBCO BusinessConnect bcebicsmanage Keystore Updating the EBICS OrderID Chapter 5 Managing EBICS Operations Overview TIBCO BusinessConnect EZComm Protocol User s Guide

4 iv Contents Synchronous Request Response Operation Configuring EBICS Operations Chapter 6 Managing Properties Managing EBICS Properties Chapter 7 EBICS Private Messages Overview Initiator Request Initiator Response Error Advisories Chapter 8 Viewing Logs Log Viewer Overview Audit Logs Preferences Appendix A bcebicsmanage Command Reference Overview Bank Initialization Commands Bank Access Commands Key Update Commands Upload to BusinessConnect Commands Order ID Commands Index TIBCO BusinessConnect EZComm Protocol User s Guide

5 v Preface TIBCO BusinessConnect EBICS Protocol is a protocol used by banks in European countries that enables banking clients, such as corporations, to communicate with banks securely. Topics Related Documentation, page vi Typographical Conventions, page viii Connecting with TIBCO Resources, page x

6 vi Related Documentation Related Documentation TIBCO BusinessConnect EBICS Protocol Documentation The following documents form the TIBCO BusinessConnect EBICS Protocol documentation set: TIBCO BusinessConnect EBICS Protocol Installation and Configuration: Read this guide to install and configure TIBCO BusinessConnect EBICS Protocol. TIBCO BusinessConnect EBICS Protocol User s Guide: Read this guide to to learn how to manage TIBCO BusinessConnect EBICS Protocol. TIBCO BusinessConnect EBICS Protocol Release Notes: Read this document to learn about new features, changes in functionality, deprecated features, known issues, and closed issues for each release. This document is supplied for each release and is available only in PDF format. TIBCO BusinessConnect Documentation The following documents form the BusinessConnect documentation set: TIBCO BusinessConnect Installation and Configuration. Read this guide to learn how to install and configure TIBCO BusinessConnect. TIBCO BusinessConnect Concepts: Read this guide to learn about TIBCO BusinessConnect architecture, deployment modes, protocols, and security. TIBCO BusinessConnect Interior Server Administration: Read this guide in order to administer, operate, and manage TIBCO BusinessConnect Interior Server. TIBCO BusinessConnect Gateway Server Administration: Read this guide in order to administer, operate, and manage TIBCO BusinessConnect Gateway Server. TIBCO BusinessConnect Trading Partner Administration: Read this guide to configure and manage trading partners. TIBCO BusinessConnect Scripting Deployment User s Guide: Read this guide to configure and manage TIBCO BusinessConnect using the command line interface. TIBCO BusinessConnect Release Notes: Read this document to learn about new features, changes in functionality, deprecated features, known issues, and closed issues for each release. This document is supplied for each release and is available only in PDF format.

7 Preface vii Other TIBCO Product Documentation You may find it useful to read the documentation for the following TIBCO products, which may be used or integrated with BusinessConnect: TIBCO Administrator software: The software allows you to manage users, machines and applications defined in a TIBCO Administration Domain. The TIBCO Administrator graphical user interface enables users to deploy, monitor, and start and stop TIBCO applications. TIBCO ActiveMatrix BusinessWorks software: This software is a scalable, extensible, and easy to use integration platform that allows you to develop integration projects. TIBCO BusinessWorks includes a graphical user interface (GUI) for defining business processes and an engine that executes the process. TIBCO Designer software: This graphical user interface is used for designing and creating integration project configurations and building an Enterprise Archive (EAR) for the project. The EAR can then be used by TIBCO Administrator for deploying and running the application. TIBCO Runtime Agent software: This software suite is a prerequisite for other TIBCO software products. In addition to TIBCO Runtime Agent components, the software suite includes the third-party libraries used by other TIBCO products such as TIBCO Designer, Java Runtime Environment (JRE), TIBCO Hawk, and TIBCO Rendezvous. TIBCO Rendezvous : This software enables programs running on many different kinds of computers on a network to communicate seamlessly. It includes two main components: the Rendezvous programming language interface (API) in several languages, and the Rendezvous daemon. TIBCO Enterprise Message Service software: This software provides a message service that enables integration of applications within an enterprise based on the Java Message Service (JMS) specifications.

8 viii Typographical Conventions Typographical Conventions The following typographical conventions are used in this manual. Table 1 General Typographical Conventions Convention ENV_NAME TIBCO_HOME ebics_home Use TIBCO products are installed into an installation environment. A product installed into an installation environment does not access components in other installation environments. Incompatible products and multiple instances of the same product must be installed into different installation environments. An installation environment consists of the following properties: Name Identifies the installation environment. This name is referenced in documentation as ENV_NAME. On Microsoft Windows, the name is appended to the name of Windows services created by the installer and is a component of the path to the product shortcut in the Windows Start > All Programs menu. Path The folder into which the product is installed. This folder is referenced in documentation as TIBCO_HOME. TIBCO BusinessConnect EBICS Server installs into a directory within a TIBCO_HOME. This directory is referenced in documentation as ebics_home. The default value of ebics_home depends on the operating system. For example on Windows systems, the default value is C:\tibco\bc\version\protocols\ebics code font bold code font Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example: Use MyCommand to start the foo process. Bold code font is used in the following ways: In procedures, to indicate what a user types. For example: Type admin. In large code samples, to indicate the parts of the sample that are of particular interest. In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled: MyCommand [enable disable]

9 Preface ix Table 1 General Typographical Conventions (Cont d) Convention italic font Key combinations Use Italic font is used in the following ways: To indicate a document title. For example: See TIBCO ActiveMatrix BusinessWorks Concepts. To introduce new terms For example: A portal page may contain several portlets. Portlets are mini-applications that run in a portal. To indicate a variable in a command or code syntax that you must replace. For example: MyCommand PathName Key name separated by a plus sign indicate keys pressed simultaneously. For example: Ctrl+C. Key names separated by a comma and space indicate keys pressed one after the other. For example: Esc, Ctrl+Q. The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances. The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result. The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

10 x Connecting with TIBCO Resources Connecting with TIBCO Resources How to Join TIBCOmmunity TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts, a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to How to Access All TIBCO Documentation After you join TIBCOmmunity, you can access the documentation for all supported product versions here: How to Contact TIBCO Support For comments or problems with this manual or the software it addresses, please contact TIBCO Support as follows. For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site: If you already have a valid maintenance or support contract, visit this site: Entry to this site requires a user name and password. If you do not have a user name, you can request one.

11 1 Chapter 1 Introduction This chapter gives an overview of EBICS (Electronic Banking Internet Communication Standard) and explains briefly how TIBCO BusinessConnect is used as an EBICS client. Topics Overview on page 2 TIBCO BusinessConnect as an EBICS Client on page 3

12 2 Chapter 1 Introduction Overview TIBCO BusinessConnect EBICS Protocol provides a client-side implementation of EBICS (Electronic Banking Internet Communication Standard) version and is limited to supporting what is known as EBICS Profile T. This chapter introduces TIBCO BusinessConnect EBICS Protocol and its support for EBICS Profile T. For specification information on EBICS version 2.4.2, please refer to the document: Specification EBICS (Electronic Banking Internet Communication Standard) Version The current version of the EBICS specification is version 2.5.0, which was released in May 26, 2011 and is not yet supported bytibco BusinessConnect EBICS Protocol. The current version of the EBICS specification, as well as past versions of the EBICS specification, can be found at: EBICS Profile T is defined in the document EBICS - Implementation Guide in France, Version This version is consistent with V2.4.2 of the specifications. This French Implementation Guide can be found at: KUEQA?OpenDocument&loglvl=7KUELS About EBICS The Electronic Banking Internet Communication Standard (EBICS) is a standard used in the banking industries of Germany and France that specifies the transmission protocol for exchanging information between banks and their customers. It is a client-server protocol that uses the Internet and HTTPS as the transport for the exchange of information. The data being exchanged is encoded into XML documents, and encryption and digital signatures are applied for security. Additionally, the electronic signature of a person can be applied to authorize the financial transactions contained in the XML documents. EBICS was first developed for use in Germany and later extended for use in France, where it has replaced the use of ETEBAC3 and ETEBAC5. When using EBICS to replace ETEBAC3, an order is sent to the bank using EBICS, but confirmation that the order should be executed by the bank is sent through a communication channel other than EBICS (such as , fax). In other words, electronic signatures are not used for authorizing transactions. EBICS Profile T is the term used to describe this scenario for using EBICS. The remainder of this chapter describes the implementation of EBICS Profile T by TIBCO BusinessConnect EBICS Protocol.

13 TIBCO BusinessConnect as an EBICS Client 3 TIBCO BusinessConnect as an EBICS Client TIBCO BusinessConnect EBICS Protocol is designed to act as an EBICS technical subscriber that handles the transmission of all orders to the various banks you may want to communicate with. A technical subscriber executes all EBICS requests on behalf of users. The following diagram depicts the flow of transactions between your back end systems and a bank using TIBCO BusinessConnect EBICS Protocol. Figure 1 TIBCO BusinessConnect as an EBICS Client Company A Private Process BC Server RV/JMS Incoming Private Process Outgoing Private Process Enterprise Systems Internet HTTPS EBICS Bank Server Legend RV = TIBCO Rendezvous BC = TIBCO BusinessConnect Establishing a Banking Relationship To begin using TIBCO BusinessConnect EBICS Protocol, you as a customer of a bank must contact the bank and exchange the information required in order for the bank to set you up as a customer on their EBICS banking server. Some of the information the bank will need to know from you are: Your account number The name on your account The number of users who will be sending/receiving EBICS transactions. (See Note A) The names of the users. (See Note A)

14 4 Chapter 1 Introduction The type of the user (such as technical versus human) (See Note A) Whether the user can sign for orders. (See Note A) The types of EBICS orders the users are allowed to send/retrieve. Which orders need confirmation before the bank should execute them. (See Note B) Who is responsible for confirming orders. (See Note B) The method of sending order confirmations outside of EBICS. (See Note B) Note A: When establishing your relationship with a bank, it is important to let the bank know that you will have only one user sending orders to the bank and that the user is a technical user. This is because the user is being implemented by TIBCO BusinessConnect EBICS Protocol. The name you use for the BusinessConnect user can be any arbitrary name. Note B: When orders are sent to a bank, some orders must be confirmed before they will be executed with the bank. TIBCO BusinessConnect EBICS Protocol does not support sending electronic signatures to confirm orders, so order confirmations must be sent to the bank by some other means. How orders should be confirmed and who is responsible for confirming the orders should be established with the bank. In return for your information, the bank will provide you with the information needed to establish communication with the bank using EBICS. The information the bank will provide you with will include: Bank Name The bank's name Bank URL HTTPS URL for connecting to the bank. Bank Host ID ID of the bank. Customer ID ID assigned to the customer by the bank. User ID ID assigned to the user by the bank. User Name Name of the user. E001 Hash Value Not used. (See Note C) X001 Hash Value Not used. (See Note C) E002 Hash Value The sha-256 hash of the bank's public encryption key X002 Hash Value The sha-256 hash of the bank's public authentication key

15 TIBCO BusinessConnect as an EBICS Client 5 Bank SSL Cert Used for communicating via HTTPS with the bank Note C: The E001 and X001 Hash Values are not used by TIBCO BusinessConnect as they pertain to earlier versions of the EBICS specification that are not supported by TIBCO BusinessConnect. You will then configure your TIBCO BusinessConnect host and a trading partner for the bank using this information. See Chapter 2, Setting Up Trading Hosts and Partners, page 9 for detailed information on how to configure TIBCO BusinessConnect with the above information. EBICS Key and Certificate Management with TIBCO BusinessConnect Each user requires three keys for sending orders to banks. User Signature Key Used to generate electronic signature (ES) of the order data that the client sends to the bank. Authentication Key Used for identification and authentication of the client by the bank. Encryption Key Used for decryption of the symmetric key sent with orders that is used for encryption of the orders and electronic signatures. On the bank's side, all of the keys except for the signature key are used. Prior to sending any order to a bank, you must first initialize the TIBCO BusinessConnect user with the bank. The initialization process consists of these steps: 1. Send the user keys to the bank. 2. Send initialization letters with the public key information to the bank via a separate communication channel (such as fax). 3. Wait for the bank to release the user on their EBICS bank server. 4. Download the bank's public keys or certificates. 5. Verify the hash values of the bank's public keys. TIBCO BusinessConnect EBICS Protocol provides the tool bcebicsmanage for the management of your EBICS keys and certificates during initialization of the TIBCO BusinessConnect user with a bank. The bcebicsmanage tool provides the following capabilities: RSA public/private key pair generation according to the EBICS specification. X.509 self-signed certificate generation using the generated key pairs Initial client X.509 certificate exchange with banks via EBICS INI and HIA order types.

16 6 Chapter 1 Introduction Generation of initialization letters for the public keys or certificates. Retrieval of the bank's public keys and certs via EBICS HPB order type. Verification of the hash values for the bank's public keys. Update of existing client public keys and certificates with banks via EBICS HCS, HCA, and PUB order types. The bcebicsmanage tool works in conjunction with your TIBCO BusinessConnect configuration repository when running its commands. If the business agreement between your TIBCO BusinessConnect host and the bank's trading partner has not been configured with any of the three keys needed for exchanging orders with the bank, those keys will be automatically created during initialization of the TIBCO BusinessConnect host with the bank server and then uploaded back into the TIBCO BusinessConnect configuration repository. The diagram in Figure 2 depicts the case where bcebicsmanage creates the TIBCO BusinessConnect host's EBICS client keys and certificates, sends the certificates to the bank server, and then uploads the keys and certificates back to the TIBCO BusinessConnect repository. The diagram also depicts how, after initialization, bcebicsmanage is used to retrieve the bank's public keys and certificates and upload them into the TIBCO BusinessConnect Repository. Figure 2 Keys Created by BCEBICSMANAGE EBICS Client System BusinessConnect Client X,509 Certificates Bank SSL Certificate Bank URL Bank ID Customer ID User ID Client Private Keys & X.509 Certificates Bank Public Keys & Certificates Bank EBICS Server Internet BCEBICSMANAGE Bank Public Keys and Certificates When keys and certificates are stored in the TIBCO BusinessConnect repository, keys must be in PKCS#12 format and certificates should be in PKCS#7 format.

17 TIBCO BusinessConnect as an EBICS Client 7 When keys and certificates are generated by the bcebicsmanage tool, the generated keys and certificates will be encoded into the proper format; when keys are generated outside of the bcebicsmanage tool, the user is responsible for making sure that the key is encoded in PKCS#12 format. The bcebicsmanage tool is only used for initialization of the TIBCO BusinessConnect user with a bank, and whenever new keys or certificates need to be exchanged with the bank. The keys and certificates that are generated by bcebicsmanage will expire in five years, since the French Implementation Guide states that is when self-signed certificates should expire. You should also be aware that the French Implementation Guide states that keys that you create and that are signed by a Certification Authority (CA) should expire in three years. For further information on bcebicsmanage and how to run the commands to initialize a user or update keys, see Chapter 4, Key Management with bcebicsmanage, page 25. EBICS Order Transfers Once BusinessConnect has been initialized with a bank and the bank's public keys or certificates have been downloaded and the hashes verified, you are now capable of sending orders to the bank. EBICS defines two types of orders: upload and download. Both types of orders are initiated by the EBICS client. For download orders, an order to request the download is first sent to the bank, and the response to the request will contain the actual downloaded data. TIBCO BusinessConnect EBICS Protocol supports the order types FUL and FDL, which are defined for use in France. FUL is used for upload orders, while FDL is used for download orders. Both FUL and FDL orders are further refined by specifying the file format to use for an order. For detailed information on how to configure TIBCO BusinessConnect EBICS Protocol for upload and download orders, see Chapter 5, Managing EBICS Operations, page 35. Confirming Orders When orders are sent to a bank, some orders must be confirmed before they will be executed by the bank. TIBCO BusinessConnect EBICS Protocol does not support sending electronic signatures to confirm orders, so order confirmations must be sent to the bank by some other means. How orders should be confirmed and who is responsible for confirming the orders should have been established during the setting up of your relationship with the bank. After sending an order that needs confirmation to the bank, the user is responsible for ensuring the confirmation of that order.

18 8 Chapter 1 Introduction

19 9 Chapter 2 Setting Up Trading Hosts and Partners This chapter explains how to set up trading hosts and partners for TIBCO BusinessConnect EBICS Protocol. Topics Overview on page 10 Configuring a Host on page 11 Configuring a Partner on page 12

20 10 Chapter 2 Setting Up Trading Hosts and Partners Overview Using the TIBCO Administrator UI, the TIBCO BusinessConnect administrator sets up trading partners and configures a business agreement as follows: 1. Configure the Host participant, which will represent the user, and set it up for the EBICS protocol. See Configuring a Host, page Configure the Partner participant, which will represent the bank, and import the bank SSL certificate. Then, configure the user information provided by the bank. See Configuring a Partner, page Create a business agreement between the Host and the Partner (Bank). See Chapter 3, Configuring Business Agreements, page 17. Once you have finished all partner and business agreement configuration steps, use the bcebicsmanage tool to initialize the user as explained in Chapter 4, Key Management with bcebicsmanage, page 25.

21 Configuring a Host 11 Configuring a Host Table 1 Host Settings: General Tab To configure a host that will play the role of a user in this installation, do the following: 1. Select BusinessConnect>Participants. 2. Click the New button. 3. Type the host s name in the Name field. 4. Select Host in the Type drop-down list. 5. Click OK. 6. In the New Host Participant dialog, select the Active checkbox. 7. Click Apply. 8. Select the Protocols tab. If the TIBCO BusinessConnect EBICS Protocol has already been activated as explained in TIBCO BusinessConnect EBICS Protocol Installation and Configuration, Protocol Activation, it is now listed under Enabled Protocols. Otherwise, you need to enable it first. 9. Click on the EBICS link. Select or enter the information according to Table 1. Field Valid Address List Authentication Key Type Encryption Key Type User Signature Key Type Description (Not used for EBICS) The authentication key type to use during initialization process. The only value allowed for this release is X002. The encryption key type to use during initialization process. The only value allowed for this release is E002. This key is used for creating the transport signature. The only value allowed for this release is A Click Save.

22 12 Chapter 2 Setting Up Trading Hosts and Partners Configuring a Partner TIBCO BusinessConnect partner in this installation represents the bank. To configure the partner, bank information contained in the user access document is entered as partner properties. 1. Select BusinessConnect>Participants. 2. Click the New button. 3. Type partner s name in the Name box. 4. Select Partner in the Type dropdown list. 5. Click OK. 6. In the New Partner Participant window, select the Active checkbox. 7. Click Apply. Enable Protocol for the Partner 1. Select the Protocols tab. 2. Click Enable. The dialog with installed protocols appears. 3. Select the checkbox next to EBICS. 4. Click OK. The EBICS protocol is now in the Enabled Protocols list. 5. Click on the EBICS link. The Edit Enabled Protocol dialog appears, with the following tabs: General Tab, page 13 Transports Tab, page 14

23 Configuring a Partner 13 General Tab Table 2 Partner Settings: General Tab Select or enter information as explained in Table 2. Field Valid Address List HostID for Bank Bank Name EBICS Protocol Version Description (Not used for EBICS) The hostid of the bank (required) The bank s name (required) Currently, only protocol version H003 is supported. Hash Values for Bank Keys E002 X002 Test Mode Hash value for the bank's E002 certificate (required) Hash value for the bank's X002 certificate (required) When selected, runtime will send Test requests to the bank. An OrderParm named TEST will be added to the request, which will treat the request as a test request. For the FUL operation, there is a FULOrderParams element connected with the parameter TEST; for the FDL operation, TEST is not available. Technical Subscriber Information EBICS Customer ID EBICS User ID EBICS User Name ID assigned to the customer by the bank (required) ID assigned to the user by the bank (required) User name (required)

24 14 Chapter 2 Setting Up Trading Hosts and Partners Table 2 Partner Settings: General Tab Field Description OrderID Prefix A character in the range A - Z. A user is assigned a character, and all the orders sent by this user will have an orderid starting with this character. Every FUL request sent by a user should have a unique orderid. The orderid can range from prefix+000 to prefix+zzz. TIBCO BusinessConnect will create a unique orderid by incrementing it for every order sent by this user. If an orderid prefix is changed for a given user, the orderid sequence with the previous prefix will be saved; for example, when any of the previously used prefixes are specified, the sequence number with that prefix will be used Reset OrderID Reset the OrderID in TIBCO BusinessConnect to prefix+000. The orderid is reset only after a user is initialized. Click Save. Transports Tab To add a transport for the partner, do the following: 1. Click on the Transports tab. 2. Click Add. Enter data for the new transport as explained in Table 3. Table 3 New Transport for the Partner Field Name Type Description Enter the name for the transport (required) Select the transport type (EBICS) from the dropdown list. 3. Click OK. 4. Configure the new EBICS transport as described in Table 4.

25 Configuring a Partner 15 Table 4 New EBICS Transport Transport Name URL Server Certificate The transport name can be changed URL of the bank EBICS server (required), such as: Add the SSL certificate sent from the bank. This certificate can be uploaded as explained in TIBCO BusinessConnect Trading Partner Administration, Managing Partner Credentials. Socket Timeout (sec) Leave the default (300). 5. Click Save three times. Manage Partner Credentials You can upload a partner certificate using the Credentials tab: New Certificate To upload a new certificate for the partner, perform these steps: 1. Select BusinessConnect>Participants> partner> Credentials tab. 2. Click New Certificate. Type the name of the key in the Alias field. 3. In the Current Credential line click change. Browse and navigate to the file containing the public key and click OK. 4. Click Save. The new certificate for the partner is now listed in the Credential Name list. SSH public keys and PGP public keys are not used for TIBCO BusinessConnect EBICS Protocol.

26 16 Chapter 2 Setting Up Trading Hosts and Partners

27 17 Chapter 3 Configuring Business Agreements This chapter explains how to configure business agreements and protocol bindings for TIBCO BusinessConnect EBICS Protocol. Topics Adding a New Business Agreement on page 18 Configuring Agreement Protocol Binding for EBICS on page 19 Operation Bindings Tab on page 20 Document Security Tab on page 22 Transports Tab on page 24

28 18 Chapter 3 Configuring Business Agreements Adding a New Business Agreement After the TIBCO BusinessConnect host and bank trading partner have been configured, you will now configure their business agreement. 1. Select BusinessConnect>Business Agreements. 2. Click the New button. The New Agreement dialog appears. Verify that EBICS appears in the Protocols column for both trading partners between which you wish to configure a business agreement. If EBICS is missing, return back to Enable Protocol for the Partner, page 12 and enable the EBICS protocol. 3. Select a host from the Host Party list that has EBICS protocol enabled. 4. Select a partner from the Partner Party list hat has EBICS protocol enabled. 5. Click OK. The New Agreement, general dialog appears. 6. Confirm that the Valid checkbox is selected. This will make the agreement valid immediately. If you wish to make the agreement valid for a certain time period, do the following: Use the Start Date dropdown lists to specify the start date. Use the End Date dropdown lists to specify the stop date. This date has to be later than the start date.

29 Configuring Agreement Protocol Binding for EBICS 19 Configuring Agreement Protocol Binding for EBICS To configure EBICS agreement protocol bindings, follow these steps: 1. In the New Agreement dialog, click Add Protocol Bindings. 2. In the Select Protocol dialog, select the checkmark next to EBICS. 3. Click OK. The New Agreement dialog appears. 4. Click the EBICS link in the Agreement Protocol Binding list. The following tabs for configuring protocol binding options are available: Operation Bindings Tab Document Security Tab Transports Tab

30 20 Chapter 3 Configuring Business Agreements Operation Bindings Tab Use the Operations Binding tab to configure the EBICS operations that each participant in a business agreement can initiate and respond to. The Host X Can Initiate and Partner Y Can Initiate areas list the activities that the host/partner can initiate and the partner/host can respond to. 1. Enter information according to Table 5. Table 5 Edit Protocol Binding: Operation Binding Tab Field Allow All Operations Non Repudiation Logging Description This checkbox is selected by default. If you leave it selected, you don t need to specify operation bindings that the host or partner can initiate. If the checkbox is cleared, you need to define the specific operation bindings. (Not used by EBICS) 2. In the Host can initiate section, click Add Operation Binding. 3. Click the topmost (+) to expand the operation tree and select the operation. 4. Click OK. The selected operation appears in the Operation Name list. Edit Operation Bindings for the Host Click the operation in the panel Host can initiate. The following tabs for configuring options are available: Operation Settings Tab Transports Tab

31 Operation Bindings Tab 21 Operation Settings Tab Override the operation settings using Table 6. Table 6 Override Outbound Settings: Operation Settings Tab (All Operations) Field Override Operation Settings Description Select the checkbox to override the operation settings for this operation. These settings have been previously configured. Inbound for FDL; Outbound for FUL Validate Message When selected, the request message will be validated. Click Save. Transports Tab Configure transport settings using Table 7. Table 7 Override Outbound Settings: Transports Tab (All Operations) Field Override Transports Description Select to override the originally configured transport for the host. Override Outbound Transports Primary Transport Select any of the transports previously configured for the partner. See Transports Tab, page 14 for more details. Click Save. Show Advanced Button In TIBCO BusinessConnect EBICS Protocol there are no properties that can be overridden. Therefore this option is not applicable although it appears in the TIBCO Administrator GUI. Edit Operation Bindings for the Partner Operation bindings for the partner are not used for TIBCO BusinessConnect EBICS Protocol since the bank cannot initiate a transaction with TIBCO BusinessConnect.

32 22 Chapter 3 Configuring Business Agreements Document Security Tab The Document Security tab is used to specify security settings for the business transaction that is being exchanged. Before using the Document Security tab to select any keys or certificates, you must first configure these keys or certificates as explained in TIBCO BusinessConnect Trading Partner Administration, Managing Host Credentials. Keep in mind that only one set of valid bank keys may exist at one time. Therefore, shadow certificates cannot be used for EBICS. 1. Configure document security using the information provided on Table 8. Table 8 Edit Protocol Bindings: Document Security Tab Field Enter/Select Outbound Doc Exchange Signing Info Settings Signing Key Select the signing private key of the host from the dropdown list. This key is used to generate the EBICS identification and authentication signature on messages sent to the EBICS bank server. User Signature Info Settings When None is selected for this key, the bcebicsmanage tool commands -init and -update* will automatically generate this key and populate this setting for you. The key will be generated according to the host's Authentication Key Type setting. User Signature Key Select the user signature private key of the host from the dropdown list. This key is used to generate the electronic signature of the order data that the client uploads to the bank. When None is selected for this key, the bcebicsmanage tool commands -init and -update* will automatically generate this key and populate this setting for you. The key will be generated according to the host's User Signature Key Type setting.

33 Document Security Tab 23 Table 8 Edit Protocol Bindings: Document Security Tab Field Enter/Select Encryption Info Settings Encryption Certificate Specifies the Encryption certificate obtained from the bank. Running the -verify command with the bcebicsmanage tool will set this certificate automatically. Inbound Doc Exchange Signing Info Settings Verification Certificate Specifies the Verification certificate obtained from the bank. Running the -verify command with the bcebicsmanage tool will set this certificate automatically. Encryption Info Settings Decryption Key Select the decryption private key of the host from the dropdown list. This key is used for decryption of the symmetric key, which is sent with orders and is used for encryption of the orders and electronic signatures. When None is selected for this key, the bcebicsmanage tool commands -init and -update* will automatically generate this key and populate this setting for you. The key will be generated according to the host's Encryption Key Type setting.

34 24 Chapter 3 Configuring Business Agreements Transports Tab Table 9 Configure Transports for the Host Configure transports for the host according to Table 9. Field Description Outbound Transports for Host This section is is used for specifying transport information for the outbound direction, or host to trading partner. Primary Transport Client Authentication Identity for HTTPS, FTPS, HTTPS CA Client Authentication Identity for SSHFTP Select the outbound transport that was previously configured for the host. See Transports Tab, page 14 for more details. (Not used for EBICS) (Not used for EBICS) Allowed Inbound Transports for Partner Since the EBCIS bank cannot initiate a transaction with TIBCO BusinessConnect, no inbound transport configuration is needed. Click Save twice. Advanced Tab Advanced configuration settings are not supported for TIBCO BusinessConnect EBICS Protocol.

35 25 Chapter 4 Key Management with bcebicsmanage This chapter explains how to manage keys that belong to the TIBCO BusinessConnect user using the bcebicsmanage tool. Topics Overview on page 26 Initializing the TIBCO BusinessConnect User on page 27 Suspending Bank Access of the TIBCO BusinessConnect User on page 29 Updating TIBCO BusinessConnect User Keys on page 30 Recovering From Upload Errors to TIBCO BusinessConnect on page 31 bcebicsmanage Keystore on page 32 Updating the EBICS OrderID on page 33

36 26 Chapter 4 Key Management with bcebicsmanage Overview TIBCO BusinessConnect EBICS Protocol provides a tool, bcebicsmanage, to perform the functions relating to key management of the TIBCO BusinessConnect user. This chapter describes the key management functions provided by the bcebicsmanage tool and when they are used. For specific details on how to configure the bcebicsmanage tool and how to run each of the commands, see Appendix A, bcebicsmanage Command Reference, page 59.. This chapter describes how to use the bcebicsmanage tool to perform the following: Create keys for the TIBCO BusinessConnect user. Send the TIBCO BusinessConnect user keys to the bank. Retrieve the bank's public keys. Verify the hashes of the bank's public keys. Upload the keys generated for the TIBCO BusinessConnect user to the TIBCO BusinessConnect repository. Upload the bank's public keys to the TIBCO BusinessConnect repository. Change the keys for the TIBCO BusinessConnect user. Suspend the TIBCO BusinessConnect user's access to a bank.

37 Initializing the TIBCO BusinessConnect User 27 Initializing the TIBCO BusinessConnect User Two bcebicsmanage tool commands, -init and -verify, are used when the TIBCO BusinessConnect user first initializes with the EBICS server of a bank. The -init command sends the certificates associated with the private keys of the TIBCO BusinessConnect user to the bank; the -verify command retrieves the bank's public keys and verifies the hash values of those keys with the ones which were previously provided by the bank. -init The -init command is typically run just once to initiate the setup of an EBICS client with a bank's EBICS server. You will run the -init command when the bank has indicated that the TIBCO BusinessConnect user has been configured on their EBICS server. When you run the -init command the following occurs: If private keys have been configured in the Document Security settings of the business agreement, those keys are retrieved from the TIBCO BusinessConnect repository. Any key that has not been configured will be generated according to the French Implementation Guide for EBICS. Self-signed X.509 certificates will be generated for any private keys created. The X.509 certificates for all 3 keys (authentication, encryption, and user signature) will be sent to the bank using the EBICS INI and HIA commands. Initialization letters for the 3 keys will be created in the directory BC_HOME/protocols/ebics/tools/letters. The generated keys will be uploaded back into the TIBCO BusinessConnect repository. The Document Security settings of the business agreement will be updated with the generated keys. After running the -init command, you will need to sign each of the initialization letters and send them to the bank by some other means than using EBICS; for example, you could fax the letters to the bank. The method for sending the initialization letters to the bank should be established in the contract between you and the bank. -verify Once the bank has indicated that the public keys (contained in the X.509 certificates) of the TIBCO BusinessConnect user have been released on their EBICS server, you can run the -verify command to download the bank's public keys. The -verify command can be run any number of times, but typically will be run once after the -init command is run, and then again whenever the bank notifies you that its keys have changed.

38 28 Chapter 4 Key Management with bcebicsmanage When you run the -verify command the following occurs: The bank's authentication and encryption public keys are retrieved using the EBICS HPB command. The hash values of the retrieved keys are compared against the hash values configured for the keys in the General settings of the bank's trading partner configuration in the TIBCO BusinessConnect Administrator GUI. If the public keys are not retrieved as X.509 certificates, new X.509 certificates are created for the keys. These X.509 certificates are signed by the internal CA of the bcebicsmanage tool. The bank's X.509 certificates are converted to PKCS#7 and loaded into the TIBCO BusinessConnect repository. The Document Security settings for the business agreement are updated with the bank's certificates.

39 Suspending Bank Access of the TIBCO BusinessConnect User 29 Suspending Bank Access of the TIBCO BusinessConnect User The bcebicsmanage tool command, -lock, is used to suspend any further access of the BusinessConnect user to a bank. -lock The -lock command causes the EBICS SPR command to be sent to the bank. After the -lock command has been executed, the bank will return an error if the TIBCO BusinessConnect user tries to continue to communicate with the bank. To resume communication with the bank, the TIBCO BusinessConnect user must be re-initialized by sending the bcebicsmanage tool commands -init and -verify again. To learn how to initialize a user, see See Initializing the TIBCO BusinessConnect User, page 27. If the private keys of the TIBCO BusinessConnect user have been compromised, you should do the following after running the -lock command and before re-running the -init command: Configure your own new key(s) in the Document Security settings of the business agreement. Specify None in the Document Security settings of the business agreement for any key you wish to be automatically created anew when the command -init is executed. It is important to understand that if you do not change your key configuration in the Document Security settings of the business agreement, the keys currently configured will be used by the -init command. If the configured keys were compromised, you would have just re-initialized with the same compromised keys.

40 30 Chapter 4 Key Management with bcebicsmanage Updating TIBCO BusinessConnect User Keys The French Implementation Guide states that self-signed certificates must be renewed after a period of five years, and that certificates signed by a CA must be renewed after a period of three years. Therefore, it will be necessary for the public keys of the TIBCO BusinessConnect user to be periodically updated with the bank. The bcebicsmanage tool provides three options for updating the TIBCO BusinessConnect user keys: -updatekeys Sends the X.509 certificates of all three keys, as configured in the Document Security settings of the business agreement, to the bank using the EBICS HCS command. -updatesignkey Sends the X.509 certificate of the configured User Signature Key to the bank using the EBICS PUB command. -updateauthencrkeys Sends the X.509 certificates of the configured Authentication and Encryption keys to the bank using the EBICS HCA command. These -update* commands, which update the TIBCO BusinessConnect user keys, act the same as the -init command when it comes to key configuration, key generation, and X.509 certificate generation. If you specify None in the Document Security settings of the business agreement for any key, that key will be automatically generated by the corresponding -update* command and a self-signed X.509 certificate will be created for the generated key. Otherwise, the key that is updated with the bank will be the key that is configured in the Document Security settings. Unlike the -init command, with the -update* commands it is not necessary to send initialization letters for the new keys to the bank. The keys are exchanged in a secure manner using the previously exchanged keys, so initialization letters to confirm the hashes of the keys are not necessary. The -update* commands can be run any number of times after the TIBCO BusinessConnect user has been initialized, and as long as the TIBCO BusinessConnect user has not been suspended with the bank.