CPM Setup Guide
CyberSource
Payment Manager™ 6.0
Setup Guide
January 2006
CyberSource Contact Information
For questions about CyberSource Payment Manager, email
[email protected]
For general information about our company, products, and services, go to
http://www.cybersource.com.
For sales questions about any CyberSource Service, email [email protected] or call
650-965-6000 or 888-330-2300 (toll-free in the United States).
For support information about any CyberSource service, visit the Support Center at
http://www.cybersource.com/support.
Copyright
© 2006 CyberSource Corporation. All rights reserved. CyberSource Corporation ("CyberSource")
furnishes this document and the software described in this document under the applicable
agreement between the reader of this document ("You") and CyberSource ("Agreement"). You may
use this document and/or software only in accordance with the terms of the Agreement. Except as
expressly set forth in the Agreement, the information contained in this document is subject to
change without notice and therefore should not interpreted in any way as a guarantee or warranty
by CyberSource. CyberSource assumes no responsibility or liability for any errors that may appear
in this document. The copyrighted software that accompanies this document is licensed to You for
use only in strict accordance with the Agreement. You should read the Agreement carefully before
using the software. Except as permitted by the Agreement, You may not reproduce any part of this
document, store this document in a retrieval system, or transmit this document, in any form or by
any means, electronic, mechanical, recording, or otherwise, without the prior written consent of
CyberSource.
Restricted Rights Legends
For Government or defense agencies. Use, duplication, or disclosure by the Government or defense
agencies is subject to restrictions as set forth the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013 and in similar clauses in the FAR and NASA FAR Supplement.
For civilian agencies. Use, reproduction, or disclosure is subject to restrictions set forth in
subparagraphs (a) through (d) of the Commercial Computer Software Restricted Rights clause at
52.227-19 and the limitations set forth in CyberSource Corporation's standard commercial
agreement for this software. Unpublished rights reserved under the copyright laws of the United
States.
Trademarks
CyberSource, the Power Behind the Buy Button, the CyberSource logo, SmartCert, and PaylinX are
registered trademarks of CyberSource Corporation in the U.S. and other countries. The Power of
Payment, CyberSource Payment Manager, CyberSource Risk Manager, CyberSource Decision
Manager, and CyberSource Connect are trademarks and/or service marks of CyberSource
Corporation. All other brands and product names are trademarks or registered trademarks of their
respective owners.
CPM Setup Guide • CyberSource Corporation • January 2006
ii
Contents
Documentation Changes............................................................................................................. vi
Chapter 1
Introduction to CPM......................................................................................................................1
Guide Overview ..............................................................................................................................1
CPM Components ...........................................................................................................................1
CPM Server ...............................................................................................................................1
CPM Administration Server ...................................................................................................2
CPM Administration Client....................................................................................................2
CPM Windows Client..............................................................................................................2
CPM Client APIs ......................................................................................................................2
CPM Architecture ....................................................................................................................2
Chapter 2
System Requirements and Installation Checklist ...................................................................4
System Requirements for Windows .............................................................................................4
Administration and Server Hardware ..................................................................................4
Administration and Server Software ....................................................................................4
Database Requirements...........................................................................................................5
System Requirements for Unix......................................................................................................5
Server Hardware ......................................................................................................................5
Server Software.........................................................................................................................5
Database Requirements...........................................................................................................6
CPM Installation Checklist ............................................................................................................6
Setting Up the Server for the CPM Environment................................................................6
Setting Up the Communication Connection ........................................................................7
Installing Required Auxiliary Software ................................................................................7
Setting Up the Database Machine..........................................................................................7
Installing the CPM Server Software ......................................................................................8
Preparing the CPM Server Database.....................................................................................9
Setting Up Your Payment Gateways.....................................................................................9
Setting Up Transaction Security...........................................................................................10
Testing the CPM Server.........................................................................................................10
Chapter 3
Setting Up the ODBC-Compliant Database ...........................................................................11
Sizing the CPM Database .............................................................................................................11
Setting Up the Database for Windows .......................................................................................11
CPM Setup Guide • CyberSource Corporation • January 2006
iii
Contents
Setting Up the CPM Data Source Name .............................................................................12
Creating a CPM Data Source.........................................................................................12
Microsoft SQL Server Considerations..........................................................................13
Oracle Considerations ....................................................................................................14
Installing Windows Administration Tools.........................................................................14
Setting Up the Database for Solaris ............................................................................................14
OpenLink Overview ..............................................................................................................14
Obtaining the OpenLink License .........................................................................................15
Installing the OpenLink Server Component ......................................................................16
Modifying the Environment Variables ...............................................................................17
Setting Up the OpenLink Client on the CPM Server ........................................................17
Setting Up the CPM Data Source Name .............................................................................18
Testing the DSN Connection ................................................................................................19
Creating Database Tables......................................................................................................19
Chapter 4
Installing CPM Server Software................................................................................................20
About Installing CPM Software ..................................................................................................20
Creating and Managing Administrator Accounts....................................................................21
Default Administrator Account ...........................................................................................22
Using the AcctMaint.exe Tool to Manage Administrators ..............................................22
Handling a Lockout Due to Failed Attempts.....................................................................23
Handling a Lockout Due to Inactivity ................................................................................23
Installing CPM Software on Windows.......................................................................................23
Installing CPM Software on Unix ...............................................................................................28
Installing the Administration Client ...................................................................................28
Installing the CPM Server Software ....................................................................................29
Setting Up CPM and the CPM Manager to Start with the Solaris System ....................32
Uninstalling CPM for Unix...................................................................................................33
Setting Up the FTP Tool for the NOVA Gateway ....................................................................33
Setting Up CPM Security..............................................................................................................34
Setting Up SSL ...............................................................................................................................35
Setting Up SSL for the First Time ........................................................................................35
Replacing the SSL Encryption Key ......................................................................................40
Installing the CPM Client in Call Centers..................................................................................41
Chapter 5
Using Multiple Servers ...............................................................................................................43
Setting Up the Servers ..................................................................................................................43
Database Encryption Key......................................................................................................43
Administrator Passwords and the cpm_admin File .........................................................44
Setting Up the Merchant Configuration ....................................................................................44
Setting Up the Gateway Configuration......................................................................................44
Configuring for Settlement ..........................................................................................................45
Setting Up the Database Aging Parameters ..............................................................................47
CPM Setup Guide • CyberSource Corporation • January 2006
iv
Contents
Chapter 6
Upgrading from a Previous Version.........................................................................................48
Upgrading from a 5.x Version .....................................................................................................48
For Unix ...................................................................................................................................48
For Windows...........................................................................................................................51
Upgrading from a 4.x or 3.x Version ..........................................................................................53
Choosing an Upgrade Strategy ............................................................................................54
Installing New Software and Database Tables ...........................................................54
Upgrading Existing Software and Database Tables ..................................................54
Summary of Upgrade Factors .......................................................................................55
Before Starting the Upgrade .................................................................................................56
Upgrading the Software........................................................................................................56
Installing New Software and Database Tables ...........................................................56
Upgrading Existing Software and Database Tables ..................................................59
Chapter 7
Using the Java SDK and SSL Proxy Server .............................................................................62
For All Java SDK Users: Updating the Security Policy Files...................................................62
For Windows...........................................................................................................................62
For Solaris................................................................................................................................63
For Users of Previous Versions of the Java SDK.......................................................................63
Installing the SSL Proxy Server ...................................................................................................63
Windows..................................................................................................................................63
Starting the Service .........................................................................................................66
Ports ..................................................................................................................................66
Solaris.......................................................................................................................................66
Updating Your Java Installation for Strong Encryption............................................67
Starting the Service .........................................................................................................68
Ports ..................................................................................................................................68
Keystore Management..................................................................................................................69
Using the Default Keystore Files .........................................................................................69
Recreating the Default Keystore Files .................................................................................69
Creating Unique Keystores for Each SDK Instance ..........................................................70
Configuration.................................................................................................................................71
Proxy Server System Properties ...........................................................................................71
SDK System Properties..........................................................................................................72
Setting the Properties.............................................................................................................72
Windows ..........................................................................................................................72
Solaris................................................................................................................................73
Troubleshooting.............................................................................................................................74
Index ...............................................................................................................................................77
CPM Setup Guide • CyberSource Corporation • January 2006
v
Documentation Changes
The following table lists changes made in the last six releases of this document:
Release
Changes
6.0
•
•
•
Updated the CPM version number to 6.0.
•
Updated the software installation instructions. See Installing CPM Software on Windows
on page 23 and Installing CPM Software on Unix on page 28.
•
Updated the software upgrade procedures. See Upgrading from a Previous Version on
page 48.
•
Added a new section about setting up CPM Security. See Setting Up CPM Security on
page 34
•
•
Added a new section about setting up SSL. See Setting Up SSL on page 35.
•
•
Updated the CPM version number to 5.8.
5.7
•
Updated the CPM version number to 5.7.
5.6.5
•
Updated the CPM version number to 5.6.5.
5.6.4
•
Clarified the general steps for setting up the database machine. See Setting Up the
Database Machine on page 7.
•
Added information about setting the database aging parameters when you are using
multiple CPM Servers. See Setting Up the Database Aging Parameters on page 47.
•
Updated the CPM version number to 5.6.3.
5.8
5.6.3
Updated the installation checklist. See CPM Installation Checklist on page 6.
Added a new section about administrator account management. See Creating and
Managing Administrator Accounts on page 21.
Removed mention of Windows NT as it is not supported for CPM 6.0.
Added a troubleshooting section to the Java SSL Proxy Server chapter. See
Troubleshooting on page 74.
CPM Setup Guide • CyberSource Corporation • January 2006
vi
Chapter 1
Introduction to CPM
This chapter presents an overview of the components, architecture, features, and
functions of the CyberSource Payment Manager (CPM) Server.
Guide Overview
The CPM Setup Guide provides instruction on installing, setting up, and testing the CPM
Server. Setup includes administrative components of the CPM, such as the database.
The users of this guide should have comprehensive knowledge of the following:
•
Operating system administration (Windows® Server 2000/2003 or Sun
Microsystems®)
•
•
•
Database administration (SQL Server, Oracle, Sybase, or DB2)
Network administration
Security administration
CPM Components
The following sections describe the components of CPM.
CPM Server
The CPM Server is the core of the CPM system and provides all traditional credit card
processing operations including the management of authorizations, settlements, and
reporting. The CPM Server takes advantage of the Windows and Sun Solaris client-server
environment to establish username and password security for setting up permission
levels to the CPM Server.
CPM Setup Guide • CyberSource Corporation • January 2006
1
Chapter 1 Introduction to CPM
CPM Components
The CPM Server runs as a Windows or Sun Solaris service and is the core of the CPM
system. The CPM Server provides high-speed payment processing with the ability to
handle multiple transactions simultaneously.
CPM Administration Server
The CPM Administration Server runs on the same machines as the CPM server and
provides an administrative interface to remotely start and stop the CPM server, as well as
to query the CPM Error/Status log.
CPM Administration Client
The CPM Administration Client runs on any Windows Server 2000/2003 machine with
TCP/IP connectivity to the CPM server machine. The CPM Administration Client is a
graphical administration tool that is used to configure, monitor, and control the CPM
server. The CPM Administration Client communicates with the CPM server and with the
CPM Administration Server via TCP/IP. It can be used to remotely administer CPM over
a local LAN or the Internet.
CPM Windows Client
The CPM Windows Client is a graphical client application for the CPM Server that runs on
Windows workstations. This optional component enables organizations to test the CPM
installation without having to write a program that uses the CPM API.
CPM Client APIs
The CPM Client APIs supply the resources to develop custom client applications to
interact with the CPM Server. These APIs include ActiveX in VB, Windows DLLs, Java
SDKs, and Sun shared objects.
CPM Architecture
The CPM architecture allows for a wide variety of configurations, from a very simple
single server with one processor connection to multiple servers with multiple processor
connections. Multiple servers and processors enable increased throughput and reliability
through redundancy.
CPM Setup Guide • CyberSource Corporation • January 2006
2
Chapter 1 Introduction to CPM
CPM Components
The following figure illustrates the most basic recommended CPM configuration.
Client Application
CPM Admin Client
Router
Frame to Processor
LAN
Database
Server
CPM Server
CPM Admin Server
Firewall
Internet
SSL to Processor
Client Application
CPM Admin Client
The client applications in the diagram include point of sale (POS) terminals or
applications, Web store fronts, or IVR systems. All communications between client
applications and the CPM server use the CPM API libraries and are encrypted with the
Blowfish encryption algorithm using a 448-bit key. For additional security, client
applications should use SSL to communicate with the CPM server.
The database server in the diagram may be any of those listed in the requirements section
of this document. See Database Requirements on page 5.
The CPM Server communicates with the financial processor through a frame connection,
or, in some cases, through a SSL connection involving the Internet.
The CPM Server is configured and controlled using the CPM Administration Client. A
single CPM Administration Client can control multiple CPM servers.
Multiple CPM Servers can be included to build redundant or higher throughput systems.
When multiple CPM Servers are used in a configuration it is recommended that only one
of the servers be configured to settle (for example, configure all but one server as AuthOnly servers).
CPM Setup Guide • CyberSource Corporation • January 2006
3
Chapter 2
System Requirements and Installation
Checklist
This chapter includes:
System Requirements for Windows
System Requirements for Unix
CPM Installation Checklist
The checklist is a general list of the items you need to perform. It refers you to more
detailed instructions in the subsequent chapters.
System Requirements for Windows
Administration and Server Hardware
•
•
•
•
•
•
Intel Pentium Processor (minimum 400 MHz recommended)
Minimum 128 MB RAM suggested (additional RAM may be required depending
on transaction volume)
Hard disk drive with at least 9 GB of available, uncompressed space
Dual-speed CD-ROM drive or higher
SVGA monitor
Network interface card (NIC) installed and connected to the network
Administration and Server Software
•
Microsoft Windows 2000 Server, Service Pack 1 or later, or
Windows 2000 Advanced Server, Service Pack 1 or later, or
Windows 2003 Server
CPM Setup Guide • CyberSource Corporation • January 2006
4
Chapter 2 System Requirements and Installation Checklist
•
System Requirements for Unix
TCP/IP protocol stack
Database Requirements
•
•
A relational database management system (RDBMS) using one of the following
supported versions:
–
SQL 7 or SQL 2000
–
Oracle 8.1.x or 9i
–
DB2 7.x or later
–
Sybase 11.x or 12.5
The latest ODBC driver software for the database application you will use with
the CPM Server
System Requirements for Unix
Server Hardware
•
•
•
•
•
Sun Sparc (minimum of one 256 MHz processor)
Minimum 128 MB RAM suggested (additional RAM may be required depending
on transaction volume)
Hard disk drive with at least 1 GB of available, uncompressed space on /opt file
system
Dual-speed or higher CD-ROM
Network interface card (NIC) installed and connected to the network
Server Software
•
Sun Solaris 8 with recommended patch cluster, or Solaris 9
CPM Setup Guide • CyberSource Corporation • January 2006
5
Chapter 2 System Requirements and Installation Checklist
CPM Installation Checklist
Database Requirements
•
•
A relational database management system (RDBMS) using one of the following
supported versions:
–
Oracle 8.1.x or 9i
–
Sybase 11.x or 12.5
OpenLink Generic ODBC Drivers (version 5.0; if you use Oracle 9i, you must use
version 5.0 or later)
CPM Installation Checklist
This checklist assumes you already have the Windows or Sun Solaris server and CPM
software CD. It also assumes that the database server resides on a separate machine. If
your hardware and network setup differ from this scenario, adjust the steps according to
your situation. For example, if you have a small environment with relatively slow
network connections, you can install and run the CPM Server software and database on
the same Windows or Sun Solaris server.
Use this checklist and the detailed instructions in the subsequent chapters to set up your
CPM Server environment.
Setting Up the Server for the CPM Environment
•
•
•
•
Locate the Windows or Sun Solaris server in a secure area that has access to
network and communication connections.
Connect the server to the network behind a security firewall.
Configure the TCP/IP protocol stack.
Test the network connection.
CPM Setup Guide • CyberSource Corporation • January 2006
6
Chapter 2 System Requirements and Installation Checklist
CPM Installation Checklist
Setting Up the Communication Connection
Install the required frame relay channels for the payment options. The following table lists
the financial processors and communication connections currently supported by CPM.
Table 1 Financial Processor Communication Options
Financial Processor
Available Communication Option
American Express Phoenix
Frame Relay
First Data Merchant Services (FDMS) Nashville,
North, or South (CPM has a separate gateway for
FDMS South debit card processing)
Frame Relay
Global Payments
Frame Relay
Midwest Payment System (MPS)
Frame Relay
NOVA
Frame Relay
Paymentech New Hampshire and Tampa
Frame Relay
Vital
Frame Relay or SSL
CyberSource Connect. CyberSource Connect™ is a service that enables CPM users to
connect to certain payment processors through CyberSource’s hosted communications
network. If you sign up to use CyberSource Connect, you do not need to set up your own
frame connection to your processor, as you are able to use your regular Internet
connection to use CyberSource’s frame connection to the processor. You set up
CyberSource Connect as part of setting up your payment gateway.
Installing Required Auxiliary Software
If you are going to use a commercial e-commerce front end or suite of applications such as
Microsoft Commerce Server or Oracle iPayment, install and configure the applications
now.
Setting Up the Database Machine
•
Install the CPM database in the protected area behind the firewall. Place the
database so that communication between the CPM Server and the CPM database
does not have to go through the firewall.
CPM Setup Guide • CyberSource Corporation • January 2006
7
Chapter 2 System Requirements and Installation Checklist
•
•
•
•
CPM Installation Checklist
If you have not already done so, install the database software on the database
server machine.
In the database application, create a CPM database and database user account
dedicated to the CPM database. This user account must have create, select,
update, and delete privileges.
On the machine where you are installing the CPM Server, create a system Data
Source Name (DSN) for the CPM database (by using ODBC for Windows or
OpenLink for Solaris).
On the machine where you are installing the CPM Server, test network
connections to the server on which the CPM database resides by using the
database application’s query utility coupled with the newly created DSN.
See Chapter 3, Setting Up the ODBC-Compliant Database, on page 11 for detailed
instructions.
Installing the CPM Server Software
Only one version of the CPM Server can be operational on a server. See Chapter 4,
Installing CPM Server Software, on page 20 for detailed instructions for the items listed
below.
If you already have a version of the CPM Server installed, continue reading this section,
but also refer to the Chapter 6, Upgrading from a Previous Version, on page 48, for
upgrade instructions.
•
•
•
•
Install the CPM Server software (see Installing CPM Software on Windows on
page 23 or Installing CPM Software on Unix on page 28)
Install the CPM Administration Client (for Windows-based CPM Servers, this
happens as part of CPM Server software installation; for Unix-based CPM
Servers, you must do this separately on the Windows system—see Installing the
Administration Client on page 28)
If you do not want to use the default administrator (cpm_local_admin) to
administer your CPM Servers, set up at least one administrator account so you
can connect to and configure the CPM Server (see Creating and Managing
Administrator Accounts on page 21)
Connect the CPM Server to the database, select a payment gateway, and configure
the setup (see Setting Up Your Payment Gateways on page 9 and see the online
help topic called “Initial CPM Server Setup” in the Administration Client’s help
for more details).
CPM Setup Guide • CyberSource Corporation • January 2006
8
Chapter 2 System Requirements and Installation Checklist
•
CPM Installation Checklist
Configure the CPM Client if you installed it (see Installing the CPM Client in Call
Centers on page 41)
Preparing the CPM Server Database
•
•
•
If you did not create data tables during CPM installation, use the CPM Database
Utility to create CPM tables in your ODBC database. See the CPM Database Utility
Guide for more information.
If you plan to store and manage BIN information for use with debit cards, use the
CPM Database Utility to create the BIN information database tables. See the CPM
Database Utility Guide for more information.
If you have not already done so, set up the CPM database encryption feature (note
you must use this feature if you want to be PCI compliant; see the CPM PCI
Compliance Guide for more information about PCI). If you are a new CPM user
installing 6.0 or later, this feature is already enabled, and the instructions for
installing the CPM software include steps for setting it up (in Chapter 4, Installing
CPM Server Software, on page 20). Also see the CPM Database Utility Guide for
more information.
Setting Up Your Payment Gateways
See the “Initial CPM Server Setup” topic in the Administration Client’s online help for
more information about these items:
•
•
•
•
•
•
•
Connect the Administration Client to the CPM Server.
Choose the established Data Source Name (DSN) for the database and establish
login settings.
Set up the CPM Server information.
Set up the storage parameters for the established database.
Enable the gateway for your payment processor and configure the gateway
settings.
If you are signed up to use CyberSource Connect, set up the IP address and IP
port settings for your processor. See the CyberSource Connect Installation Guide for
more information.
Set up your merchants in the payment gateway.
CPM Setup Guide • CyberSource Corporation • January 2006
9
Chapter 2 System Requirements and Installation Checklist
CPM Installation Checklist
Setting Up Transaction Security
•
•
Set up CPM Security and any related user groups. This feature requires users to
provide usernames/passwords when they send transactions to the CPM Server.
To be PCI compliant, you must use CPM Security if your system sends
transactions to CPM from outside the framework of your trusted network
environment (see the CPM PCI Compliance Guide for information about PCI). If
you are a new CPM user installing 6.0 or later, this feature is already enabled, but
you still need to set it up. For information about setting up CPM Security, see
Setting Up CPM Security on page 34.
Enable the Secure Socket Layer (SSL) feature for transaction security between the
CPM transaction APIs and the CPM Server. You must use SSL to be PCI compliant
(see the CPM PCI Compliance Guide for information about PCI). For information
about setting up SSL, see Setting Up SSL on page 35.
Testing the CPM Server
•
•
•
•
Using the CPM Windows Client, run the test transactions for your gateway with
the CPM Server in test mode.
If you are developing proprietary client applications to interface with the CPM
Server, test your programs at this point.
Once testing is complete, change from Test Mode to Production Mode. Contact
the financial processor and tell them that you want to test and certify the
connection.
Once testing with the financial processor is successful, you can begin accepting
transactions.
CPM Setup Guide • CyberSource Corporation • January 2006
10
Chapter 3
Setting Up the ODBC-Compliant
Database
This chapter contains instructions for setting up your ODBC-compliant database and
creating a data source for Windows and Sun Solaris:
Sizing the CPM Database
Setting Up the Database for Windows
Setting Up the Database for Solaris
Sizing the CPM Database
When initially creating your database, CyberSource recommends that you start with a
database one gigabyte in size. To estimate how much space you will need, run some
typical transactions and measure how much database space the transactions use. Then
factor in your expected transaction volume and how long you plan to retain the data.
Setting Up the Database for Windows
CPM works with Microsoft SQL Server and other SQL92 ODBC-compliant relational
databases management systems (RDBMS). CPM does not support the Microsoft Access
database or the Microsoft text driver option. Multiple CPM Servers can use the same
database, but make sure that the database application can be polled by simultaneous and
separate processes, such as multiple CPM Servers or a CPM Server and a reporting utility.
For optimum performance, the database should not reside on the same Windows
computer as the CPM Server. You should have a dedicated, high speed network
connection with speeds no less than 10 megabits/second to connect the CPM Server with
the database.
1
Make sure you have the most current database driver available for your database.
2
Obtain and install the database software.
CPM Setup Guide • CyberSource Corporation • January 2006
11
Chapter 3 Setting Up the ODBC-Compliant Database
3
Setting Up the Database for Windows
Configure the database according to the application’s instructions.
Setting Up the CPM Data Source Name
For a CPM Server to store transaction and CPM Server information to a database, a CPM
system data source name (DSN) must be configured through the Windows ODBC Data
Source Administrator. A data source includes the data a user wants to access and the
information needed to get to that data. For example, a data source can be a Microsoft SQL
Server database, the server on which it resides, and the network used to access that server.
Users created in the CPM database must have the right to create, select, update, and delete
information.
Creating a CPM Data Source
Follow these steps to create a data source that is visible to all users on the system running
the CPM Server service.
The following procedure uses Microsoft SQL Server as a setup example. Follow the setup
instructions for your database application.
1
On the Desktop, click Start > Settings > Control Panel.
2
In the Control Panel, click Administrative Tools, then click Data Sources
(ODBC).
3
In the ODBC Data Source Administrator screen, select the System DSN tab and
click Add.
CPM Setup Guide • CyberSource Corporation • January 2006
12
Chapter 3 Setting Up the ODBC-Compliant Database
4
Setting Up the Database for Windows
Select the driver for the CPM data source. Click Finish to add the source.
Note The driver must be the one for the database you are using.
5
At the prompt, enter a Data Source Name, a description that defines the purpose
of this database, and then select the server on which the CPM database resides.
6
Complete any additional steps required by your database application and then
exit from the setup.
Note If your database uses password information, the information will be needed
when connecting the CPM Server to the database. Make sure you provide the
password to any other administrators of the CPM Server.
Microsoft SQL Server Considerations
If you are using Microsoft SQL Server, you must enable the following options:
•
•
•
Use ANSI quoted identifier
Use ANSI nulls, paddings and warnings
Perform translation for character data
CPM Setup Guide • CyberSource Corporation • January 2006
13
Chapter 3 Setting Up the ODBC-Compliant Database
Setting Up the Database for Solaris
Important Do not enable the Uses Regional Settings when outputting currency,
numbers, dates, and times option. If enabled, this setting corrupts the date, time,
and currency settings communicated between the financial processor, the CPM
Server, and the CPM database.
Oracle Considerations
If you are using the Oracle ODBC client, select the option to disable Large Objects (LOB’s)
for the DSN that the CPM server will use.
Installing Windows Administration Tools
1
Place the CPM CD into the CD-ROM drive on your Windows computer.
2
Open the CD-ROM and go to the x:\Payment Manager <version>\ folder where x
is the drive letter of the CD-ROM.
3
Run setup.exe.
4
Follow the setup default prompts. Select the required client services, APIs and
documentation.
Setting Up the Database for Solaris
CPM for Unix works with Oracle version 8i and 9i and Sybase 11.x and 12.x, and
OpenLink 5.0 ODBC drivers (if you use Oracle 9i, you must use OpenLink 5.0 or later).
Multiple Unix-based CPM Servers can use the same database, but you must ensure that
the database can be polled by simultaneous and separate processes, such as multiple CPM
Servers or a CPM Server and a reporting utility.
For optimum performance, the Oracle database should not reside on the same Sun Solaris
computer as the CPM Server. You should use a dedicated, high speed network connection
with speeds no less than 10 megabits/second to connect the CPM Server with the
database.
OpenLink Overview
OpenLink contains the necessary ODBC database drivers and DSN configuration settings
for a CPM for Unix database. OpenLink ODBC Client components include:
CPM Setup Guide • CyberSource Corporation • January 2006
14
Chapter 3 Setting Up the ODBC-Compliant Database
•
•
•
Setting Up the Database for Solaris
OpenLink Broker ODBC driver manager — A shared library that links ODBC
applications with ODBC drivers. The OpenLink Broker must be installed on the
computer that hosts the CPM database.
Generic ODBC drivers — A shared library that provides database connectivity
and data access services to ODBC-based clients.
Sample ODBC application — A program that you can use to test the ODBC
installation and working environment.
All OpenLink component files are found on the CPM for Unix CD.
When setting up the OpenLink server, first set up OpenLink, then the CPM server.
Obtaining the OpenLink License
You must have the appropriate OpenLink License installed on your database system.
1
Go to www.openlinksw.com.
2
Click Software Availability and Download.
3
Click Download UDA to download Universal Data Access Drivers.
4
When prompted, click Continue.
5
Click the Multi-Tier Edition.
6
Click Multi-Tier Edition Release 5.0 and click Continue.
7
Click the appropriate Client Operating System from the drop-down list box (the
operating system for your CPM Server, either Windows or Solaris 2.8).
8
Click ODBC for the Data Access Mechanism.
9
Click Solaris 2.8 for the Server Operating System from the drop-down list box and
click Availability.
10 Click Oracle 8.1 or Oracle 9.x, and at the bottom of the page, do NOT click the
check box that says you already have the license file.
11 Fill out any registration information as required.
12 Once you complete the registration information, OpenLink will email you the
license. You do not need to download the ODBC drivers as they are already
provided to you on the CPM CD.
13 Once you receive the license from OpenLink, copy it to the /opt/OpenLink/bin
directory.
CPM Setup Guide • CyberSource Corporation • January 2006
15
Chapter 3 Setting Up the ODBC-Compliant Database
Setting Up the Database for Solaris
Installing the OpenLink Server Component
This section explains how to set up OpenLink.
Important To install OpenLink, you must log in as the database user account. Do
not log in as root.
1
Log in as the database user.
2
Place the CPM CD into the CD-ROM drive.
3
Go to cd /cdrom/PaymentManager<version>/unix/openlink/server/create/opt/
Openlink.
4
Copy the OpenLink server files into the /opt/Openlink directory.
5
At the command prompt, change to the /opt/Openlink directory and run the
installation application:
install.sh
6
At the prompts, enter the following information (click Enter for the default
values):
a
Port number the broker will listen on for client connections.
b
TCP/IP Port. The default is 8000.
c
Log file. The default is www_sv.log.
d
Log all requests (Y or N). The default is N (no).
e
Administration account. The default is admin.
f
Administration password. The default is admin.
The OpenLink Administration Assistant is now ready for use.
7
g
Program owner user name. The default is the current user setting.
h
Program owner group name. The default is the current group setting.
Start the OpenLink Request Broker (OPLRQB) service:
a
At the command prompt, change to the /opt/OpenLink/bin directory
b
Run the starting application by typing
./oplrqb-v
CPM Setup Guide • CyberSource Corporation • January 2006
16
Chapter 3 Setting Up the ODBC-Compliant Database
Setting Up the Database for Solaris
Modifying the Environment Variables
1
Update the database user environment variables depending on your shell.
For csh or tcsh, use openlink.csh as a reference guide for setting your environment
variables in your .cshrc file.
For ksh, sh, or bash, use openlink.sh as a reference guide for setting your
environment variables in your .profile file.
For the corresponding Shell reference guide, edit the .cshrc or .profile file to
append the path data and variables, extending your classpaths and path
statements. Do not overwrite your current settings.
2
Make the environment variable active for the current shell.
For csh or tcsh, type [source .cshrc], then click Enter.
For ksh, sh, or bash, type [. ./.profile], then click Enter.
Note Manually modify the profile environment variable to point LD_
library_path to both the /usr/lib and usr/4lib directories.
Setting Up the OpenLink Client on the CPM Server
If you have CPM and the database residing on the same host machine, then skip this
section.
1
Place the CPM CD into the CD-ROM drive.
2
Go to cd /cdrom/PaymentManager<version>/unix/openlink/client.
3
Create the directory opt/openlink.
4
Copy the following files to the /opt/openlink directory:
sroczzzz.taz
install.sh
5
Execute install.sh. For example, run ./install.sh in the /opt/openlink directory.
Accept the defaults.
6
Copy the server’s odbc.ini file to the client’s /opt/openlink/bin directory, or
manually edit the client to match the server’s odbc.ini file.
Verify all environment path data is correct for the client computer.
CPM Setup Guide • CyberSource Corporation • January 2006
17
Chapter 3 Setting Up the ODBC-Compliant Database
Setting Up the Database for Solaris
7
Set the client’s environment variables by copying the database users .profile or
.cshrc settings to the client account, or by referencing the /opt/openlink/
openlink.sh or .csh files.
8
Make the changes to the environment variables active for the current shell.
For csh or tcsh, type [source .cshrc], then click Enter.
For ksh, sh, or bash, type [. ./.profile], then click Enter.
9
Set up the CPM data source name (DSN). For instructions, see Setting Up the
CPM Data Source Name below.
10 Test odbc.ini.
a
Run ./odbctest from /opt/openlink/bin directory.
b
At the prompt, enter DSN=<your_DSN_name>.
If the connections fails, check your environment variables.
Setting Up the CPM Data Source Name
For a CPM Server to store transaction and CPM Server information to a database for Unix,
a CPM system data source name (DSN) must be configured through OpenLink.
You can set up the CPM DSN through the OpenLink Admin Assistant Web application or
though a command terminal by manually editing the odbc.ini file in /opt/openlink/bin.
The following instructions are for setup using the OpenLink Admin Assistant. All
selections made in the Admin Assistant are saved to the odbc.ini file.
1
Open a Web browser and enter the following URL: http://localhost:8000.
2
In the navigation bar of the OpenLink Admin Assistant page, select the Client
Components Administration link, then select Data Source Name Configuration
and Edit Data Sources by Wizard, and Edit ODBC Data Sources.
3
Type the OpenLink administrator’s username and password. The default for both
values is admin.
4
In the ODBC Data Source Configuration Wizard, click Add, then select the
OpenLink Generic 32-Bit Driver 5.0 and click Next.
5
Enter a name for the data source you are creating, then enter a description for the
data source in the Comment field. Click Next.
CPM Setup Guide • CyberSource Corporation • January 2006
18
Chapter 3 Setting Up the ODBC-Compliant Database
Setting Up the Database for Solaris
6
In the Domain field, select the type of OpenLink agent that serves your ODBC
client. For example, select Oracle 8.1.x.
7
In the Host Name field, enter the name or IP address of the computer that runs
the OpenLink Server Components. The default port is 5000.
8
Select the protocol your system uses and click Next.
9
In the Database Name field, enter a name for the database you want OpenLink to
use. You can also enter an optional identifier in the Database Server field.
10 In the Username field, enter a default username that can be used to log in to the
database. Click Next.
11 Select any boxes (for Read-only connection, No Login Dialog Box, Defer Fetching
of long data, or Row buffer size) that are appropriate for your environment.
Accepting the default selections is suggested. Click Next.
12 Verify your settings, then click Save.
You have set up the DSN.
13 Return to step 10 on page 18 to finish setting up OpenLink.
Testing the DSN Connection
1
In the OpenLink ODBC Setup Wizard, click Test this DSN.
2
Enter the DSN Name, user ID, and password for the selected DSN.
3
Click Test.
If the test times out or generates an error, review the DSN connection information.
Creating Database Tables
1
At the command prompt, go to /opt/cybersource/payment_manager/server.
2
Type the following command.
./cpm_dbutil -create -usr <DB Username> -pwd <pwd> -db <DSN Name>
Note The DSN Name is the one you created through OpenLink.
CPM Setup Guide • CyberSource Corporation • January 2006
19
Chapter 4
Installing CPM Server Software
This chapter provides instructions for installing the CPM Server software.
Note These instructions are not a complete guide for upgrading your CPM software. For information about upgrading1, refer to Chapter 6, Upgrading from a Previous Version, on page 48.
The chapter includes these sections:
About Installing CPM Software
Creating and Managing Administrator Accounts
Installing CPM Software on Windows
Installing CPM Software on Unix
Setting Up the FTP Tool for the NOVA Gateway
Setting Up CPM Security
Setting Up SSL
Installing the CPM Client in Call Centers
You can set up your system to run multiple CPM Servers that connect to a single CPM
database. If you plan to do this, also see Chapter 5, Using Multiple Servers, on page 43.
About Installing CPM Software
If you have not already done so, read CPM Installation Checklist on page 6. That section
lists the overall set of tasks related to setting up CPM (installing the CPM software is only
part of the process).
The following instructions describe how to install CPM from a CD. None of the CPM
components may be run from the CD itself. All of the CPM components must be installed
on to a hard drive.
CPM software can be installed over a network. A network installation helps simplify the
process of multiple installations of CPM Client APIs, the CPM Merchant Editor, CPM
Reports, and other components. To install CPM over a network, you must map the drive
CPM Setup Guide • CyberSource Corporation • January 2006
20
Chapter 4 Installing CPM Server Software
Creating and Managing Administrator Accounts
containing the CPM software CD or the drive containing the CPM installation image to
the local computer.
Before proceeding with the installation, make sure you have performed all the necessary
steps for setting up the Windows or Sun Solaris server environment, making hardware
and software connections to your financial processor, and installing an ODBC-compliant
database and any auxiliary software.
Note During installation, you must enter the CPM license key provided by CyberSource. License keys are case sensitive and are not saved if you type an error. To
prevent typing errors, we suggest you copy the license key to the clipboard or save
it to the desktop, then when prompted, paste it into the appropriate installation
screen.
You can set up your system to run multiple CPM Servers that connect to a single CPM
database. For information about doing this, see Chapter 5, Using Multiple Servers, on
page 43.
Creating and Managing Administrator Accounts
This section describes changes that have been made in CPM 6.0 to the definition of a CPM
administrator. You should read this section to understand how CPM handles
administrator information.
Prior to CPM 6.x, you created a new administrator by going to the Administration Client,
connecting to a CPM Server, opening the Security tab in the server’s properties, and
adding a new user to the Security group called “Administrators”. All management of
administrators (creating, deleting, changing passwords) was done there. The username
and password information for administrators was stored in the CPM database.
Now with CPM 6.0, you create a new administrator by using a command-line tool called
AcctMaint.exe. All management of administrators (creating, deleting, changing
passwords) is done with this tool. The username and password information for
administrators is now stored outside the CPM database in a special file called cpm_admin,
which resides in the Server directory. If you have multiple CPM Servers, you need to
place a copy of that file in the Server directory on each CPM Server and keep the files
synchronized. If you make changes to the cpm_admin file on one CPM Server (for
example, if you add a new administrator or change an administrator’s password), you
need to copy the updated cpm_admin file to all of your CPM Servers.
Although administrators are managed differently with 6.0, the CPM Security group called
“Administrators” still exists if you upgrade from a previous CPM version. When you
upgrade to 6.0, any users that were part of the Administrators Security group prior to 6.0
CPM Setup Guide • CyberSource Corporation • January 2006
21
Chapter 4 Installing CPM Server Software
Creating and Managing Administrator Accounts
still exist for the purposes of the CPM Security functionality and still have their account
information stored in the CPM database. However, those users can no longer log in to the
Administration Client unless you create administrator accounts for them with the
AcctMaint.exe tool.
CPM was changed with version 6.0 so that new merchants installing CPM 6.0 for the first
time will not see a default Administrators Security group in the Administration Client’s
Security tab. With 6.0, that default group has been removed for new installations.
Default Administrator Account
CPM comes with a default administrator (username: cpm_local_admin, password:
changeoninstall). If you want to, you can use this administrator account and never create
another administrator. The first time you log in to the Administration Client with the
cpm_local_admin account, you will be prompted to change its default password. Make
sure to remember this new password, as the only way you can restore the default
password is to reinstall the CPM software.
Using the AcctMaint.exe Tool to Manage Administrators
To be able to administer your CPM Server(s), you must have at least one administrator
account. You can use the default administrator account (see above) or create one or more
of your own.
If you are upgrading to 6.0 and previously had your own administrator accounts besides
the default administrator, you must use the AcctMaint.exe tool to recreate your
administrator accounts so that the password information is stored as needed in the cpm_
admin file.
AcctMaint.exe is a command-line program that works on both Windows and Unix
systems and is located on the CPM Server system in the Server directory. With it you can
create a new administrator, change a password, and delete an administrator.
To use the program:
1
Go to the Server directory of the CPM Server and run the AcctMaint.exe program.
2
When prompted, enter an existing administrator’s username and password. If
you have not yet created any administrators, use the default administrator
(username: cpm_local_admin, default password: changeoninstall). The first time
you log in to the Administration Client with the default administrator you will be
prompted to change the password.
CPM Setup Guide • CyberSource Corporation • January 2006
22
Chapter 4 Installing CPM Server Software
3
Installing CPM Software on Windows
Select the number (1–4) from the menu that corresponds to the task you want to
perform: add an administrator, change a password, delete an administrator, or
quit the program.
Note that passwords must have at least seven characters and must include at least
one alphabetic character, one numeric character, one uppercase character, and one
lowercase character. Also, passwords expire after 90 days (the administrator is
prompted to change the password the expiration date approaches).
4
Depending on which task you choose, you will be prompted to enter the relevant
information. If you are changing a password, be aware that CPM stores the recent
password history and prohibits you from reusing any of the last four passwords
that you have used for that administrator.
When the task is complete the program automatically terminates.
Handling a Lockout Due to Failed Attempts
With CPM 6.x, if you try to log in to the Administration Client and enter the wrong
password six times in a row, the account will be locked out for five minutes or until
another administrator restarts the CPM Server in the Administration Client (note that
there is no time window for your failed attempts; for example: if you fail three times and
do not try again until a month later, your next failed login attempt is still considered your
fourth failed attempt).
Handling a Lockout Due to Inactivity
With CPM 6.x, if you are logged in to the Administration Client and leave the machine
idle for more than 15 minutes, CPM will automatically close the Administration Client.
CPM will then display an alert window with a button you can click to reopen the
Administration Client. You will have to log in again when it reopens.
Installing CPM Software on Windows
Use the following instructions to install CPM on a Windows system. If you are upgrading
your CPM software, instead see Chapter 6, Upgrading from a Previous Version, on page
48.
None of the CPM components may be run from the CD-ROM itself. You must install all
components on your hard drive.
CPM Setup Guide • CyberSource Corporation • January 2006
23
Chapter 4 Installing CPM Server Software
1
Place the CPM CD into the CD-ROM drive.
2
Run the Setup.exe file.
Installing CPM Software on Windows
Note During installation, you must provide the CPM license key. The
license key is case sensitive and is not saved if an error is made. Be sure you
type the key correctly, or copy and paste it to help prevent making an error.
3
When the InstallShield Wizard opens, click Next to begin.
A dialog box appears with the CyberSource license agreement.
4
Click Yes to accept this agreement and continue with the installation; otherwise,
click No and exit the setup.
If you accept the license agreement, another dialog box opens prompting for the
Directory Destination for the CPM System.
5
Click Next to accept the default destination directory, or enter a different
destination directory, and then click Next.
Note CyberSource recommends installing the CPM System in the C:\Program Files\CyberSource\Payment Manager directory. Installing the CPM
System in the old PaylinX directory (if you have one) will require you to
uninstall the CPM System manually should you need to remove the CPM
System for any reason.
CPM Setup Guide • CyberSource Corporation • January 2006
24
Chapter 4 Installing CPM Server Software
6
Installing CPM Software on Windows
Select the CPM components (on the left side of the window) and subcomponents
(on the right side) you want to install.
If you do NOT plan to use the Java SDK, make sure to deselect the check box for
the SSL Proxy Service subcomponent.
If you do plan to use the Java SDK and SSL, you must install the SSL Proxy Server,
so make sure to select the SSL Proxy Service. Also read Chapter 7, Using the Java
SDK and SSL Proxy Server, on page 62, which covers configuring and using the
Proxy Server.
When you install the CPM Client or client APIs (ActiveX or C Windows), you
must also install the CPM Merchant Editor. Make sure you select the CPM
Merchant Editor in the CPM components window.
7
Click Next.
8
Type or copy and paste the license key and click Next.
9
When prompted, click Next to start copying the CPM files.
Note If upgrading, you might be asked if you want to remove the current
PaylinX directory (if you have an old version of PaylinX installed). If you
select No, but later delete PaylinX through the Windows Add/Remove
option, the registry may become corrupt. You should back up the registry
if there is a possibility of deleting PaylinX using the Windows method.
CPM Setup Guide • CyberSource Corporation • January 2006
25
Chapter 4 Installing CPM Server Software
Installing CPM Software on Windows
10 If in step 6 you selected the check box for the CPM Client, you will be prompted
to select the transaction types your business needs. Select the transaction types
and click Next. For information about the CPM transaction types that are
available, see the CPM API Reference Guide.
11 When prompted, click Yes to create your database tables.
12 When prompted, log in to the database with the username, password, and data
source name.
When the installation is complete, a dialog box opens with the option of rebooting
the server immediately or at a later time.
13 Select NO so that you do NOT reboot the server at this time, and click Finish.
14 Set up database encryption:
The database encryption key generation tool that comes with CPM 6.x uses a
split-knowledge technique that ensures that the key is under the control of two or
more people. During key generation, two different people are required to provide
passphrases separately. The key is generated based on those passphrases and can
be reconstructed if needed with the passphrases. Each person must memorize his
or her own passphrase and may not tell anyone the phrase at any time. See the
CPM Database Utility Guide for more information about best practices for
managing your database encryption key.
a
Go to the Server directory (C:\Program Files\CyberSource\
PaymentManager\Server) and double-click DBKeyGenerator.exe.
The menu is displayed.
b
Click Generate New Key.
CPM Setup Guide • CyberSource Corporation • January 2006
26
Chapter 4 Installing CPM Server Software
Installing CPM Software on Windows
When prompted for the first passphrase, have the first person enter the first
passphrase.
c
When prompted for the second passphrase, have the second person enter the
second passphrase.
The tool creates the key and displays the 8-character serial number (686F7573
in this example).
d
Write down the serial number, which you will need in a moment.
e
Select the check box for Write to Registry and click OK.
The key is imported into the registry. See the database encryption section in
the CPM Database Utility Guide for information about additional tasks you
will need to perform when managing your database encryption key.
f
Click Exit to close the tool.
g
Locate the cpm.cfg file (in the Server directory), and with a text editor, update
the file so that the DBEncryptKeySN field is set to the encryption key’s serial
number.
You have prepared the CPM Server to use database encryption. If you have
additional CPM Servers, make sure to import the database encryption key
into the registry on each CPM Server. Also update the cpm.cfg file on each
CPM Setup Guide • CyberSource Corporation • January 2006
27
Chapter 4 Installing CPM Server Software
Installing CPM Software on Unix
CPM Server so that the DBEncryptKeySN parameter is set to the serial
number of the key. See the database encryption procedures in the CPM
Database Utility Guide for instructions.
15 Reboot the CPM Server system.
16 Log in to the Administration Client with the default administrator (username:
cpm_local_admin, password: changeoninstall) and change the default password
when prompted.
17 If you are using the NOVA gateway, set up the FTP tool that CPM uses to transfer
the settlement files to NOVA. See Setting Up the FTP Tool for the NOVA Gateway
on page 33.
You have installed the CPM software. Make sure to return to Installing the CPM Server
Software on page 8 to continue with the general installation checklist.
Installing CPM Software on Unix
When setting up a Unix CPM system, you must:
•
•
Install the CPM Administration Client on the Windows system (see below)
Install the CPM Server software on the Unix system(s) (see page 28)
Installing the Administration Client
1
Place the CPM CD into the CD-ROM drive.
2
Run the setup.exe file.
3
When the InstallShield Wizard opens, click Next to start it.
A dialog box appears with the CyberSource license agreement.
4
Click Yes to accept this agreement and continue with the installation; otherwise,
click No and exit the setup.
If you accept the license agreement, another dialog box opens prompting you to
choose the destination directory for the CPM System.
5
Click Next to accept the default destination directory, or enter a different
destination directory, and then click Next.
CPM Setup Guide • CyberSource Corporation • January 2006
28
Chapter 4 Installing CPM Server Software
Installing CPM Software on Unix
Note CyberSource recommends installing the CPM System in the default
C:\Program Files\CyberSource\PaymentManager directory.
6
When prompted to select the CPM components you want to install, select the
check box for the Administration Client on the right side of the screen. Make sure
that is the only check box that is selected.
7
Click Next to confirm the component and files you want to install.
The Wizard copies the necessary files and completes the installation.
You have installed the Administration Client.
Installing the CPM Server Software
Use the following instructions to install the CPM Server software on a Solaris system.
1
Log in as Root on the target computer.
2
Verify that the LD_LIBRARY_PATH environment variable includes the path to
the CPM Server. The default path to the server is
/opt/cybersource/payment_manager/server.
One easy way to do this is by setting the variable’s path in the .profile file.
3
Insert the CPM for Solaris CD into the CD-ROM drive and change to the
CD-ROM mount directory /cdrom/PaymentManager<version>/unix.
4
Copy the tar file to the directory in which you want to install the CPM software
(the default installation directory is /opt).
5
Change to the directory where you copied the tar file and untar the file by using
tar xvf <filename> to extract the directory structures.
6
Change directory to /opt/cybersource/payment_manager/server.
7
Execute ./enterKey.ksh, and enter the CPM license key at the prompt.
8
If you have not already installed it, install and configure the OpenLink client and
server. See OpenLink Overview on page 14.
9
Set up database encryption:
The database encryption key generation tool that comes with CPM 6.x uses a
split-knowledge technique that ensures that the key is under the control of two or
more people. During key generation, two different people are required to provide
CPM Setup Guide • CyberSource Corporation • January 2006
29
Chapter 4 Installing CPM Server Software
Installing CPM Software on Unix
passphrases separately. The key is generated based on those passphrases and can
be reconstructed if needed with the passphrases. Each person must memorize his
or her own passphrase and may not tell anyone the phrase at any time. See the
CPM Database Utility Guide for more information about best practices for
managing your database encryption key.
a
Go to the Windows system where the Administration Client is installed, and
in the Server directory of the CPM installation, double-click
DBKeyGenerator.exe.
The menu is displayed.
b
Click Generate New Key.
When prompted for the first passphrase, have the first person enter the first
passphrase.
c
When prompted for the second passphrase, have the second person enter the
second passphrase.
CPM Setup Guide • CyberSource Corporation • January 2006
30
Chapter 4 Installing CPM Server Software
Installing CPM Software on Unix
The tool creates the key and displays the 8-character serial number (686F7573
in this example).
d
Write down the serial number, which you will need in a moment.
e
Select the check box for Write to File and click OK.
The file is written to the Server directory as <serial number>.key.
f
Click Exit to close the tool.
g
Copy the key file from the Windows-based system to the server directory on
each CPM Server you are using (the typical path is opt/cybersource/payment_
manager/server), and change the file permissions so that access to the file is
limited.
h
Delete the key file from the Windows-based system.
i
Locate the cpm.cfg file (in the server directory), and with a text editor, update
the file so that the DBEncryptKeySN field is set to the encryption key’s serial
number.
You have prepared the CPM Server(s) to use database encryption.
10 If you plan to use the CPM Java SDK, update your security policy files for strong
encryption (for instructions, see Updating Your Java Installation for Strong
Encryption on page 67). If you plan to use SSL with the Java SDK, you must use
the SSL Proxy Server, which was automatically installed during step 5. For
information about configuring and using the proxy, see Chapter 7, Using the Java
SDK and SSL Proxy Server, on page 62.
11 Start CPM by executing ./cpm.
12 Go back to the Windows system, log in to the Administration Client with the
default administrator (username: cpm_local_admin, password: changeoninstall),
and change the default password when prompted.
CPM Setup Guide • CyberSource Corporation • January 2006
31
Chapter 4 Installing CPM Server Software
Installing CPM Software on Unix
You have installed the CPM Server software. Make sure to return to Installing the CPM
Server Software on page 8 to complete the general installation checklist.
Setting Up CPM and the CPM Manager to Start with the
Solaris System
This section explains how to setup CPM and the CPM Manager to start automatically
when the Solaris system is started.
1
Place the following file in the /etc/init.d directory, and name the file cpm.
#!/sbin/sh
#
CPMHOME=/export/home/
case "$1" in
'start')
echo "Starting cpm service control manager"
$CPMHOME/cpm_manager
echo "Starting cpm server"
$CPMHOME/cpm
;;
'stop')
if [ -f $CPMHOME/cpm.pid ]; then
echo "Stopping cpm server"
kill -INT `cat $CPMHOME/cpm.pid`
fi
if [ -f $CPMHOME/cpm_manager.pid ]; then
echo "Stopping cpm service control manager"
kill -INT `cat $CPMHOME/cpm_manager.pid`
fi
;;
*)
echo "Usage: $0 { start | stop }"
exit 1
;;
esac
exit 0
CPM Setup Guide • CyberSource Corporation • January 2006
32
Chapter 4 Installing CPM Server Software
Setting Up the FTP Tool for the NOVA Gateway
2
Create a link in the run level directory, for example /etc/rc3.d, called S88cpm, and
point the link to the file in the init.d directory.
3
Change the CPMHOME variable to point to where the server executable is
installed.
Uninstalling CPM for Unix
If you need to uninstall CPM for Unix, use the following steps to remove the CPM Unix
programs and directories from a command terminal.
1
Before removing CPM from your system, make sure all merchants have settled
and that the CPM service is stopped.
2
Open a command terminal and go to the directory where CPM is located, for
example:
opt/cybersource/payment_manager
3
At the command prompt, enter rm -rf /opt/cybersource. This removes the
CyberSource directory and all subdirectories related to CPM.
4
Go to the directory where OpenLink is located, for example:
opt/openlink
5
At the command prompt, enter rm -rf /opt/openlink. This removes the
OpenLink directory and all subdirectories related to OpenLink.
Setting Up the FTP Tool for the NOVA Gateway
If you are using the NOVA gateway, you must set up a particular FTP tool that CPM uses
to transfer the settlement files to NOVA. Make sure to perform the following procedure
before settlement occurs for the first time. You will need your FTP user ID and password,
which you obtain from NOVA.
To set up the FTP tool:
1
Open a command prompt.
2
Change to the Server directory of the CPM installation.
3
At the prompt, type
CPM Setup Guide • CyberSource Corporation • January 2006
33
Chapter 4 Installing CPM Server Software
Setting Up CPM Security
psftp <FTP host provided by NOVA>
For example: psftp masstrans.novainfo.net
4
When prompted, enter your FTP user ID.
5
When prompted with “Store key in cache? (y/n)”, type y.
6
When prompted, enter your FTP password.
7
Type quit to end the session.
You have set up the FTP tool.
Setting Up CPM Security
CyberSource recommends that you use the CPM Security feature. If you want to be PCI
compliant, you must use CPM Security if your system sends transactions to CPM from
outside the framework of your trusted network environment (see the CPM PCI Compliance
Guide for more information about PCI). When you turn on CPM Security, users must
provide usernames/passwords when sending transactions to the CPM Server either
through the CPM Client or through a CPM API. If disabled, anyone can send transactions
to the CPM Server without a password.
If you are a new CPM user installing CPM 6.x (without a pre-6.0 version being installed),
CPM Security is enabled by default. You still need to set up your security group(s) and
define usernames/passwords for all of your CPM users. You do this on the Security tab in
the CPM Server’s properties in the Administration Client. See the topic called “Security
Tab” in the Administration Client’s online help for more information.
If you are an existing CPM merchant upgrading to 6.x and you were not previously using
CPM Security, it will be disabled.
To enable CPM Security:
1
Open the Administration Client and connect to a CPM Server.
2
In the server’s properties, click the Security tab.
3
Select the Require Username and Password check box.
4
Click OK.
You must then define one or more security groups with different privileges (if desired)
and add your CPM users to the security group(s). See the topic called “Security Tab” in
the Administration Client’s online help for more information.
CPM Setup Guide • CyberSource Corporation • January 2006
34
Chapter 4 Installing CPM Server Software
Setting Up SSL
Create a separate username/password for each person who will be sending transactions
to the CPM Server. Do not use group or shared passwords.
If you plan to send transactions to the CPM Server through one of the CPM APIs, see the
CPM API Reference Guide for information about the Security Group API fields and the API
functions called Begin Session (150) and End Session (151). You will need to use those
fields and functions in your API calls.
Setting Up SSL
CyberSource recommends that you use SSL with CPM. If you want to be PCI compliant,
you must use SSL (see the CPM PCI Compliance Guide for more information about PCI). If
you are running multiple CPM Servers, you can use the same SSL key across all servers, or
you can generate a different SSL key for each server.
If you are using CPM’s Java API, see Chapter 7, Using the Java SDK and SSL Proxy Server,
on page 62 for information about setting up CPM to use SSL.
If you are using CPM’s C Windows API, C Solaris API, or Active X API, follow the
instructions in the next two sections to set up SSL.
Setting Up SSL for the First Time
These instructions are for merchants using CPM’s C Windows API, C Solaris API, or
Active X API. If you are using CPM’s Java API, see Chapter 7, Using the Java SDK and SSL
Proxy Server, on page 62 for information about setting up CPM to use SSL.
Use these instructions if you have never set up SSL on CPM before. If you have already set
up SSL before and you want to create a new SSL encryption key, see Replacing the SSL
Encryption Key on page 40.
1
Generate the certificate request:
CPM Setup Guide • CyberSource Corporation • January 2006
35
Chapter 4 Installing CPM Server Software
Setting Up SSL
a
Open the Administration Client and in the server properties go to the SSL
Server Information tab.
b
Click Generate Certificate Request.
c
In the SSL Server Information dialog box, enter the requested information
and click OK. The passphrase can be any phrase that you want to use.
CPM Setup Guide • CyberSource Corporation • January 2006
36
Chapter 4 Installing CPM Server Software
Setting Up SSL
The certificate request information appears in the Certificate Request
window.
d
Click Save to File and save the file with any name to the desktop.
e
Click Close to close the Certificate Request window.
The window on the SSL Server Information tab shows information
beginning with “Awaiting key certificate import”.
2
Generate the certificate with the SSLKeyGenerator.exe tool:
a
Go to the Server directory and run the SSLKeyGenerator.exe tool.
CPM Setup Guide • CyberSource Corporation • January 2006
37
Chapter 4 Installing CPM Server Software
Setting Up SSL
b
Click Load from File and select the file you saved to the desktop in step d.
c
Click the Validate Request tab.
The tool validates the information and populates the fields on the screen.
CPM Setup Guide • CyberSource Corporation • January 2006
38
Chapter 4 Installing CPM Server Software
3
Setting Up SSL
d
Click the Generate Key tab and click Generate Key.
e
Click Save to File and save the file with any name to the desktop.
f
Click OK to close the SSLKenGenerator.exe tool.
Import the certificate:
a
Open the file you created in step e and copy all of the text.
b
Go back to the Administration Client’s SSL Server Information tab and click
Import Certificate.
CPM Setup Guide • CyberSource Corporation • January 2006
39
Chapter 4 Installing CPM Server Software
4
Setting Up SSL
c
Click Paste from Clipboard to paste the contents from the file into the
window.
d
Click OK.
Restart the CPM Server.
The information in the SSL Server Information window updates to indicate that
SSL is enabled and shows the certificate’s expiration date.
You have enabled SSL. You now have two certificate files in the
C:\WINDOWS\SYSTEM32 directory on the CPM Server (for Windows users) or on the
Windows system where the Administration Client resides (for Unix users):
•
•
sslcertificate.txt
sslprivatekey.txt
For merchants with Windows-based CPM Servers: If you have multiple servers and want
to use the same SSL key for all the servers, copy the two files above to the
C:\WINDOW\SYSTEM32 directory of all the servers and restart each CPM Server. The
certificates will automatically be picked up and used by the CPM Servers.
Replacing the SSL Encryption Key
Replace your SSL key every four to six years.
These instructions are for merchants using CPM’s C Windows API, C Solaris API, or
Active X API. If you are using CPM’s Java API, see Chapter 7, Using the Java SDK and SSL
Proxy Server, on page 62 for information.
CPM Setup Guide • CyberSource Corporation • January 2006
40
Chapter 4 Installing CPM Server Software
Installing the CPM Client in Call Centers
To replace your SSL key:
1
Open the Administration Client and stop the CPM Server.
2
On the CPM Server system, delete the following two files from the
C:\WINDOWS\SYSTEM32 directory (if you are a Unix user, delete these from
the Windows system that is running the Administration Client):
3
–
sslcertificate.txt
–
sslprivatekey.txt
Follow the procedure that you use when setting up SSL for the first time (see
Setting Up SSL for the First Time on page 35).
You have replaced your SSL key.
Installing the CPM Client in Call Centers
The CPM Client allows call center and IVR staff to enter transaction information from
their location and route that information to a remotely located CPM Server for processing.
You need to install the CPM Client separately on each Windows workstation of your call
center.
You can install the CPM Client onto workstations from the CD or from a mapped network
drive. The instructions that follow describe installation from a CD.
Note For information on CPM integrations for IVR, contact CyberSource Sales.
1
Place the CPM CD into the CD-ROM drive. On the Desktop, select Start > Run.
2
In the Run dialog box command line, type x:\Payment Manager
<version>\startup.exe where x is the drive letter of the CD-ROM and then click
OK.
3
In the CPM Installation screen, click Install Software.
4
At the prompt, close all currently running programs and click Next.
5
In the License Agreement screen, click Yes to accept the agreement and continue
with the installation.
6
In the Destination Directory dialog, click Next to accept the default destination
directory or select a different directory and click Next.
CPM Setup Guide • CyberSource Corporation • January 2006
41
Chapter 4 Installing CPM Server Software
Installing the CPM Client in Call Centers
Note If there is not enough room on the selected drive, the installation program generates an insufficient disk space warning. If this happens, select
another drive on which to install CPM.
7
Select the CPM Client and the CPM Merchant Editor in the CPM components
window and click Next.
8
Select the transaction types you want to perform. The types of transactions
available in this screen depend on what your license key permits.
9
Click Next to accept the default program folder or select an another folder to hold
the CPM software. We recommend you use the default folder.
Click Next to begin the final installation process.
10 You must reboot the computer to complete the installation. Select Yes and click
Finish to reboot the computer now, or select No to reboot it later.
CPM Setup Guide • CyberSource Corporation • January 2006
42
Chapter 5
Using Multiple Servers
You can set up your system to run multiple CPM Servers connecting to a single CPM
database. You may want to do this to load balance your transaction volume and to
provide failover capability in case one of the servers fails.
This chapter includes these topics:
Setting Up the Servers
Setting Up the Merchant Configuration
Setting Up the Gateway Configuration
Configuring for Settlement
Setting Up the Database Aging Parameters
Setting Up the Servers
To do this, repeat the CPM Server installation procedure for each CPM Server you want to
create, then configure each CPM Server to point to the same database. See Chapter 4,
About Installing CPM Software, on page 20.
Important When using multiple servers with the same database, you must specify
a unique server ID for each server. You specify the server’s ID on the CPM Server
tab of the server’s Properties in the CPM Administration Client. See the screenshot
on page 45.
Database Encryption Key
If you are installing CPM with the database encryption option, you need to use the same
CPM software license key and database encryption key on all of the CPM Servers. See the
CPM Database Utility Guide for information about database encryption.
CPM Setup Guide • CyberSource Corporation • January 2006
43
Chapter 5 Using Multiple Servers
Setting Up the Merchant Configuration
Administrator Passwords and the cpm_admin File
With CPM 6.0 and later, the usernames and passwords for all of the CPM administrators
are stored in a file called cpm_admin, which resides on the CPM Server in the Server
directory. You need to place a copy of that file in the Server directory on each CPM Server
and keep the files synchronized. If you make changes to the cpm_admin file on one CPM
Server (for example, if you add a new administrator or change an administrator’s
password), you need to copy the updated cpm_admin file to all of your CPM Servers.
Setting Up the Merchant Configuration
If you have multiple servers, you need to set up the merchant configuration on only one of
the servers; the merchant configuration information is shared between the servers.
To access a merchant’s configuration information:
1
Open the Administration Client and connect to one of the CPM servers.
2
Open the server’s properties.
3
Click the Merchants tab.
4
Select the merchant ID from the list.
5
Click Modify.
You then have access to the merchant’s configuration information, including the
settlement conditions for the merchant, and the card types the merchant accepts.
Depending on your system configuration, you might have multiple instances of the
Administration Client running. It is possible for two or more users to access and modify a
merchant’s configuration at the same time. Thus, to avoid conflicts, CyberSource
recommends that you designate one person to be in charge of making all merchant
configuration changes, and that you designate a specific instance of the Administration
Client to use when making those changes.
Setting Up the Gateway Configuration
Unlike the merchant configuration which is shared between all the servers, the gateway
configuration is not shared between the servers and does not have to be identical on each.
You must configure the gateway individually on each CPM Server.
To access a gateway’s configuration information:
CPM Setup Guide • CyberSource Corporation • January 2006
44
Chapter 5 Using Multiple Servers
Configuring for Settlement
1
Open the Administration Client and connect to the desired CPM server.
2
Open the server’s properties.
3
Click the Gateway Types tab.
4
In the Configure Gateway Types section, select the gateway type from the dropdown list.
5
Click Gateway Settings....
You then have access to the gateway configuration information for that server.
Configuring for Settlement
If you are running CPM 5.x software or later with multiple servers, you should set up the
servers so that only one is used for settlement. To do this, configure all of the servers
except one of them as “Auth-only” servers:
1
Open the Administration Client and connect to the server.
2
Open the server’s properties.
3
Click the CPM Server tab.
4
Select the check box for Auth-Only Server.
CPM Setup Guide • CyberSource Corporation • January 2006
45
Chapter 5 Using Multiple Servers
Configuring for Settlement
You can, however, ignore this rule about setting up all but one server as auth-only, but
ONLY if you disable automatic settlement for all merchants. You then should settle only
by using the API or the Settle Now feature with specific merchants or gateways.
For information about the settlement API, see the CPM API Reference Guide. Specifically
look at the information for the Admin Command group of API fields.
For information about the Settle Now feature, see the online help in the Administration
Client.
To disable automatic settlement for a merchant:
1
Open the Administration Client and connect to one of the CPM servers.
2
Open the server’s properties.
3
Click the Merchants tab.
4
Select the merchant ID from the list.
5
Click Modify.
6
Click the Merchant - Settlement Conditions tab.
7
Make sure the check box for Perform Settlement automatically for this merchant
is NOT selected.
8
Make sure the check box for Perform Settlement Recovery automatically for this
merchant is NOT selected.
9
Click OK to close the properties.
CPM Setup Guide • CyberSource Corporation • January 2006
46
Chapter 5 Using Multiple Servers
Setting Up the Database Aging Parameters
Setting Up the Database Aging Parameters
If you are using multiple CPM Servers, you need to set up the database aging parameters
on only one of the CPM Servers. You set up these parameters on the Storage tab of the
server’s properties in the Administration Client. For more information, see the
Administration Client’s online help.
CPM Setup Guide • CyberSource Corporation • January 2006
47
Chapter 6
Upgrading from a Previous Version
This chapter explains how to upgrade to the latest version of CPM and helps you select
the best upgrade strategy for your business. The chapter includes these sections:
Upgrading from a 5.x Version
Upgrading from a 4.x or 3.x Version
Upgrading from a 5.x Version
An upgrade from a 5.x version to the 6.x version does not require any significant changes
to the database, so the upgrade process is very easy.
Important If you are upgrading from a version prior to 5.5.5 and plan to use the
new CPM Java SDK that is available with 5.5.5 and later, make sure to read For All
Java SDK Users: Updating the Security Policy Files on page 62 and update your
security policy files.
For Unix
Important If you are using a Unix-based CPM Server, the default installation path
for the CPM software has changed with CPM 6.0 to:
/opt/cybersource/payment_manager/server
1
Compile a list of your existing administrator account usernames and passwords
as you will need to recreate these accounts later in this procedure (see Creating
and Managing Administrator Accounts on page 21 for more information).
2
If you are using the NDC East (Global Payments) gateway and you are upgrading
from a version prior to 5.7:
a
Open the Administration Client, connect to the CPM Server, and open the
server properties.
CPM Setup Guide • CyberSource Corporation • January 2006
48
Chapter 6 Upgrading from a Previous Version
3
4
Upgrading from a 5.x Version
b
Go to the gateway settings for NDC East and record the value of the
Application ID. With CPM 5.7, the field moved from the gateway settings to
the agreement settings, and you will reenter the value later.
c
Close the server properties.
If you are using the FDMS South gateway and you are upgrading from a version
prior to 5.1.1:
a
Open the Administration Client, connect to the CPM Server, and open the
server properties.
b
Go to the gateway settings for FDMS South and record the host IP address
and port settings. With CPM 5.1.1, the layout of the FDMS South gateway
settings dialog box was redesigned to be easier to understand. You will
reenter the values later.
c
Close the server properties.
Stop the existing CPM system:
a
Stop accepting transactions. Make sure no CPM clients are submitting
transactions to the server.
b
Settle any open CPM transactions.
c
Stop the CPM Server and close the Administration Client.
d
Make sure the Database Utility is not running.
5
Log in as Root on the target computer.
6
Make a backup copy of the entire CPM /server directory to a location outside of
the /cybersource directory.
7
Untar the software:
8
a
Insert the CPM for Solaris CD into the CD-ROM drive.
b
Change to the CD-ROM mount directory /cdrom/
PaymentManager<version>/unix.
c
Copy the tar file to the directory in which you want to install the CPM
software (you can install it in the same directory where you installed the
previous version; the default installation directory is /opt).
d
Change to the directory where you copied the tar file.
e
Untar the file using tar xvf <filename> to extract the directory structures.
Go to the /server directory backup that you made in step 6 and copy the files
listed below. Paste them into the cybersource/payment_manager/server directory
of the new 6.x installation, overwriting any files of the same name. This step
transfers your configuration information from the previous installation to the new
installation.
–
cpm.cfg
CPM Setup Guide • CyberSource Corporation • January 2006
49
Chapter 6 Upgrading from a Previous Version
–
9
Upgrading from a 5.x Version
<8-character key ID>.key (if you currently use database encryption)
Change the CPMHOME environment variable to point to the location of the new
version of CPM.
10 Upgrade the Windows-based CPM components (specifically the CPM
Administration Client):
a
On the Windows system, insert the CPM CD and run the setup.exe file.
The installation program detects the previous version of the CPM software
and prompts you to modify, repair, or delete the previous version.
b
Select “repair” to upgrade the software to the new version.
c
The installation program upgrades the CPM components that you have
previously installed.
11 With the upgrade, the password for the default administrator (cpm_local_admin)
was changed back to its default (changeoninstall). You must change it from its
default, so log in to the Administration Client with the default administrator
username and change the default password when prompted.
12 Verify that the data for your payment gateway is accurate in the agreement and
gateway settings in the Administration Client. Also follow these gateway-specific
instructions:
a
If you are using the NDC East (Global Payments) gateway and are upgrading
from a version prior to 5.7, reenter the Application ID in the Global Payments
agreement settings.
b
If you are using the FDMS South gateway and are upgrading from a version
prior to 5.1.1, reenter the host IP address and port settings in the FDMS South
gateway settings.
13 Recreate your administrator accounts by using the AcctMaint.exe tool. See Using
the AcctMaint.exe Tool to Manage Administrators on page 22 for instructions.
14 Enable and set up database encryption if you plan to use it but were not using it
prior to the upgrade (you must use it if you want to be PCI compliant; see the
CPM PCI Compliance Guide for information about PCI). For instructions, see the
Unix chapter in the CPM Database Utility Guide.
15 If you are upgrading from a version prior to 5.5.5 and are planning to use the
latest version of the CPM Java SDK (made available first with version 5.5.5), read
For All Java SDK Users: Updating the Security Policy Files on page 62 and update
your security policy files.
16 If you are using CPM’s C Windows API, C Solaris API, or Active X API and are
not already using SSL, set up SSL encryption (you must use it if you want to be
PCI compliant; see the CPM PCI Compliance Guide for information about PCI). See
Setting Up SSL on page 35.
CPM Setup Guide • CyberSource Corporation • January 2006
50
Chapter 6 Upgrading from a Previous Version
Upgrading from a 5.x Version
17 Enable and set up CPM Security if you plan to use it but were not using it prior to
the upgrade (you must use it if you want to be PCI compliant and your system
sends transactions to CPM from outside the framework of your trusted network
environment; see the CPM PCI Compliance Guide for information about PCI). See
Setting Up CPM Security on page 34.
You have upgraded the CPM software. Later, once you have confirmed the installation is
functioning properly, you can delete the /server directory backup that you made earlier.
For Windows
1
Compile a list of your existing administrator account usernames and passwords
as you will need to recreate these accounts later in this procedure (see Creating
and Managing Administrator Accounts on page 21 for more information).
2
Make a backup copy of the entire CPM C:\CyberSource\PaymentManager\Server
directory to a location outside of the CyberSource directory.
3
If you are using the NDC East (Global Payments) gateway and you are upgrading
from a version prior to 5.7:
4
5
a
Open the Administration Client, connect to the CPM Server, and open the
server properties.
b
Go to the gateway settings for NDC East and record the value of the
Application ID. With CPM 5.7 the field has moved from the gateway settings
to the agreement settings, and you will reenter the value later.
c
Close the server properties.
If you are using the FDMS South gateway and you are upgrading from a version
prior to 5.1.1:
a
Open the Administration Client, connect to the CPM Server, and open the
server properties.
b
Go to the gateway settings for FDMS South and record the host IP address
and port settings. With CPM 5.1.1 the layout of the FDMS South gateway
settings dialog box was redesigned to be easier to understand. You will
reenter the values later.
c
Close the server properties.
Stop the existing CPM system:
a
Stop accepting transactions. Make sure no CPM clients are submitting
transactions to the server.
b
Settle any open CPM transactions.
c
Stop the CPM Server and close the Administration Client.
d
Make sure the Database Utility is not running.
CPM Setup Guide • CyberSource Corporation • January 2006
51
Chapter 6 Upgrading from a Previous Version
6
Upgrading from a 5.x Version
Insert the CPM for Windows CD into the CD-ROM drive and run the setup.exe
file.
The installation program detects the previous version of the CPM software and
prompts you to modify, repair, or delete the previous version.
7
Select “repair” to upgrade the software to the new version.
The installation program upgrades the CPM components that you have
previously installed.
8
9
Go to the Server directory backup that you made earlier and copy the files listed
below. Paste them into the Server directory of the new 6.x installation,
overwriting any files with the same name. This step transfers your configuration
information from the previous installation to the new installation.
–
cpm.cfg
–
<8-character key ID>.key (if you currently use database encryption)
If you were using database encryption before the upgrade, import your database
encryption key into the system’s registry (this is a new requirement with CPM
6.x):
a
If you do not already have a backup copy of your database encryption key
file, back it up to a secure storage device.
b
Return to the Server directory and double-click DBKeyGenerator.exe.
c
In the menu, click Import Key.
d
In the dialog box that is displayed, double-click the database encryption key
that you want to import.
e
The key is imported to the registry. You can confirm that the key was
imported by clicking Export Key in the menu. You should see the key in the
list of keys in the registry that are available to export.
f
Click Exit to close the tool.
g
Delete the database encryption key file from the Server directory, as it is no
longer needed there.
h
If you are using multiple CPM Servers, repeat steps b–g above on each of
your CPM Servers.
10 With the upgrade, the password for the default administrator (cpm_local_admin)
was changed back to its default (changeoninstall). You must change it from its
default, so log in to the Administration Client with the default administrator
username and change the default password when prompted.
CPM Setup Guide • CyberSource Corporation • January 2006
52
Chapter 6 Upgrading from a Previous Version
Upgrading from a 4.x or 3.x Version
11 Verify that the data for your payment gateway is accurate in the agreement and
gateway settings in the Administration Client. Also follow these gateway-specific
instructions:
a
If you are using the NDC East (Global Payments) gateway and are upgrading
from a version prior to 5.7, reenter the Application ID in the Global Payments
agreement settings.
b
If you are using the FDMS South gateway and are upgrading from a version
prior to 5.1.1, reenter the host IP address and port settings in the FDMS South
gateway settings.
12 Recreate your administrator accounts by using the AcctMaint.exe tool. See Using
the AcctMaint.exe Tool to Manage Administrators on page 22 for instructions.
13 Enable and set up database encryption if you plan to use it but were not using it
prior the upgrade (you must use it if you want to be PCI compliant; see the CPM
PCI Compliance Guide for information). For instructions, see the Windows chapter
in the CPM Database Utility Guide.
14 If you are upgrading from a version prior to 5.5.5 and are planning to use the
latest version of the CPM Java SDK (made available first with version 5.5.5), read
For All Java SDK Users: Updating the Security Policy Files on page 62 and update
your security policy files.
15 If you are using CPM’s C Windows API, C Solaris API, or Active X API and are
not already using SSL, set up SSL encryption (you must use it if you want to be
PCI compliant; see the CPM PCI Compliance Guide for information about PCI). See
Setting Up SSL on page 35.
16 Enable and set up CPM Security if you plan to use it but were not using it prior to
the upgrade (you must use it if you want to be PCI compliant and your system
sends transactions to CPM from outside the framework of your trusted network
environment; see the CPM PCI Compliance Guide for information about PCI). See
Setting Up CPM Security on page 34.
17 Stop and restart the CPM Server.
You have upgraded the CPM software. Later, once you have confirmed the installation is
functioning properly, you can delete the Server directory backup that you made earlier.
Upgrading from a 4.x or 3.x Version
You can upgrade to CPM 6.x from these 4.x and 3.x versions:
CPM Setup Guide • CyberSource Corporation • January 2006
53
Chapter 6 Upgrading from a Previous Version
•
CPM 4.x.
•
CPM 3.5 SP4 or higher service pack.
Upgrading from a 4.x or 3.x Version
If you are running a CPM 3.5 version that is less than SP4, you must upgrade to
version 3.5 SP4 (or higher service pack) before upgrading to version 6.x.
•
CPM 3.1.9 SP8 or higher service pack.
If you are running a CPM version previous to 3.1.9 SP8, you must first upgrade to
version 3.1.9 SP8 (or higher service pack) before upgrading to version 6.x.
Choosing an Upgrade Strategy
The database table structure has changed with the 5.x/6.x versions and is not compatible
with any previous 4.x or 3.x CPM release. As such, this chapter covers two upgrade
strategies that are discussed in the next two sections.
Installing New Software and Database Tables
In this case, you install new software and database tables, creating a new empty CPM 6.x
database on a separate server. Your current database is not migrated. This strategy is
recommended to avoid downtime or touching your production server. When the new
server has been tested and certified, you can switch from using the old server.
Do not attempt this strategy if you perform Authorization transactions and Capture
transactions separately (which will be the case if there is a delay before you ship the
goods). A Capture sent to your new system for an Authorization performed by your old
system will fail.
Select this strategy if you have the available hardware and you do not rely on your CPM
database data for business operations (as your current database will not be migrated).
Upgrading Existing Software and Database Tables
In this case, you upgrade your existing software and database tables to be compliant with
the new 6.x structure. You use the CPM upgrade program to update your database tables.
This strategy is the simplest of the two options, but comes with the most risk. If you select
this strategy, expect at least two hours of downtime for the server you are upgrading. You
should perform the upgrade when the downtime will have minimal impact on your
customers.
CPM Setup Guide • CyberSource Corporation • January 2006
54
Chapter 6 Upgrading from a Previous Version
Upgrading from a 4.x or 3.x Version
You must plan to test and debug the upgraded server against your client API before
deploying it again in the production environment. Do not upgrade a mission-critical
production server because upgrading and configuring your server might keep your server
offline. Prior to upgrading, you should have a good backup of your system.
Summary of Upgrade Factors
The following table lists factors to consider when choosing an upgrade strategy.
Determine the upgrade factor in the left column that is most important for your situation.
Table 2 Upgrade Factors and Strategies
Install new software and
new database tables
Upgrade existing
software and database
tables
Acceptable downtime
None
Minimum 2 hours
Importance of current CPM
database data *
None
Critical
Size of current CPM database
Not applicable
Large
Use of follow-on Capture **
Not recommended
Recommended
* Is CPM database data used for business operations, such as reconciliation?
** Do not attempt the new installation strategy if you perform Authorization transactions and
Capture transactions separately. (Both strategies support the combined Authorization and
Capture transaction.)
Also consider these additional upgrade factors:
•
•
•
•
•
Current database size: Database size is proportional to the time required to
upgrade the data.
Available hardware and support.
Number of merchants: Some data entry might be required for upgrading existing
systems.
Rollbacks: You will only have the option to stop the upgrade process and roll back
to the old release if you are installing new software and database tables.
Capture lag time: Some processors require a one-hour delay before you may
capture an authorization. If your processor has this type of requirement, make
sure to factor in that delay when calculating downtime.
CPM Setup Guide • CyberSource Corporation • January 2006
55
Chapter 6 Upgrading from a Previous Version
•
Upgrading from a 4.x or 3.x Version
Sequence numbers: If you are upgrading your database tables, your server will
determine the highest sequence number in your CPM database, then start
sequencing numbers from there. This avoids creating duplicate sequence
numbers.
Before Starting the Upgrade
Before starting the upgrade, you must have the following:
•
•
Installation or Upgrade CD for the 6.x version you are upgrading to.
CyberSource license key, which should be the same as your existing license key,
unless you purchased new features with the upgrade.
Before performing the upgrade, consider doing the following:
•
•
Back up the CPM database.
Plan necessary downtime. Perform the upgrade at a time that will have the least
impact on your users.
Upgrading the Software
Follow the instructions for one of the two upgrade strategies:
•
•
Installing new software and database tables (see below)
Upgrading existing software and database tables (see page 59)
Installing New Software and Database Tables
Before continuing with these instructions, make sure you understand the implications of
choosing this upgrade strategy. See Choosing an Upgrade Strategy on page 54 for more
information.
1
Compile a list of your existing administrator account usernames and passwords
as you will need to recreate these accounts later in this procedure (see Creating
and Managing Administrator Accounts on page 21 for more information).
2
Go to the Server directory of your existing system and copy the files listed below
to a temporary directory outside of the CyberSource directory. This step saves
your configuration information from the current installation.
–
cpm.cfg
CPM Setup Guide • CyberSource Corporation • January 2006
56
Chapter 6 Upgrading from a Previous Version
–
3
4
Upgrading from a 4.x or 3.x Version
<8-character key ID>.key (if you currently use database encryption)
If you are using the NDC East (Global Payments) gateway and you are upgrading
to version 5.7 or later:
a
Open the Administration Client on your existing system, connect to the CPM
Server, and open the server properties.
b
Go to the gateway settings for NDC East and record the value of the
Application ID. With CPM 5.7 the field has moved from the gateway settings
to the agreement settings, and you must reenter the value in the agreement
settings later.
c
Close the server properties.
If you are using the FDMS South gateway:
a
Open the Administration Client, connect to the CPM Server, and open the
server properties.
b
Go to the gateway settings for FDMS South and record the host IP address
and port settings. With CPM 5.1.1 the layout of the FDMS South gateway
settings dialog box was redesigned to be easier to understand. You will
reenter the values later.
c
Close the server properties.
5
Install the CPM 6.x software on the new system. See Chapter 4, Installing CPM
Server Software, on page 20 for installation instructions.
6
Paste the files that you copied in step 2 to the Server directory on the new system,
overwriting any existing files of the same name that are there. This transfers your
configuration information to the new CPM version.
7
If you are using a Windows-based CPM Server and were using database
encryption before the upgrade, import your database encryption key into the
CPM Server’s registry (this is a new requirement with CPM 6.x):
a
If you do not already have a backup copy of your database encryption key
file, back it up to a secure storage device.
b
Return to the Server directory and double-click DBKeyGenerator.exe.
c
In the menu, click Import Key.
d
In the dialog box that is displayed, double-click the database encryption key
that you want to import.
e
The key is imported to the registry. You can confirm that the key was
imported by clicking Export Key in the menu. You should see the key in the
list of keys in the registry that are available to export.
CPM Setup Guide • CyberSource Corporation • January 2006
57
Chapter 6 Upgrading from a Previous Version
Upgrading from a 4.x or 3.x Version
f
Click Exit to close the tool.
g
Delete the database encryption key file from the Server directory, as it is no
longer needed there.
h
If you are using multiple CPM Servers, repeat steps b–g above on each of
your CPM Servers.
8
With the upgrade, the password for the default administrator (cpm_local_admin)
was changed back to its default (changeoninstall). You must change it from its
default, so log in to the Administration Client with the default administrator
username and change the default password when prompted.
9
Configure your merchants and agreements in the Administration Client. Also
follow these gateway-specific instructions:
a
If you are using the NDC East (Global Payments) gateway, enter the
Application ID in the Global Payments agreement settings.
b
If you are using the FDMS South gateway, reenter the host IP address and
port settings in the FDMS South gateway settings.
10 Recreate your administrator accounts by using the AcctMaint.exe tool. See Using
the AcctMaint.exe Tool to Manage Administrators on page 22 for instructions.
11 Set up database encryption if you plan to use it and were not using it prior to the
upgrade (you must use it if you want to be PCI compliant; see the CPM PCI
Compliance Guide for information about PCI). Encryption is automatically enabled
when you install 6.x, but you still need to set it up if you were not using it before
you upgraded. If you were using database encryption before the upgrade, you
can use the same database encryption key you were using before. See the CPM
Database Utility Guide for instructions on setting up database encryption.
12 If you are planning to use the latest version of the CPM Java SDK (made available
first with version 5.5.5), read For All Java SDK Users: Updating the Security
Policy Files on page 62 and update your security policy files.
13 If you are not already using SSL, set up SSL encryption (you must use it if you
want to be PCI compliant; see the CPM PCI Compliance Guide for information
about PCI). See Setting Up SSL on page 35.
14 Set up CPM Security if you plan to use it (you must use it if you want to be PCI
compliant and your system sends transactions to CPM from outside the
framework of your trusted network environment; see the CPM PCI Compliance
Guide for information about PCI). CPM Security is automatically enabled when
you install 6.x, but you still must set up your Security groups and create the
usernames/passwords on the new system. See Setting Up CPM Security on
page 34.
CPM Setup Guide • CyberSource Corporation • January 2006
58
Chapter 6 Upgrading from a Previous Version
Upgrading from a 4.x or 3.x Version
15 Once the new system is set up, stop the old CPM system and switch to the new
system.
16 Settle any open CPM transactions on the old system.
You have installed the new software.
Upgrading Existing Software and Database Tables
Before continuing with these instructions, make sure you understand the implications of
choosing this upgrade strategy. See Choosing an Upgrade Strategy on page 54 for more
information.
1
Compile a list of your existing administrator account usernames and passwords
as you will need to recreate these accounts later in this procedure (see Creating
and Managing Administrator Accounts on page 21 for more information).
2
Make a backup copy of the entire CPM server directory to a location outside of
the c:\CyberSource directory.
3
If you are using the NDC East (Global Payments) gateway and you are upgrading
to version 5.7 or later:
4
5
a
Open the Administration Client on your existing system, connect to the CPM
Server, and open the Server Properties.
b
Go to the gateway settings for NDC East and record the value of the
Application ID. With CPM 5.7 the field has moved from the gateway settings
to the agreement settings, and you must reenter the value in the agreement
settings later.
c
Close the Server Properties.
If you are using the FDMS South gateway and you are upgrading to version 5.1.1
or later:
a
Open the Administration Client on your existing system, connect to the CPM
Server, and open the server properties.
b
Go to the gateway settings page for FDMS South and record the host IP
address and port settings. With CPM 5.1.1 the layout of the FDMS South
gateway settings dialog box was redesigned to be easier to understand. You
will reenter the values later.
c
Close the server properties.
Stop the existing CPM system:
a
Stop accepting transactions. Make sure no CPM clients are submitting
transactions to the server.
b
Settle any open CPM transactions.
CPM Setup Guide • CyberSource Corporation • January 2006
59
Chapter 6 Upgrading from a Previous Version
Upgrading from a 4.x or 3.x Version
c
Stop the CPM Server and close the Administration Client.
d
Make sure the Database Utility is not running.
6
For Windows-based systems: Uninstall your existing 3.x or 4.x software by using
the Add/Remove Programs feature.
7
Install the CPM 6.x software. See Chapter 4, Installing CPM Server Software, on
page 20 for installation instructions.
8
For Unix users: Change the CPMHOME environment variable to point to the
location of the new version of CPM.
9
Go to the server directory backup that you made in step 2 and copy and paste the
files listed below into the server directory of the 6.x installation, overwriting any
files of the same name. This step transfers your configuration information from
the previous installation.
–
cpm.cfg
–
<8-character key ID>.key (if you use database encryption)
10 If you are using a Windows-based CPM Server and were using database
encryption before the upgrade, import your database encryption key into the
CPM Server’s registry (this is a new requirement with CPM 6.x):
a
If you do not already have a backup copy of your database encryption key
file, back it up to a secure storage device.
b
Return to the Server directory and double-click DBKeyGenerator.exe.
c
In the menu, click Import Key.
d
In the dialog box that is displayed, double-click the database encryption key
that you want to import.
e
The key is imported to the registry. You can confirm that the key was
imported by clicking Export Key in the menu. You should see the key in the
list of keys in the registry that are available to export.
f
Click Exit to close the tool.
g
Delete the database encryption key file from the Server directory as it is no
longer needed there.
h
If you are using multiple CPM Servers, repeat steps b–g above on each of
your CPM Servers.
11 With the upgrade, the password for the default administrator (cpm_local_admin)
was changed back to its default (changeoninstall). You must change it from its
CPM Setup Guide • CyberSource Corporation • January 2006
60
Chapter 6 Upgrading from a Previous Version
Upgrading from a 4.x or 3.x Version
default, so log in to the Administration Client with the default administrator
username and change the default password when prompted.
12 Verify that the data for your payment gateway is accurate in the agreement and
gateway settings in the Administration Client. Also follow these gateway-specific
instructions:
a
If you are using the NDC East (Global Payments) gateway, reenter the
Application ID in the Global Payments agreement settings.
b
If you are using the FDMS South gateway, reenter the host IP address and
port settings in the FDMS South gateway settings.
13 Recreate your administrator accounts by using the AcctMaint.exe tool. See Using
the AcctMaint.exe Tool to Manage Administrators on page 22 for instructions.
14 For Unix users: Update your database tables. See the CPM Database Utility Guide
for instructions.
15 Set up database encryption if you plan to use it and were not using it prior to the
upgrade (you must use it if you want to be PCI compliant; see the CPM PCI
Compliance Guide for information about PCI). Encryption is automatically enabled
when you install 6.x, but you still need to set it up if you were not using it before
you upgraded. See the CPM Database Utility Guide for instructions.
16 If you are planning to use the latest version of the CPM Java SDK (made available
first with version 5.5.5), read For All Java SDK Users: Updating the Security
Policy Files on page 62 and update your security policy files.
17 If you are not already using SSL, set up SSL encryption (you must use it if you
want to be PCI compliant; see the CPM PCI Compliance Guide for information
about PCI). See Setting Up SSL on page 35.
18 Set up CPM Security if you plan to use it but were not using it prior to the
upgrade (you must use it if you want to be PCI compliant and your system sends
transactions to CPM from outside the framework of your trusted network
environment; see the CPM PCI Compliance Guide for information about PCI). CPM
Security is automatically enabled when you install 6.x, but if you were not using it
prior to the upgrade, you still must set up your Security groups and create the
usernames/passwords for all the CPM users. See Setting Up CPM Security on
page 34.
You have completed the upgrade. Later, once you have confirmed the installation is
functioning properly, you can delete the server directory backup that you made earlier.
CPM Setup Guide • CyberSource Corporation • January 2006
61
Chapter 7
Using the Java SDK and SSL Proxy
Server
The CPM Java SDK that is available with CPM 5.5.5 and later is built on Java 1.4.2. You can
use the SDK with or without SSL. If you plan to use SSL, you must use the CPM SSL Proxy
Server. This chapter describes how to install and configure the Java SSL Proxy Server and
includes these sections:
For All Java SDK Users: Updating the Security Policy Files
For Users of Previous Versions of the Java SDK
Installing the SSL Proxy Server
Keystore Management
Configuration
Troubleshooting
For All Java SDK Users: Updating the Security
Policy Files
If you are using the new Java SDK either with or without SSL, you must update the
security policy files that Java uses so as to accommodate strong encryption. This is
because the SDK uses the JCE implementation of the Blowfish encryption algorithm
whether or not SSL is used, and the key size that this algorithm uses is larger than the size
allowed by the default Java security policy files.
For Windows
For Windows users, if you use the installer to install the SDK, the Install Shield Wizard
automatically updates these security policy files for you. If you do not use the installer,
you need to update the files manually using the procedure below.
Note The CPM installation CD includes the security policy files used for Java 1.4.2
from Sun Microsystems®. Sun posts the latest version of the policy files for download on their Web site. If you are using a Java implementation from a supplier other
CPM Setup Guide • CyberSource Corporation • January 2006
62
Chapter 7 Using the Java SDK and SSL Proxy Server
For Users of Previous Versions of the Java SDK
than Sun, check with the supplier to ensure that you have the appropriate security
policy files for strong encryption.
1
Go to the Client APIs\Java API directory on the CPM installation CD and locate
the following files:
local_policy.jar
US_export_policy.jar
2
Replace the following existing files in your Java installation with the files from
step 1:
<Java Home Directory>\<jre>\lib\security\local_policy.jar
<Java Home Directory>\<jre>\lib\security\US_export_policy.jar
You have updated the security policy files for strong encryption.
For Solaris
For Solaris users, you need to update the files manually (see Updating Your Java
Installation for Strong Encryption on page 67).
For Users of Previous Versions of the Java SDK
The previous versions of the CPM Java SDK used EccpressoAll.jar and SSLPlus.jar. The
new Java SDK does not use these files; if you switch to use the new Java SDK you can
remove references to those .jar files from your classpath.
Installing the SSL Proxy Server
To install the SSL Proxy Server, use the following instructions for Windows and Solaris.
Windows
To install the Java SSL Proxy Server and automatically update the security policy files:
CPM Setup Guide • CyberSource Corporation • January 2006
63
Chapter 7 Using the Java SDK and SSL Proxy Server
1
Installing the SSL Proxy Server
Run the regular CPM installation.
The Install Shield Wizard starts and steps you through the process.
2
When prompted for which parts of the CPM Server to install, select the check box
for the SSL Proxy Service.
The SSL Proxy Server will be installed in
c:\Program Files\CyberSource\PaymentManager\Server.
CPM Setup Guide • CyberSource Corporation • January 2006
64
Chapter 7 Using the Java SDK and SSL Proxy Server
Installing the SSL Proxy Server
3
When prompted, select the directory where Java is installed. Ensure that the
directory you select is the current working Java directory in the environment. The
SSL Proxy Service loads the JVM from this directory, and the installer looks here
when updating the existing security policy files for strong encryption.
4
Complete the installation with the Install Shield Wizard and reboot the system.
5
In the CPM Administration Client, open the server properties for your CPM
Server, go to the CPM Server tab, and make sure the Java SSL Transaction Port is
set to 0. You need to do this because the SSL Proxy Server, not the CPM Server,
controls which port CPM uses for Java SSL transactions. See Ports on page 66 for
more information.
CPM Setup Guide • CyberSource Corporation • January 2006
65
Chapter 7 Using the Java SDK and SSL Proxy Server
Installing the SSL Proxy Server
6
Install the default keystores provided with the CPM installation CD or recreate
the keystores for an additional level of security (see Keystore Management on
page 69 for instructions).
7
Configure the properties for the Proxy Server and SDKs as needed (see
Configuration on page 71).
You have installed and configured the SSL Proxy Server. It is now ready to use.
Starting the Service
To start the service for the first time, reboot the computer. The new service program for the
SSL Proxy Server automatically starts when the computer is booted. You never need to
stop this program even if you stop the CPM Server. The CPM Server does not need to be
running for the service to be started; however, if the Proxy Service is running and the CPM
Server has not yet been started, transactions that are sent to the Proxy Server will fail.
Ports
By default, the Proxy Server uses port 1531 for Java SSL connections and port 1530 for the
CPM Server connection. To change these, see Configuration on page 71.
Important If you are migrating from an older version of the CPM Java SDK to the
current one available with CPM 5.5.5 and later, be aware that the current SDK and
SSL Proxy Server default to using port 1531 to communicate. If you are already
using port 1531 with an older version of the Java SDK, when you install the SSL
Proxy Server, make sure to configure it and the application using the new Java SDK
to use a port other than 1531.
Solaris
To install the Java SSL Proxy Server:
1
If you have not already done so, untar the main CPM installation .tar file that
contains the rest of the Solaris CPM files (see Installing CPM Software on Unix on
page 28). The Proxy Server is automatically installed in the cybersource/
payment_manager/server directory when you untar the file.
2
In the CPM Administration Client, open the server properties for your CPM
Server, go to the CPM Server tab, and make sure the Java SSL Transaction Port is
set to 0. You need to do this because the SSL Proxy Server, not the CPM Server,
CPM Setup Guide • CyberSource Corporation • January 2006
66
Chapter 7 Using the Java SDK and SSL Proxy Server
Installing the SSL Proxy Server
controls which port CPM uses for Java SSL transactions. See Ports on page 68 for
more information.
3
Update your security policy files (see Updating Your Java Installation for Strong
Encryption on page 67 below).
4
Install the default keystores provided with the CPM installation CD or recreate
the keystores for an additional level of security (see Keystore Management on
page 69 for instructions).
5
Configure the properties for the Proxy Server and SDKs as needed (see
Configuration on page 71).
You have installed and configured the SSL Proxy Server. It is now ready to use.
Updating Your Java Installation for Strong Encryption
The security policy files for the default Java installation allow only weak encryption. To
use the Java SDK (with or without the SSL Proxy Server), you must update your policy
files for strong encryption.
Note The CPM installation CD includes the security policy files used for Java 1.4.2
from Sun Microsystems®. Sun posts the latest version of the policy files for download on their Web site. If you are using a Java implementation from a supplier other
than Sun, check with the supplier to ensure that you have the appropriate security
policy files for strong encryption.
1
Go to the cybersource/payment_manager/server directory and locate the
following files:
CPM Setup Guide • CyberSource Corporation • January 2006
67
Chapter 7 Using the Java SDK and SSL Proxy Server
Installing the SSL Proxy Server
local_policy.jar
US_export_policy.jar
2
Replace the following existing files in your Java installation with the files from
step 1:
$(JAVA_HOME)/lib/security/local_policy.jar
$(JAVA_HOME)/lib/security/US_export_policy.jar
You have updated the security policy files for strong encryption.
Starting the Service
The Proxy Server is a Java application that you start with these steps:
1
Go to the cybersource/payment_manager/server directory.
2
Type the following at a command line:
java -cp Proxy.jar lcc.proxy.Proxy
The Proxy Server starts.
You never need to stop this program even if you stop the CPM Server. The CPM Server
does not need to be running for the service to be started; however, if the Proxy Service is
running and the CPM Server has not yet been started, transactions that are sent to the
Proxy Server will fail.
Ports
By default, the Proxy uses port 1531 for Java SSL connections and port 1530 for the CPM
Server connection. To change these, see Configuration on page 71.
Important If you are migrating from an older version of the CPM Java SDK to the
current one available with CPM 5.5.5 and later, be aware that the current SDK and
SSL Proxy Server default to using port 1531 to communicate. If you are already
using port 1531 with an older version of the Java SDK, when you install the SSL
Proxy Server, make sure to configure it and the application using the new Java SDK
to use a port other than 1531.
CPM Setup Guide • CyberSource Corporation • January 2006
68
Chapter 7 Using the Java SDK and SSL Proxy Server
Keystore Management
Keystore Management
One of the important reasons to use SSL with CPM is that SSL is able to validate the
identity of both the server and the client in the Web-based client-server relationship. The
CPM Java SDK and SSL Proxy Server employ both server-side and client-side validation.
This means that the Proxy Server needs to have the public key certificate for each of the
clients (SDKs) that will be connecting to it, and each SDK needs to have the public key
certificate for the Proxy Server. The certificates are stored in keystore files that you must
distribute appropriately.
Using the Default Keystore Files
The default keystore files are located in the directory that contains the Proxy Server. On
Windows this defaults to c:\Program Files\CyberSource\PaymentManager\Server and on
Solaris this defaults to cybersource/payment_manager/server. The files are called default_
proxy_keystore and default_client_keystore. You can use these default keystore files to get
up and running. They provide a measure of security that is equivalent to that supplied by
the original version of the CPM Java SDK.
To use the default keystore files, simply copy the default_client_keystore file to the
working directory of the application that will be using the SDK. You do not need to
relocate the default_proxy_keystore file.
Recreating the Default Keystore Files
For additional security, you can recreate the default keystores with new random key
material. By distributing the recreated client keystore to the SDK instances, you ensure
that only those SDK instances can connect to the Proxy Server and that the SDK instances
can connect only to that particular Proxy Server.
To create your own version of the default keystores:
1
At a command prompt, go to the directory where the Proxy Server is installed
(c:\Program Files\CyberSource\PaymentManager\Server for Windows or
cybersource/payment_manager/server for Solaris).
2
Run the script create_default_keystore.bat (for Windows) or create_default_
keystore.sh (for Solaris).
The script creates a new default_proxy_keystore file and default_client_keystore
file and places them in the current directory.
CPM Setup Guide • CyberSource Corporation • January 2006
69
Chapter 7 Using the Java SDK and SSL Proxy Server
3
Keystore Management
Copy the new default_client_keystore file to the working directory of the
application that will be using the SDK. You do not need to relocate the default_
proxy_keystore file.
You have recreated the default keystores.
Creating Unique Keystores for Each SDK Instance
For maximum security, you can create a separate keystore for each individual SDK
instance that you use. In this case, the keystore that the Proxy Server uses contains the
public certificate for each individual SDK instance. If necessary, you could prevent a
specific SDK instance from connecting to the Proxy Server by invalidating that SDK’s
certificate in the Proxy Server’s keystore. This level of security can be useful in instances
where access to a CPM Server is being re-sold to outside parties.
To create unique keystores for each SDK instance:
1
Recreate the default keystore files as described in step 1 and step 2 in Recreating
the Default Keystore Files on page 69.
2
Determine the naming convention you want to use for the keystores. The
keystores will be called <sdk instance name>_client_keystore. Do not use
spaces or special characters except underscores or hyphens in the SDK instance
name.
3
From the same directory that you used in step 1, run the script create_client_
keystore.bat (for Windows) or create_client_keystore.sh (for Solaris), giving the
name of one of the SDK instances as a parameter to the script. For example, for
Windows:
run create_client_keystore.bat client1
This creates a file named client1_client_keystore in the current directory.
4
Repeat step 3 for each SDK instance.
5
Copy each of the new client keystore files to the corresponding machines (to the
working directory of the application that will be using the SDK).
6
For each SDK, update the cybs.client.keystore system property to use the new
client keystore file (see Configuration below).
You have created a unique keystore for each SDK instance.
CPM Setup Guide • CyberSource Corporation • January 2006
70
Chapter 7 Using the Java SDK and SSL Proxy Server
Configuration
Configuration
The Proxy Server and SDK automatically use default values for the ports, SSL protocol
level, certificate algorithm, and other properties. These defaults are appropriate for the
majority of merchants. If, however, you have designed your system so that it uses custom
security settings, you can modify the behavior of the Proxy Server and the SDK by
changing the values of the system properties listed in Table 3 below (for the Proxy Server)
and Table 4 on page 72 (for the SDK). Also, if you create unique keystores for the SDKs,
you must update each SDK’s cybs.client.keystore system property.
The sections following the tables explain how to change the properties if using Windows
or if using Solaris.
Proxy Server System Properties
Table 3 Proxy Server System Properties
Property Name
Default Value
Description
cybs.keystore.type
Default keystore type as specified by
java.security (usually JKS)
Keystore type.
cybs.certificate.algorithm
Default certificate algorithm as specified in
java.security (usually RSA)
Certificate algorithm.
cybs.ssl.protocol
TLS
SSL protocol level.
cybs.cpm.server.port
1530
The port that CPM uses for non-SSL
transactions.
cybs.ssl.port
1531
The port that the Proxy Server uses for
SSL connections.
cybs.proxy.keystore
default_proxy_keystore
Name of the keystore that the Proxy
Server uses for validating SDKs.
CPM Setup Guide • CyberSource Corporation • January 2006
71
Chapter 7 Using the Java SDK and SSL Proxy Server
Configuration
SDK System Properties
Table 4 SDK System Properties
Property Name
Default Value
Description
cybs.keystore.type
Default keystore type as specified by
java.security (usually JKS)
Keystore type.
cybs.certificate.algorithm
Default certificate algorithm as specified in
java.security (usually RSA)
Certificate algorithm.
cybs.ssl.protocol
TLS
SSL protocol level.
cybs.client.keystore
default_client_keystore
Name of the keystore file that the SDK
uses to validate SSL connections.
Setting the Properties
You set the properties for the Proxy Server or the SDK in the corresponding machine’s
Java System Properties.
Windows
To add the properties to the Java System Properties:
1
At a command prompt, run the Registry Editor (regedit.exe).
2
Open the following key:
HKEY_LOCAL_MACHINE\SYSTEM\ControlSet001\Services\CPMSSLProxy\
Parameters
CPM Setup Guide • CyberSource Corporation • January 2006
72
Chapter 7 Using the Java SDK and SSL Proxy Server
3
Edit the AppParameters value.
4
For each property that you want to set, type
Configuration
|-Dproperty_name=value
The initial character is a pipe (|). Separate each property that you set in the list
with a pipe.
5
Close the Registry Editor.
You have set the system properties.
Solaris
You can set the Proxy Server’s system properties by using the -D command line option
when you start the service:
% java -cp Proxy.jar -Dproperty_name=value lcc.proxy.Proxy
CPM Setup Guide • CyberSource Corporation • January 2006
73
Chapter 7 Using the Java SDK and SSL Proxy Server
Troubleshooting
For detailed instructions about using the -D command line option, type java -help.
Troubleshooting
This section includes items to check if you have problems with the Java SDK and Proxy
Server.
Important Currently, the error message that CPM returns if a transaction fails is
misleading and is similar to the message that is returned when a successful transaction is processed.
A failed transaction returns 109=Success, but it does not return a sequence number
in the 105 field.
A successful transaction returns 109=Success, but it DOES return a sequence number in the 105 field.
J2SE 1.4.2-b28
J2SE 1.4.2-b28 does not work.
Keystore Conflicts
If you are running SSL and experience conflicts with the default keystore files, make sure
you are using JVM 1.4.2.-05 or higher.
Verifying Port 1531 Is Open
You can verify that port 1531 is open by opening a command prompt and typing:
run netstat -an
Verifying Policy Files Were Updated
You can verify that the policy files have been correctly updated by checking their size: The
new files are 5 KB.
Running Transactions with and without SSL:
The Java API comes with a run.bat file that sends a test transaction to the CPM Server. To
run a test transactions with and without SSL:
CPM Setup Guide • CyberSource Corporation • January 2006
74
Chapter 7 Using the Java SDK and SSL Proxy Server
Troubleshooting
1
In the Administration Client, make sure the CPM merchant is set up properly for
the gateway and the card type.
2
Modify the run.bat file so that is has the appropriate IP address and merchant ID.
3
Run without SSL:
a
Open a command prompt and run the compile.bat file by typing:
compile
The command prompt returns to a prompt to indicate a successful
compilation.
b
4
Run the run.bat file without SSL to ensure your policy files have been correctly
updated.
-
If the policy files have been correctly updated, you receive 109=Success,
and the 105 field (the sequence number) is populated with a sequence
number.
-
Otherwise, if the policy files have NOT been correctly updated, you still
receive 109=Success, but the 105 field is NOT POPULATED. See For All
Java SDK Users: Updating the Security Policy Files on page 62 for
instructions on updating your policy files.
Run with SSL:
a
Edit the run.bat file to add -ssl as the last argument.
b
Again run the compile.bat file as you did previously
c
Run the run.bat file to observe a successful SSL transaction.
If Proxy Service Does Not Open Port 1531 upon Startup with JVM 1.4.2
If the Proxy Service says “started” but does not open port 1531 for listening, check to make
sure in the registry that the JVM path has been set properly. To do this:
1
Open the registry and go to HKEY_LOCAL_MACHINE > SYSTEM >
ControlSet001 > Services > CPMSSLProxy > Parameters.
2
Verify the AppParameters contains:
-Djava.class.path=<path to Proxy.jar>|wrkdir=<CPM Server directory path>
|jvmpath=<jvm.dll path>
For example:
-Djava.class.path=C:\Program
Files\CyberSource\PaymentManager\Server\Proxy.jar|wrkdir=C:\Program
Files\CyberSource\PaymentManager\Server|jvmpath=C:\j2sdk1.4.2_
09\jre\bin\client\jvm.dll
CPM Setup Guide • CyberSource Corporation • January 2006
75
Chapter 7 Using the Java SDK and SSL Proxy Server
Troubleshooting
If Proxy Service Does Not Open Port 1531 upon Startup with JVM 1.5.0
JVM 1.5.0 will run as a service with some modification to the registry.
When you run the proxy, use the following switch:
-Dcybs.certificate.algorithm=SunX509
This switch is needed because the JCE that JVM 1.5.0 uses has a new default
KeyManagerFactory algorithm called PKIX. However, CPM requires the use of the old
default SunX509 algorithm.
For Windows users launching the proxy as a service, you can add the switch to the
registry:
1
Open the registry and go to HKEY_LOCAL_MACHINE > SYSTEM >
ControlSet001 > Services > CPMSSLProxy > Parameters.
2
Verify the AppParameters contains:
-Djava.class.path=<path to Proxy.jar>|wrkdir=<CPM Server directory path>
|jvmpath=<jvm.dll path>|-Dcybs.certificate.algorithm=SunX509
CPM Setup Guide • CyberSource Corporation • January 2006
76
Index
A
Access database 11
AcctMaint.exe 21
Administration Client 2
Administration Server 2
administrators 21
APIs 2
architecture of CPM 2
auxiliary software 7
C
Client APIs 2
communication connection, setup 7
CPM Administration Client 2
CPM Administration Server 2
CPM Client 9
CPM Security 34
CPM server
described 1
environment 6
software 6
testing 10
CPM Windows Client 2
cpm_admin file 21
cpm_local_admin 21
CyberSource Connect 7, 9
requirements for Unix 6
requirements for Windows 5
setup 7
size 11
Unix setup 14
Windows setup 11
Database Utility 9
DB2 5
DSN connections, testing 19
E
encryption, database 9
F
failover servers 43
FTP tool for NOVA gateway 33
G
gateways, setup 9
H
hardware requirements
Unix 5
Windows 4
D
I
data source 13
data source name 9
Unix 18
Windows 12
database
encryption 9
password 13
preparing 9
installation
checklist 6
CPM client software 41
CPM software 8, 20
on Unix system 28
on Windows system 23
OpenLink 14
SSL Proxy Server 62
CPM Setup Guide • CyberSource Corporation • January 2006
77
Index
ISDN line 7
S
J
security 34
server database, preparing 9
server, testing 10
servers, multiple 43
size of database 11
software requirements
Unix 5
Windows 4
SQL Server 5, 11, 13
SSL for C APIs or Active X API 35
SSL Proxy Server 62
Unix 31
Windows 25
SSL with Java 62
Unix 31
Windows 25
Sybase 5, 6, 14
system components 1
system requirements
Unix 5
Windows 4
Java SDK 62
Unix 31
Windows 25
K
keystores for Java SSL Proxy Server 69
L
license key 21
M
Microsoft
Access database 11
SQL Server 5, 11, 13
multiple servers, using 43
N
network interface card
Unix 5
Windows 4
NOVA gateway FTP 33
T
testing
CPM server 10
DSN connections 19
O
U
OpenLink 6, 14
Oracle 5, 6, 14
uninstalling CPM software for Unix 33
upgrading software 48
P
W
passwords 21
payment gateways, setup 9
production mode 10
protocol stack 5, 6
Windows Administration Tools 14
Windows Client 2
Windows server 4, 6, 11
R
Relational Database Management System
(RDBMS) 11
CPM Setup Guide • CyberSource Corporation • January 2006
78
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement