Sun Microsystems 5.1.1 User Manual

SUN SEEBEYOND

eWAY™ HTTPS ADAPTER USER’S GUIDE

Release 5.1.1

Copyright © 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in other countries. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc. standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. This distribution may include materials developed by third parties. Sun, Sun Microsystems, the Sun logo, Java, Sun Java Composite Application Platform Suite, SeeBeyond, eGate, eInsight, eVision, eTL, eXchange, eView, eIndex, eBAM, eWay, and JMS are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon architecture developed by Sun Microsystems, Inc. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. This product is covered and controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile, chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited. Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but not limited to, the denied persons and specially designated nationals lists is strictly prohibited.

Copyright © 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, Etats-Unis. Tous droits réservés.Sun Microsystems, Inc. détient les droits de propriété intellectuels relatifs à la technologie incorporée dans le produit qui est décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuelle peuvent inclure un ou plus des brevets américains listés à l'adresse http://www.sun.com/patents et un ou les brevets supplémentaires ou les applications de brevet en attente aux Etats - Unis et dans les autres pays.L'utilisation est soumise aux termes de la Licence.Cette distribution peut comprendre des composants développés par des tierces parties.Sun, Sun Microsystems, le logo Sun, Java, Sun Java Composite Application Platform Suite, Sun, SeeBeyond, eGate, eInsight, eVision, eTL, eXchange, eView, eIndex, eBAM et eWay sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux EtatsUnis et dans d'autres pays.Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc.UNIX est une marque déposée aux Etats-Unis et dans d'autres pays et licenciée exlusivement par X/Open Company, Ltd.Ce produit est soumis à la législation américaine en matière de contrôle des exportations et peut être soumis à la règlementation en vigueur dans d'autres pays dans le domaine des exportations et importations. Les utilisations, ou utilisateurs finaux, pour des armes nucléaires,des missiles, des armes biologiques et chimiques ou du nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou réexportations vers les pays sous embargo américain, ou vers des entités figurant sur les listes d'exclusion d'exportation américaines, y compris, mais de manière non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer, d'une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la législation américaine en matière de contrôle des exportations et la liste de ressortissants spécifiquement désignés, sont rigoureusement interdites.

Version 20060623131507

HTTPS eWay Adapter User’s Guide 2 Sun Microsystems, Inc.

Contents

Chapter 1

Introducing the HTTPS eWay 7

About HTTP and HTTPS 7

About the HTTPS eWay 8

HTTP Messages 8 Web Browser Cookies 8

Cookie Expiration Date Checking 9

GET and POST Methods 9 Sample HTTP Exchange in Client Mode 9 Sample HTTP Exchange in Server Mode 10

What’s New in This Release 11

About This Document 12

HTTPS eWay Javadoc 13

Scope 13 Intended Audience 13 Text Conventions 13

Introducing the HTTPS eWay

Welcome to the Sun SeeBeyond eWay™ HTTPS Adapter User’s Guide. This document includes information about installing, configuring, and using the Sun Java Composite Application Platform Suite HTTPS eWay™ Adapter, referred to as the HTTPS eWay throughout this guide.

This chapter provides an overview of Hypertext Transfer Protocol (HTTP) and HTTP over Secure Socket Layer (SSL), better known as HTTPS. This chapter also introduces the HTTPS eWay.

What’s in This Chapter

 About HTTP and HTTPS on page 7

 About the HTTPS eWay on page 8

 What’s New in This Release on page 11

 About This Document on page 12

 Related Documents on page 13

Chapter 1

 Sun Microsystems, Inc. Web Site on page 14

 Documentation Feedback on page 14

1.1 About HTTP and HTTPS

HTTP

HTTP (hypertext transfer protocol) is the set of rules used for transferring files (text, graphic images, sound, and video) over the Web. When a user opens a Web browser, the user is indirectly making use of HTTP. HTTP is an application protocol that runs on top of the TCP/IP suite of protocols.

In addition to the files that it serves, every Web server contains an HTTP daemon—a program that waits for HTTP requests and handles them when they arrive. A Web browser is an HTTP client, sending requests to server machines. When the user enters a URL or clicks on a hypertext link, the browser builds an HTTP request and sends it to the IP address indicated by the URL. The HTTP daemon in the destination server machine receives the request and sends back the requested file or files associated with the request.

HTTPS eWay Adapter User’s Guide 7 Sun Microsystems, Inc.

Chapter 1 Section 1.2

Introducing the HTTPS eWay About the HTTPS eWay

HTTPS

HTTPS (hypertext transfer protocol over secure socket layer—or HTTP over SSL) is a Web protocol that encrypts and decrypts user page requests as well as the pages that are returned by the Web server. HTTP uses port 443 instead of HTTP port 80 in its interactions with the lower layer TCP/IP. SSL uses a 40-bit encryption key algorithm, which is considered an adequate level of encryption for commercial exchange.

When an HTTPS request is sent by a browser—usually by clicking a link that begins with https://—the client browser encrypts the request and sends it to the Web server. The acknowledgement sent by the Web server is also sent using encryption, and is decrypted by the client browser.

1.2 About the HTTPS eWay

The HTTPS eWay enables eGate Integrator to communicate with client and server applications over the Internet using HTTP, either with or without SSL.

1.2.1 HTTP Messages

An HTTP message has two parts: a request and a response. The message header is composed of a header line, header fields, a blank line, and an optional body (or data payload). The response is made up of a header line, header fields, a blank line, and an optional body (or data payload). HTTP is a synchronous protocol, that is, a client makes a request to a server and the server returns the response on the same socket.

1.2.2 Web Browser Cookies

A cookie is an HTTP header, which is a key-value pair in the header fields section of an HTTP message.

The Set-Cookie and Cookie headers are used with cookies. The Cookie-request header is sent from the server in request for cookies on the client side. An example of a Cookie- request header is:

Set-Cookie: sessauth=44c46a10; expires=Wednesday, 27-Sep-2006 03:59:59 GMT

In this example, the server requests that the client store the following cookie:

sessauth=44c46a10

Everything after the first semi-colon contains additional information about the cookie, such as the expiration date. When the eWay sees this header, it extracts the cookie sessauth=44c46a10 and returns it to the server on subsequent requests. The eWay prepends a cookie header to the HTTP request, for example:

Cookie: sessauth=44c46a10

Each time the eWay sends a request to the same server during a session, the cookie is sent along with the request.

HTTPS eWay Adapter User’s Guide 8 Sun Microsystems, Inc.

Chapter 1 Section 1.2

Introducing the HTTPS eWay About the HTTPS eWay

Cookie Expiration Date Checking

The HTTPS eWay checks time-limited cookies with expiration dates to ensure that they have not expired. If they have expired, the cookie is removed and is not resent to the originating server. As a result, the session state is removed.

The following standard expiration date formats are recognized by the HTTPS eWay:

"Sun, 06 Nov 1994 08:49:37 GMT" ;RFC 822, updated by RFC 1123 "Sunday, 06-Nov-94 08:49:37 GMT";RFC 850, obsoleted by RFC 1036 "Sunday, 06-Nov-1994 08:49:37 GMT";RFC 1036 "Sun Nov 6 08:49:37 1994" ;ANSI C's asctime()

If the expiration date is in another format, the eWay does not recognize the expiration date. Instead, it treats the cookie as if it does not have an expiration date.

1.2.3 GET and POST Methods

The GET method can be used in client mode to retrieve a page specified by the URL or to retrieve information from a form-based Web page by submitting URL-encoded key and name value pairs. In the latter case, the page must support the GET method.

The following example shows a URL-encoded query string:

http://.../bin/query?p=seebeyond+integrator

The URL specifies the search page and the name-value pair for the search. The question mark (?) indicates the beginning of the name-value pair encoding. In the previous example, the name portion of the query is “p,” and the value to search is “seebeyond integrator.” A query can consist of one or more of these name-value pairs.

Note: See the official HTTP Specification for complete information.

The POST method is more versatile, in that it supports form-based requests, as well as sending large amounts of data. The POST method does not have the size-limitation maximum of 255 or 1024 characters (depending on the Web server), which the GET method has. As with GET, the Web page must support the POST method in order to use POST.

Taking the previous URL as an example, if you specify the following URL:

http://

.../bin/query

Then, you can specify the name-value pair separately. The HTTP client allows for the specification of the URL and n-number of value pairs via its methods.

1.2.4 Sample HTTP Exchange in Client Mode

To retrieve the file at the following URL:

http://www.myhost.com/path/file.html

First open a socket to the host www.myhost.com, port 80 (use the default port of 80 because none is specified in the URL). You can then send a request through a socket that looks like the following example:

HTTPS eWay Adapter User’s Guide 9 Sun Microsystems, Inc.

Chapter 1 Section 1.2

Introducing the HTTPS eWay About the HTTPS eWay

GET /path/file.html HTTP/1.0 (Request Header Line) User-Agent: HTTP(S)eWay (Request Header field)

The server sends a response back through the same socket. The response could look like the following example:

HTTP/1.0 200 OK (Response Header Line) Date: Fri, 31 Dec 1999 23:59:59 GMT(Response Header Field) Content-Type: text/html (Response Header Field) Content-Length: 1354 (Response Header Field) [blank line here] <html> (Response payload) <body> <h1>Happy New Millennium!</h1> (more file contents)

. .

. </body> </html>

After sending the response, the server closes the socket.

1.2.5 Sample HTTP Exchange in Server Mode

To listen for a request from an HTTP client, the HTTPS eWay in server mode listens on the port configured for your Integration Server (18001 by default). The HTTPS eWay receives the request and processes it according to the logic you create in your Collaboration or Business Process.

In a simple example, the HTTPS eWay receives a request from the following form:

<HTML><HEAD><TITLE>HTTP Server JCE Test Page</TITLE></HEAD> <BODY> <FORM ACTION="http://localhost:18001/Deployment1_servlet_MyServlet/ MyServlet" METHOD=POST> <TABLE> <TR><TD>What's your name? </TD><TD><INPUT NAME=fname></TD></TR> <TR><TD></TD><TD></TD></TR> </TABLE> <BR> <CENTER><INPUT TYPE=submit VALUE="Submit"></CENTER> </FORM> </BODY> </HTML>

HTTPS eWay Adapter User’s Guide 10 Sun Microsystems, Inc.

Chapter 1 Section 1.3

Introducing the HTTPS eWay What’s New in This Release

Figure 1 Sample Input Form

When the client enters a name in a browser and clicks Submit, the HTTPS eWay server returns a simple response (according to the logic in the Collaboration or Business Process).

Figure 2 Sample Response

1.3 What’s New in This Release

The HTTPS eWay includes the following changes and new features:

 Version Control: An enhanced version control system allows you to effectively

manage changes to the eWay components.

 Manual Connection Management: Establishing a connection can now be

performed automatically (configured as a property) or manually (using OTD methods from the Java Collaboration).

HTTPS eWay Adapter User’s Guide 11 Sun Microsystems, Inc.

Chapter 1 Section 1.4

Introducing the HTTPS eWay About This Document

 Multiple Drag-and-Drop Component Mapping from the Deployment Editor: The

Deployment Editor now allows you to select multiple components from the Editor’s component pane, and drop them into your Environment component.

 Support for Runtime LDAP Configuration: eWay configuration properties now

support LDAP key values.

 Connectivity Map Generator: Generates and links your Project’s Connectivity Map

components using a Collaboration or Business Process.

 Support for Digest Authentication: eWay functionality now supports HTTP Digest

Authentication.

 Support for Cookie Redirect: eWay functionality supports now for Cookie

Redirect.

 Logging in the OTD: The User ID and Password are now exposed in the OTD.

 Basic Authentication feature through eDesigner for WebService Server and HTTP

Server.

Many of these features are documented further in the Sun SeeBeyond eGate™ Integrator User’s Guide or the Sun SeeBeyond eGate™ Integrator System Administration Guide.

1.4 About This Document

This guide includes the following chapters:

 Chapter 1 “Introducing the HTTPS eWay”: Provides an overview description of

the product as well as high-level information about this document.

 Chapter 2 “Installing the HTTPS eWay”: Describes the system requirements and

provides instructions for installing the HTTPS eWay.

 Chapter 3 “Understanding the HTTPS eWay OTD”: Provides a description of the

Object Type Definitions to be used with the HTTPS eWay.

 Chapter 4 “Operating SSL”: Explains the operation of the Secure Sockets Layer

(SSL) feature available with the HTTPS eWay, and provides detailed information on how to use the OpenSSL utility.

 Chapter 5 “Configuring the HTTPS eWay”: Provides instructions for configuring

the eWay.

 Chapter 6 “Implementing the HTTPS eWay BPEL Sample Projects”: Describes

how to use the HTTPS eWay with eInsight Business Process Manager and reviews a sample Project that uses eInsight.

 Chapter 7 “Implementing the HTTPS eWay JCD Sample Projects”: Describes

how to implement the HTTPS eWay using a review of the sample Project, which uses Java-based Collaborations.

HTTPS eWay Adapter User’s Guide 12 Sun Microsystems, Inc.

Chapter 1 Section 1.4

Introducing the HTTPS eWay About This Document

HTTPS eWay Javadoc

An HTTPS eWay Javadoc is also provided that documents the Java methods available with the HTTPS eWay. The Javadoc is uploaded with the eWay’s documentation file (HTTPeWayDocs.sar) and downloaded from the Documentation tab of the Sun Java Composite Application Platform Suite Installer. To access the full Javadoc, extract the Javadoc to an easily accessible folder, and double-click the index.html file.

1.4.1 Scope

This user’s guide provides a description of the HTTPS eWay Adapter. It includes directions for installing the eWay, configuring the eWay properties, and implementing the eWay’s sample Projects. This document is also intended as a reference guide, listing available properties, functions, and considerations. For a reference of available HTTPS eWay Java methods, see the associated Javadoc.

1.4.2 Intended Audience

This guide is intended for experienced computer users who have the responsibility of helping to set up and maintain a fully functioning Java Composite Application Platform Suite system. This person must also understand any operating systems on which the Java Composite Application Platform Suite will be installed (Windows and UNIX), and must be thoroughly familiar with Windows-style GUI operations.

1.4.3 Text Conventions

The following conventions are observed throughout this document.

Table 1 Text Conventions

Text Convention Used For Examples

Bold Names of buttons, files, icons,

parameters, variables, methods, menus, and objects

Monospaced Command line arguments, code

samples; variables are shown in

bold italic

Blue bold

Blue underlined

Hypertext links within document

Hypertext links for Web addresses (URLs) or email addresses

 Click OK.  On the File menu, click Exit.  Select the eGate.sar file.

java -jar filename.jar

See

Text Conventions on page 13

http://www.sun.com

HTTPS eWay Adapter User’s Guide 13 Sun Microsystems, Inc.

Chapter 1 Section 1.5

Introducing the HTTPS eWay Related Documents

1.5 Related Documents

The following Sun documents provide additional information about the Sun Java Composite Application Platform Suite product:

 Sun SeeBeyond eGate™ Integrator

 Sun Java Composite Application Platform Suite Installation Guide

1.6 Sun Microsystems, Inc. Web Site

The Sun Microsystems web site is your best source for up-to-the-minute product news and technical support information. The site’s URL is:

http://www.sun.com

1.7 Documentation Feedback

We appreciate your feedback. Please send any comments or suggestions regarding this document to:

CAPS_docsfeedback@sun.com

HTTPS eWay Adapter User’s Guide 14 Sun Microsystems, Inc.

Installing the HTTPS eWay

What’s in This Chapter

 HTTPS eWay System Requirements on page 15

 Installing the HTTPS eWay on page 15

 ICAN 5.0 Project Migration Procedures on page 17

 Installing Enterprise Manager eWay Plug-Ins on page 19

2.1 HTTPS eWay System Requirements

The HTTPS eWay Readme contains the latest information on:

 Supported Operating Systems

 System Requirements

Chapter 2

 External System Requirements

The HTTPS eWay Readme is uploaded with the eWay’s documentation file (HTTPeWayDocs.sar) and can be accessed from the Documentation tab of the Sun Java Composite Application Platform Suite Installer. Refer to the HTTPS eWay Readme for the latest requirements before installing the HTTPS eWay.

2.2 Installing the HTTPS eWay

The Sun Java Composite Application Platform Suite Installer, a web-based application, is used to select and upload eWays and add-on files during the installation process. The following section describes how to install the components required for this eWay.

Note: When the Repository is running on a UNIX operating system, the eWays are loaded

from the Sun Java Composite Application Platform Suite Installer running on a Windows platform connected to the Repository server using Internet Explorer.

HTTPS eWay Adapter User’s Guide 15 Sun Microsystems, Inc.

Chapter 2 Section 2.2

Installing the HTTPS eWay Installing the HTTPS eWay

2.2.1 Installing the HTTPS eWay on an eGate supported system

Follow the directions for installing the Sun Java Composite Application Platform Suite (CAPS).

After you have installed eGate or eInsight, do the following:

1 From the Enterprise Manager’s ADMINISTRATION tab, click on license in the

Sun Java Composite Application Platform Suite Products Installed table. The Sun Java Composite Application Platform Suite Web Installer appears.

2 From Select Sun Java Composite Application Platform Suite Products to Install,

select the products for your Sun Java Composite Application Platform Suite and include the following:

 FileeWay (the File eWay is used by most sample Projects)

 HTTPeWay

To upload the Sun SeeBeyond eWay™ HTTPS Adapter User’s Guide, Help file, Javadoc, Readme, and sample Projects, select the following:

 HTTPeWayDocs

3 Once you have selected all of your products, click Next in the top-right or bottom-

right corner of the Select Sun Java Composite Application Platform Suite Products to Install box.

4 From the Selecting Files to Install box, locate and select your first product’s SAR

file. Once you have selected the SAR file, click Next. Follow this procedure for each of your products. The Installing Files window appears after the last SAR file has been selected.

5 From the Installing Files window, review the product list. If it is correct, Click

Install Products. The Enterprise Manager starts the installation.

6 When your product’s installation is completed, click on the prompt, “When

installation completes, click here to continue.”

7 Continue installing the eGate Integrator as instructed in the Sun Java Composite

Application Platform Suite Installation Guide.

Adding the eWay to an Existing Sun Java Composite Application Platform Suite Installation

It is possible to add the eWay to an existing Sun Java Composite Application Platform Suite installation.

Steps required to add an eWay to an Existing CAPS installation include:

1 Complete steps 1 through 6 on “Installing the HTTPS eWay on an eGate

supported system” on page 15.

2 Open the Enterprise Designer and select Update Center from the Tools menu. The

Update Center Wizard appears.

3 For Step 1 of the wizard, simply click Next.

HTTPS eWay Adapter User’s Guide 16 Sun Microsystems, Inc.

Chapter 2 Section 2.2

Installing the HTTPS eWay Installing the HTTPS eWay

4 For Step 2 of the wizard, click the Add All button to move all installable files to the

Include in Install field, then click Next.

5 For Step 3 of the wizard, wait for the modules to download, then click Next.

6 The wizard’s Step 4 window displays the installed modules. Review the installed

modules and click Finish.

7 When prompted, restart the IDE (Integrated Development Environment) to

complete the installation.

After Installation

Once you install the eWay, it must then be incorporated into a Project before it can perform its intended functions. See the eGate Integrator User’s Guide for more information on incorporating the eWay into an eGate Project.

2.2.2 Extracting the Sample Projects and Javadocs

The HTTPS eWay includes sample Projects and Javadocs. The sample Projects are designed to provide you with a basic understanding of how certain database operations are performed using the eWay, while Javadocs provide a list of classes and methods exposed in the eWay.

Steps to extract the Javadoc include:

1 Click the Documentation tab of the Sun Java Composite Application Platform Suite

Installer, then click the Add-ons tab.

2 Click the HTTPS eWay Adapter link. Documentation for the HTTPS eWay appears

in the right pane.

3 Click the icon next to Javadoc and extract the ZIP file.

4 Open the index.html file to view the Javadoc.

Steps to extract the Sample Projects include:

1 Click the Documentation tab of the Sun Java Composite Application Platform Suite

Installer, then click the Add-ons tab.

2 Click the HTTPS eWay Adapter link. Documentation for the HTTPS eWay appears

in the right pane.

3 Click the icon next to Sample Projects and extract the ZIP file. Note that the

HTTPS_eWay_Sample.zip file contains two additional ZIP files for each sample

Project.

Refer to “Importing a Sample Project” on page 58 for instructions on importing the sample Project into your repository via the Enterprise Designer.

HTTPS eWay Adapter User’s Guide 17 Sun Microsystems, Inc.

Chapter 2 Section 2.3

Installing the HTTPS eWay ICAN 5.0 Project Migration Procedures

2.3 ICAN 5.0 Project Migration Procedures

This section describes how to transfer your current ICAN 5.0.x Projects to the Sun Java Composite Application Platform Suite 5.1.1. To migrate your ICAN 5.0.x Projects to the Sun Java Composite Application Platform Suite 5.1.1, do the following:

Export the Project

1 Before you export your Projects, save your current ICAN 5.0.x Projects to your

Repository.

2 From the Project Explorer, right-click your Project and select Export from the

shortcut menu. The Export Manager appears.

3 Select the Project that you want to export in the left pane of the Export Manager and

move it to the Selected Projects field by clicking the Add to Select Items (arrow) button, or click All to include all of your Projects.

4 In the same manner, select the Environment that you want to export in the left pane

of the Export Manager and move it to the Selected Environments field by clicking the Add to Select Items (arrow) button, or click All to include all of your Environments.

5 Browse to select a destination for your Project ZIP file and enter a name for your

Project in the ZIP file field.

6 Click Export to create the Project ZIP file in the selected destination.

Install Java CAPS 5.1.1

1 Install the Java CAPS 5.1.1, including all eWays, libraries, and other components

used by your ICAN 5.0 Projects.

2 Start the Java CAPS 5.1.1 Enterprise Designer.

Import the Project

1 From the Java CAPS 5.1.1 Enterprise Designer’s Project Explorer tree, right-click the

Repository and select Import Project from the shortcut menu. The Import Manager appears.

2 Browse to and select your exported Project file.

3 Click Import. A warning message, “Missing APIs from Target Repository,” may

appear at this time. This occurs because various product APIs were installed on the ICAN 5.0 Repository when the Project was created, that are not installed on the Java CAPS 5.1.1 Repository. These APIs may or may not apply to your Projects. You can ignore this message if you have already installed all of the components that correspond to your Projects. Click Continue to resume the Project import.

4 Close the Import Manager after the Project is successfully imported.

Deploy the Project

1 A new Deployment Profile must be created for each of your imported Projects.

When a Project is exported, the Project’s components are automatically “checked in” to Version Control to write-protected each component. These protected components appear in the Explorer tree with a red padlock in the bottom-left corner of each icon.

HTTPS eWay Adapter User’s Guide 18 Sun Microsystems, Inc.

Chapter 2 Section 2.4

Installing the HTTPS eWay Installing Enterprise Manager eWay Plug-Ins

Before you can deploy the imported Project, the Project’s components must first be “checked out” of Version Control from both the Project Explorer and the Environment Explorer. To “check out” all of the Project’s components, do the following:

A From the Project Explorer, right-click the Project and select Version Control >

Check Out from the shortcut menu. The Version Control - Check Out dialog box

appears.

B Select Recurse Project to specify all components, and click OK.

C Select the Environment Explorer tab, and from the Environment Explorer, right-

click the Project’s Environment and select Version Control > Check Out from the shortcut menu.

D Select Recurse Environment to specify all components, and click OK.

2 If your imported Project includes File eWays, these must be reconfigured in your

Environment prior to deploying the Project.

To reconfigure your File eWays, do the following:

A From the Environment Explorer tree, right-click the File External System, and

select Properties from the shortcut menu. The Properties Editor appears.

B Set the inbound and outbound directory values, and click OK. The File External

System can now accommodate both inbound and outbound eWays.

3 Deploy your Projects.

Note: Only projects developed on ICAN 5.0.2 and later can be imported and migrated

successfully into the Java Composite Application Platform Suite.

2.4 Installing Enterprise Manager eWay Plug-Ins

The Sun SeeBeyond Enterprise Manager is a Web-based interface you use to monitor and manage your Java Composite Application Platform Suite applications. The Enterprise Manager requires an eWay specific “plug-in” for each eWay you install. These plug-ins enable the Enterprise Manager to target specific alert codes for each eWay type, as well as start and stop the inbound eWays.

The Sun Java Composite Application Platform Suite Installation Guide describes how to install Enterprise Manager. The Sun SeeBeyond eGate Integrator System Administration Guide describes how to monitor servers, Services, logs, and alerts using the Enterprise Manager and the command-line client.

The eWay Enterprise Manager Plug-ins are available from the List of Components to

Download under the Sun Java Composite Application Platform Suite Installer’s DOWNLOADS tab.

There are two ways to add eWay Enterprise Manager plug-ins:

 From the Sun SeeBeyond Enterprise Manager

 From the Sun Java Composite Application Platform Suite Installer

HTTPS eWay Adapter User’s Guide 19 Sun Microsystems, Inc.

Chapter 2 Section 2.4

Installing the HTTPS eWay Installing Enterprise Manager eWay Plug-Ins

To add plug-ins from the Enterprise Manager

1 From the Enterprise Manager’s Explorer toolbar, click configuration.

2 Click the Web Applications Manager tab, go to the Auto-Install from Repository

sub-tab, and connect to your Repository.

3 Select the application plug-ins you require, and click Install. The application plug-

ins are installed and deployed.

To add plug-ins from the Sun Java Composite Application Platform Suite Installer

1 From the Sun Java Composite Application Platform Suite Installer’s Download

tab, select the Plug-Ins you require and save them to a temporary directory.

2 From the Enterprise Manager’s Explorer toolbar, click configuration.

3 Click the Web Applications Manager tab and go to the Manage Applications sub-

tab.

4 Browse for and select the WAR file for the application plug-in that you

downloaded, and click Deploy. The plug-ins is installed and deployed.

2.4.1 Viewing Alert Codes

You can view and delete alerts using the Enterprise Manager. An alert is triggered when a specified condition occurs in a Project component. The purpose of the alert is to warn the administrator or user that a condition has occurred.

To View the eWay Alert Codes

1 Add the eWay Enterprise Manager plug-in for this eWay.

2 From the Enterprise Manager’s Explorer toolbar, click configuration.

3 Click the Web Applications Manager tab and go to the Manage Alert Codes sub-

tab. Your installed eWay alert codes display under the Results section. If your eWay alert codes are not displayed under Results, do the following:

A From the Install New Alert Codes section, browse to and select the eWay alert

properties file for the application plug-in that you added. The alert properties files are located in the alertcodes folder of your Sun Java Composite Application Platform Suite installation directory.

B Click Deploy. The available alert codes for your application are displayed under

Results. A listing of the eWay’s available alert codes is displayed in Table 2.

Tabl e 2 HTTPS eWay Alert Codes

Alert Code Description User Action

HTTPCLIENTEWAY-CONFIGFAILED000001=Configuration error encountered for HTTP Client eWay.

HTTPS eWay Adapter User’s Guide 20 Sun Microsystems, Inc.

Occurs if there your project deployment parameters are invalid.

Connectivity Map and External configuration information is invalid. Verify configured parameters.

Chapter 2 Section 2.4

Installing the HTTPS eWay Installing Enterprise Manager eWay Plug-Ins

Alert Code Description User Action

HTTPCLIENTEWAY-CONNECTFAILED000002=Failed to prepare the HTTP Client agent for establishing the connection to the HTTP server.

HTTPCLIENTEWAY-GETFAILED000004=Failed on HTTP GET request to URL {0}.

HTTPCLIENTEWAY-POSTFAILED000005=Failed on HTTP POST request to URL {0}.

HTTPCLIENTEWAY-URLFAILED000003=Invalid URL specified {0}.

HTTPSERVEREWAY-REQUESTFAILED000001=Failed to process the POST or GET request.

Occurs when a socket connection does not exist.

Occurs when an HTTPS operation is not successful.

Occurs when an invalid URL is entered.

Occurs when an HTTPS operation is not successful.

Verify that network connectivity is available.

 Read the response code in

the collaboration and proceed accordingly.

 Run the operation from a

web browser.

 Read the response code in

the collaboration and proceed accordingly.

 Run the operation from a

web browser.

Verify that the URL is correct.

 Read the response code in

the collaboration and proceed accordingly.

 Verify that the HTTP Server is

running.

For information on Managing and Monitoring alert codes and logs, as well as how to view the alert generated by the project component during runtime, see the Sun SeeBeyond eGate™ Integrator System Administration Guide.

Note: An alert code is a warning that an error has occurred. It is not a diagnostic. The user

actions noted above are just some possible corrective measures you may take. Refer to the log files for more information. For information on Managing and Monitoring alert codes and logs, see the Sun SeeBeyond eGate Integrator System Administration Guide.

HTTPS eWay Adapter User’s Guide 21 Sun Microsystems, Inc.

Understanding the HTTPS eWay OTD

This chapter provides an overview of OTDs and describes the HTTPS eWay’s Object Type Definition (OTD) structure.

What’s in This Chapter

 Overview of eWay OTDs on page 22

 HTTPS Client OTD on page 22

3.1 Overview of eWay OTDs

An OTD contains a set of rules that define an object. The object encodes data as it travels through eGate. OTDs are used as the basis for creating a Java-based Collaboration Definition for a Project.

Each OTD acts as a template with a unique set of eWay features. The HTTPS eWay OTD template is not customizable and cannot be edited.

Chapter 3

The basic parts of an OTD are:

 Element: This is the highest level in the OTD tree. The element is the basic

container that holds the other parts of the OTD. The element can contain fields and methods.

 Field: Fields are used to represent data. A field can contain data in any of the

following formats: string, boolean, int, double, or float.

 Method: Method nodes represent actual Java methods.

 Parameters: Parameters nodes represent the Java methods’ parameters.

Note: For complete information on the methods contained in the HTTPS eWay OTDs,

refer to the Javadoc provided with the eWay documentation in the Enterprise Manager.

3.2 HTTPS Client OTD

The HTTPS OTD is specific to the HTTPS eWay. It is used as an inbound or outbound OTD in a Collaboration.

HTTPS eWay Adapter User’s Guide 22 Sun Microsystems, Inc.

Chapter 3 Section 3.3

Understanding the HTTPS eWay OTD HTTPS Server OTD

OTDs have a tree-like hierarchical data structure composed of fields containing methods and properties.

The top root element of the OTD is the HTTPClientApplication interface, and the fields underneath contain Java methods. You can use these Java methods to create Business Rules that specify the HTTP message format and invoke messaging to and/or from an HTTP server.

To access other Java classes and methods, you can use the Collaboration Editor (Java) to utilize the entire contents available for HTTPClientApplication.

3.2.1 HTTP OTD Method Descriptions

The HTTP OTD includes the following methods used in HTTP data exchange:

get

The method called in the Collaboration (Java) to send an HTTP get request to an HTTP server.

post

The method called in the Collaboration (Java) to send an HTTP post request to an HTTP server.

getRequest

The method called in the Collaboration (Java) for other “request” related helper methods, such as to set the URL, to add properties, etc.

getResult

The method called in the Collaboration (Java) for other “respond” related helper methods, such as, to obtain the respond code, respond result, text result, and so on.

For more information on methods available in the HTTP OTDs, see the HTTPS eWay’s Javadoc.

3.3 HTTPS Server OTD

The HTTPS Server input OTD has two nodes, Request and Response. The Request node contains the data that the HTTPS Server eWay receives from an HTTP client, while the Response node is used to set the HTTP response data that will be sent back to the HTTP client.

Figure 3 Input Server OTD

HTTPS eWay Adapter User’s Guide 23 Sun Microsystems, Inc.

Chapter 3 Section 3.3

Understanding the HTTPS eWay OTD HTTPS Server OTD

Figure 4 Input Server Request Node

HTTPS eWay Adapter User’s Guide 24 Sun Microsystems, Inc.

Chapter 3 Section 3.3

Understanding the HTTPS eWay OTD HTTPS Server OTD

Figure 5 Input Server Response Node

Working with the Server OTD

Use the OTDs Request and Response nodes to build the logic in your HTTPS Collaborations. The HTTP response is not sent back to the HTTP client until sendResponse() method is called on the HTTP server input OTD.

Figure 6 sendResponse() Method

It is critical that you use this method to send the response back to the client. Otherwise, the client will wait indefinitely for the response. HTTP requires that a response be sent to the client whether the response is a valid application response or an application error response.

HTTPS eWay Adapter User’s Guide 25 Sun Microsystems, Inc.

Chapter 3 Section 3.3

Understanding the HTTPS eWay OTD HTTPS Server OTD

Collaboration Example

The following example shows a simple Java Collaboration that retrieves the HTTP method from the Request node via the Method property, creates an HTML response indicating the HTTP method retrieved from the request, sets the ContentType property as “text/html” on the Response node, sets the Text property with the HTML response, and then calls the sendResponse() method on the HTTP server input OTD to send the constructed response to the HTTP client.

Figure 7 sendResponse() Example

HTTPS eWay Adapter User’s Guide 26 Sun Microsystems, Inc.

Operating SSL

This chapter explains the operation of the Secure Sockets Layer (SSL) feature available with the HTTP(S) eWay.

What’s in This Chapter

 Overview on page 27

 KeyStores and TrustStores on page 29

 SSL Handshaking on page 33

 Using the OpenSSL Utility on page 36

4.1 Overview

The use of SSL with HTTP, here called HTTPS, enables HTTP data exchanges that are secure from unauthorized interception from “hackers” or other entities. The eWay’s SSL feature provides a secure communications channel for the data exchanges (see Figure

8).

Chapter 4

HTTPS eWay Adapter User’s Guide 27 Sun Microsystems, Inc.

Chapter 4 Section 4.1

Operating SSL Overview

Figure 8 General SSL Operation: HTTPS

Man-in-Middle Attack:

Cannot break secured channel

HTTP(S) eWay

TrustStore KeyStore

Trusted CA Certificates

Hacker

POST / GET

Response

SSL Communication Channel

Private

Key

Certificate &

CA Certificate

Chain

Web Server

This SSL feature is supported through the use of JSSE version 1.0.3.

Currently, the JSSE reference implementation is used. JSSE is a provider-based architecture, meaning that there is a set of standard interfaces for cryptographic algorithms, hashing algorithms, secured-socket-layered URL stream handlers, and so on.

Because the user is interacting with JSSE through these interfaces, the different components can be mixed and matched as long as the implementation is programmed under the published interfaces. However, some implementations may not support a particular algorithm.

The JSSE 1.0.3 application programming interface (API) is capable of supporting SSL versions 2.0 and 3.0 and Transport Layer Security (TLS) version 1.0. These security protocols encapsulate a normal bidirectional stream socket and the JSSE 1.0.3 API adds transparent support for authentication, encryption, and integrity protection. The JSSE reference implementation implements SSL version 3.0 and TLS 1.0.

For more information, visit the Sun Java Web site at the following URL:

http://java.sun.com

Note: See the JSSE documentation provided by Sun Microsystems for further details.

HTTPS eWay Adapter User’s Guide 28 Sun Microsystems, Inc.

Chapter 4 Section 4.2

Operating SSL KeyStores and TrustStores

4.2 KeyStores and TrustStores

As depicted in Figure 8, JSSE makes use of files called KeyStores and TrustStores. The KeyStore is used by the eWay for client authentication, while the TrustStore is used to authenticate a server in SSL authentication.

 A KeyStore consists of a database containing a private key and an associated

certificate, or an associated certificate chain. The certificate chain consists of the client certificate and one or more certification authority (CA) certificates.

 A TrustStore contains only the certificates trusted by the client (a “trust” store).

These certificates are CA root certificates, that is, self-signed certificates. The installation of the Logical Host includes a TrustStore file named cacerts.jks in the location:

<c:\JavaCAPS>\logicalhost\is\domains\<MyDomain>\config

where <c:\JavaCAPS> is the directory where the Sun Java Composite Application Platform Suite is installed and <MyDomain> is the name of your domain. This file is recommended as the TrustStore for the HTTPS eWay.

Both KeyStores and TrustStores are managed by means of a utility called keytool, which is a part of the Java SDK installation.

4.2.1 Generating a KeyStore and TrustStore

This section explains steps on how to create both a KeyStore and a TrustStore (or import a certificate into an existing TrustStore such as the default Logical Host TrustStore in the location:

<c:\JavaCAPS>\logicalhost\is\domains\<MyDomain>\config\cacert s.jks

where <c:\JavaCAPS> is the directory where the Sun Java Composite Application Platform Suite is installed and <MyDomain> is the name of your domain. The primary tool used is keytool, but openssl is also used as a reference for generating pkcs12 KeyStores.

For more information on openssl, and available downloads, visit the following Web site:

http://www.openssl.org.

4.2.2 KeyStores

This section explains how to use KeyStores.

Creating a KeyStore in JKS Format

This section explains how to create a KeyStore using the JKS format as the database format for both the private key, and the associated certificate or certificate chain. By default, as specified in the java.security file, keytool uses JKS as the format of the key and certificate databases (KeyStore and TrustStores). A CA must sign the certificate

HTTPS eWay Adapter User’s Guide 29 Sun Microsystems, Inc.

Chapter 4 Section 4.2

Operating SSL KeyStores and TrustStores

signing request (CSR). The CA is therefore trusted by the server-side application to which the eWay is connected.

Note: It is recommended to use the default KeyStore

<c:\JavaCAPS>\logicalhost\is\domains\<MyDomain>\config\k eystore.jks where <c:\JavaCAPS> is the directory where the Sun Java

Composite Application Platform Suite is installed and <MyDomain> is the name of your domain.

To generate a KeyStore

Use the following command:

keytool -keystore clientkeystore -genkey -alias client

You are prompted for several pieces of information required to generate a CSR. A sample key generation section follows:

Enter keystore password: seebyond What is your first and last name? [Unknown]: development.seebeyond.com What is the name of your organizational unit? [Unknown]: Development what is the name of your organization? [Unknown]: SeeBeyond What is the name of your City of Locality? [Unknown]: Monrovia What is the name of your State or Province? [Unknown]: California What is the two-letter country code for this unit? [Unknown]: US Is<CN=Foo Bar, OU=Development, O=SeeBeyond, L=Monrovia, ST=California, C=US> correct? [no]: yes

Enter key password for <client>

(RETURN if same as keystore password):

If the KeyStore password is specified, then the password must be provided for the eWay. Press RETURN when prompted for the key password (this action makes the key password the same as the KeyStore password).

This operation creates a KeyStore file clientkeystore in the current working directory. You must specify a fully-qualified domain for the “first and last name” question. The reason for this use is that some CAs such as Verisign expect this properties to be a fully qualified domain name.

There are CAs that do not require the fully qualified domain, but it is recommended to use the fully-qualified domain name for the sake of portability. All the other information given must be valid. If the information can not be validated, a CA such as Verisign does not sign a generated CSR for this entry.

This KeyStore contains an entry with an alias of client. This entry consists of the Generated private key and information needed for generating a CSR as follows:

keytool -keystore clientkeystore -certreq alias client -keyalg rsa

-file client.csr

HTTPS eWay Adapter User’s Guide 30 Sun Microsystems, Inc.

+ 84 hidden pages

Sun Microsystems 5.1.1 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Introducing the HTTPS eWay

1.1 About HTTP and HTTPS

1.2 About the HTTPS eWay

1.2.1 HTTP Messages

1.2.2 Web Browser Cookies

Cookie Expiration Date Checking

1.2.3 GET and POST Methods

1.2.4 Sample HTTP Exchange in Client Mode

1.2.5 Sample HTTP Exchange in Server Mode

1.3 What’s New in This Release

1.4 About This Document

HTTPS eWay Javadoc

1.4.1 Scope

1.4.2 Intended Audience

1.4.3 Text Conventions

1.5 Related Documents

1.6 Sun Microsystems, Inc. Web Site

1.7 Documentation Feedback

Installing the HTTPS eWay

2.1 HTTPS eWay System Requirements

2.2 Installing the HTTPS eWay

2.2.1 Installing the HTTPS eWay on an eGate supported system

Adding the eWay to an Existing Sun Java Composite Application Platform Suite Installation

After Installation

2.2.2 Extracting the Sample Projects and Javadocs

2.3 ICAN 5.0 Project Migration Procedures

2.4 Installing Enterprise Manager eWay Plug-Ins

2.4.1 Viewing Alert Codes

Understanding the HTTPS eWay OTD

3.1 Overview of eWay OTDs

3.2 HTTPS Client OTD

3.2.1 HTTP OTD Method Descriptions

3.3 HTTPS Server OTD

Operating SSL

4.1 Overview

4.2 KeyStores and TrustStores

4.2.1 Generating a KeyStore and TrustStore

4.2.2 KeyStores

Creating a KeyStore in JKS Format