Rocket U2 Clients and APIs September 2015 UCC...

Rocket U2 Clients and APIs

Administrative Supplement for Current andLegacy Client APIs

September 2015

September 2015UCC-S2015-SUPP-UG-01

2

NoticesEdition

Publication date: September 2015Book number: UCC-S2015-SUPP-UG-01Product version: September 2015

Copyright© Rocket Software, Inc. or its affiliates 1988-2015. All Rights Reserved.

Trademarks

Rocket is a registered trademark of Rocket Software, Inc. For a list of Rocket registered trademarks goto: www.rocketsoftware.com/about/legal. All other products or services mentioned in this documentmay be covered by the trademarks, service marks, or product names of their respective owners.

Examples

This information might contain examples of data and reports. The examples include the names ofindividuals, companies, brands, and products. All of these names are fictitious and any similarity tothe names and addresses used by an actual business enterprise is entirely coincidental.

License agreement

This software and the associated documentation are proprietary and confidential to Rocket Software,Inc. or its affiliates, are furnished under license, and may be used and copied only in accordance withthe terms of such license.

Note: This product may contain encryption technology. Many countries prohibit or restrict theuse, import, or export of encryption technologies, and current use, import, and export regulationsshould be followed when exporting this product.

http://www.rocketsoftware.com/about/legal

3

Corporate informationRocket Software, Inc. develops enterprise infrastructure products in four key areas: storage, networks,and compliance; database servers and tools; business information and analytics; and applicationdevelopment, integration, and modernization.

Website: www.rocketsoftware.com

Rocket Global Headquarters77 4th Avenue, Suite 100Waltham, MA 02451-1468USA

To contact Rocket Software by telephone for any reason, including obtaining pre-sales informationand technical support, use one of the following telephone numbers.

Country Toll-free telephone number

United States 1-855-577-4323Australia 1-800-823-405Belgium 0800-266-65Canada 1-855-577-4323China 800-720-1170France 0800-180-0882Germany 08-05-08-05-62Italy 800-878-295Japan 0800-170-5464Netherlands 0-800-022-2961New Zealand 0800-003210South Africa 0-800-980-818United Kingdom 0800-520-0439

Contacting Technical Support

The Rocket Customer Portal is the primary method of obtaining support. If you have currentsupport and maintenance agreements with Rocket Software, you can access the Rocket CustomerPortal and report a problem, download an update, or find answers to in the U2 Knowledgebase.To log in to the Rocket Customer Portal or to request a Rocket Customer Portal account, go towww.rocketsoftware.com/support.

In addition to using the Rocket Customer Portal to obtain support, you can send an email [email protected] or use one of the following telephone numbers.

Country Telephone number

North America +1 800 729 3553United Kingdom/France +44 (0) 800 773 771 or +44 (0) 20 8867 3691Europe/Africa +44 (0) 20 8867 3692Australia +1 800 707 703 or +61 (0) 29412 5450New Zealand +0800 505 515

http://www.rocketsoftware.com

http://www.rocketsoftware.com/support

mailto:[email protected]

4

Contents

Notices................................................................................................................................................................................... 2

Corporate information......................................................................................................................................................... 3

Chapter 1: Introduction........................................................................................................................................................6UCI..............................................................................................................................................................................6UniOLEDB.................................................................................................................................................................. 6InterCall..................................................................................................................................................................... 6UniObjects................................................................................................................................................................. 6UniObjects for Java.................................................................................................................................................. 7UniObjects for .NET...................................................................................................................................................7JDBC Driver for UniVerse and UniData................................................................................................................... 7

Chapter 2: Maintaining the UniRPC.....................................................................................................................................8System requirements............................................................................................................................................... 8How the UniRPC works............................................................................................................................................ 8Maintaining the UniRPC........................................................................................................................................... 8

UniRPC maintenance on UniVerse systems................................................................................................9Defining the UniRPC port number (UniVerse Only)........................................................................9Maintaining the hosts file (UniVerse Only)....................................................................................10Adding a node.................................................................................................................................10Modifying a node............................................................................................................................ 10Removing a node............................................................................................................................10Starting the UniRPC on Windows platforms.................................................................................10From the Control Panel..................................................................................................................11From the UniVerse Control Panel..................................................................................................11At the MS-DOS prompt...................................................................................................................11Stopping the UniRPC on Windows platforms...............................................................................11From the Control Panel..................................................................................................................11From the UniVerse Control Panel..................................................................................................12At the MS-DOS prompt...................................................................................................................12Starting the UniRPC daemon on UNIX systems............................................................................12Stopping the UniRPC daemon on UNIX systems..........................................................................12

UniRPC maintenance on UniVerse servers............................................................................................... 12About the unirpcservices file................................................................................................................................. 13

UniVerse systems........................................................................................................................................ 13UniData systems......................................................................................................................................... 14

Chapter 3: The UCI Configuration Editor.......................................................................................................................... 15UCI configuration file..............................................................................................................................................15System requirements............................................................................................................................................. 15Starting the UCI Configuration Editor...................................................................................................................16Creating the UciCfgFile key in the registry........................................................................................................... 16Adding a data source............................................................................................................................................. 17Adding a parameter................................................................................................................................................18Data source parameters.........................................................................................................................................19Modifying a data source.........................................................................................................................................22Deleting a data source........................................................................................................................................... 23Creating a UCI configuration file........................................................................................................................... 23Opening an alternative UCI configuration file......................................................................................................23

Reverting to the default uci.config file..................................................................................................... 23Securing configuration files................................................................................................................................... 23Modifying a configuration file and making comments........................................................................................ 24

New data source parameters and comments.......................................................................................... 24

Contents

5

Chapter 4: Accessing UniVerse Accounts.......................................................................................................................... 25Running concurrent UniVerse versions.................................................................................................................25

Running UCI, UniVerse ODBC, or UniOLEDB concurrently.......................................................................25Running InterCall, UniObjects, or UniObjects for Java concurrently......................................................26

Tracing events.........................................................................................................................................................26

Chapter 5: Device licensing................................................................................................................................................27Licensing modes..................................................................................................................................................... 27

Session licensing.........................................................................................................................................27Device licensing.......................................................................................................................................... 27

Why do I need device licensing?............................................................................................................................27Device licensing requirements...................................................................................................................28

Connection types.................................................................................................................................................... 28Direct connections......................................................................................................................................28Two-tier connections..................................................................................................................................28Multiple-tier connections........................................................................................................................... 28Using device subkeys................................................................................................................................. 29

Chapter 6: The U2 SSL Configuration Editor.................................................................................................................... 30About SSL property lists.........................................................................................................................................30List encryption........................................................................................................................................................ 30Working with SSL property lists............................................................................................................................ 31Loading and decrypting an SSL property list....................................................................................................... 31SSL properties.........................................................................................................................................................31

SSLVersion={SSLv3 | TLSv1 | TLSv1.1 | TLSv1.2}....................................................................................... 31CertificateStoreType={U2 | Windows}....................................................................................................... 31CACertificate=<cert-path>[;<cert-path>...]................................................................................................ 32MyCertificate=<cert-path>..........................................................................................................................32MyPrivateKey=<key-path>..........................................................................................................................33PrivateKeyPassword=<pass-phrase>.........................................................................................................33CRL=<cert-path>......................................................................................................................................... 33AuthenticationDepth=<level>.................................................................................................................... 34CipherSuite=<cipher-suite-string>............................................................................................................. 34TrustedPeerName=<trusted-peer-name-string........................................................................................ 34AuthenticationStrength=[STRICT | GENEROUS]....................................................................................... 34CertificatePath=[DEFAULT | RELATIVE | PATH=<path> | ENV=<env-var>]................................................35ClientAuthentication=[TRUE | FALSE]........................................................................................................35RandomFileLocation=<directory-path>.................................................................................................... 36

Starting the SSL Configuration Editor...................................................................................................................36Creating an SSL property list.................................................................................................................................37

Specifying certificates................................................................................................................................ 39Specifying authentication properties, CRLs, and cipher suites...............................................................41

Editing an existing SSL property list..................................................................................................................... 42Deleting an SSL property list................................................................................................................................. 47Copying an SSL property list................................................................................................................................. 47Renaming an SSL property list.............................................................................................................................. 48Using the Trace feature..........................................................................................................................................48

6

Chapter 1: IntroductionU2 provides seven common APIs for writing client application programs that connect to UniVerse andUniVerse databases.

We call them common APIs because programs written in them can access data in both databases.

The seven Client APIs are:

▪ UCI, on page 6

▪ UniOLEDB, on page 6

▪ InterCall, on page 6

▪ UniObjects, on page 6

▪ UniObjects for Java, on page 7

▪ UniObjects for .NET, on page 7

▪ JDBC Driver for UniVerse and UniData, on page 7

UCIUCI is a C-language API. It lets developers write UNIX and Windows client programs that use SQLstatements to access and manipulate data in UniVerse and UniVerse databases. UCI is modelled onthe ODBC standard as defined in the Microsoft ODBC 2.0 specification.

It models only the API side of the ODBC standard, not the driver/transport side. Unlike the standardODBC interface, UCI is more closely integrated with the extended relational database model used byUniVerse and UniVerse, with their nested tables, transaction processing support, and so forth.

UniOLEDBUniOLEDB is U2’s OLE DB provider for UniVerse and UniVerse.

It uses Microsoft’s Universal Data Access (UDA) technology to provide applications in an enterprisenetwork with direct access to UniVerse and UniVerse databases.

InterCallInterCall is an open API that lets client application programs developed on UNIX or Windows systemsaccess data on UniVerse or UniVerse servers.

On UNIX systems, developers can write client programs using any tool that accesses static libraries,typically a C compiler. On Windows platforms, developers can write client programs using any toolthat accesses DLLs, for example, Visual Basic, C, or Visual C/C++.

Note: InterCall replaces and supersedes ICI (Integrated Calling Interface).

UniObjectsUniObjects is an API to UniVerse or UniVerse from Visual Basic, or from any other programdevelopment environment that uses the Microsoft ActiveX interface.

UniObjects for Java

7

It is fully integrated with the Microsoft environment.

UniObjects for JavaUniObjects for Java is an API that lets developers create Java-based applications that access UniVerseand UniVerse databases.

UniObjects for Java, based on the UniObjects model, is a 100% Pure Java Class Library whose objectscan take full advantage of any Java-based IDE (Integrated Development Environment).

UniObjects for .NETUniObjects for .NET is an API that lets developers create .NET-based applications that access UniVerseand UniVerse databases.

UniObjects for .NET is fully integrated with the Microsoft environment.

JDBC Driver for UniVerse and UniDataThe JDBC driver for UniVerse and UniData is an interface to UniVerse and UniData databases fromJDBC applications.

This book is for experienced programmers and application developers who are familiar with UniVerseand UniData, Java, JDBC, and who want to write JDBC applications that access these databases.

Note: The JDBC Driver for UniVerse and UniData does not require any configuration for UCI andwill not need an entry within the UCI configuration file.

8

Chapter 2: Maintaining the UniRPCThe UniRPC lets local UniVerse and UniVerse systems communicate with remote systems. Thecommunicating systems must use TCP/IP networking software to make connections.

In this chapter the terms local and remote refer to client and server programs or systems. However,because client programs can connect to server programs running on the same computer, remote doesnot necessarily imply that the server is on another physical computer system.

This chapter describes:

▪ The UniRPC daemon (on UNIX servers)

▪ The UniRPC service (on Windows servers)

▪ The contents of the unirpcservices file

The UniRPC on UniVerse servers requires little maintenance, other than starting and stopping theUniRPC daemon or service. On UniVerse servers, you can also do the following:

▪ Change the port number

▪ Add entries to a UNIX hosts file

System requirementsBefore installing layered or third-party products that use the UniRPC, such as the UniDK, UniOLEDB,the JDBC Driver for UniVerse and UniVerse, or UniAdmin, you must install and configure TCP/IP usingthe instructions supplied by the TCP/IP facility vendor.

On UniVerse systems, you should then identify the systems to be networked with the database bydefining them in the /etc/hosts file. See Maintaining the hosts file (UniVerse Only), on page 10 formore information.

How the UniRPC worksThe UniRPC daemon unirpcd (or the UniRPC service unirpc) waits for a request from a client system toconnect to a server process.

When it receives a connection request, it checks the unirpcservices files to verify that the clientsystem is allowed to request a particular service. If it can, the UniRPC starts the requested service,then returns to the listening state. Each client process connects to its own server process. Each serverprocess uses the same amount of system resources as a local database user.

Maintaining the UniRPCThis section describes the following:

▪ How to change the UniRPC port number (UniVerse only)

▪ How to maintain a UNIX server’s hosts file (UniVerse only)

▪ How to start and stop the UniRPC daemon (unirpcd)

UniRPC maintenance on UniVerse systems

9

UniRPC maintenance on UniVerse systems

Use UniAdmin to:

▪ Define the UniRPC port number

▪ Maintain the hosts file on a UNIX server

Choose Network Services from the UniAdmin menu. The Network Services window appears, asshown in the following example:

This window has the following components:

▪ Port # field. The current port number for the UniRPC daemon.

▪ Hosts list. Displays the machine name and IP address for each node in the /etc/hosts file.

Note: If you are using the Network Information Services (NIS, also known as Yellow Pages), youdo not need to use the /etc/hosts file to define, change, and delete network nodes. See the UNIXnetworking documentation provided with your system for more information.

Defining the UniRPC port number (UniVerse Only)

Before you can use the UniRPC, you must specify the number of the port that the UniRPC is to use. Youspecify the port number on the client and the server systems. If you specify a port number other thanthe default, it must be the same on all systems that communicate via the UniRPC.

The current UniRPC daemon port number is displayed in the Port # field in the Network Serviceswindow. To change the number, do the following:

1. Click Change.The Change Port Number dialog box appears.

2. Enter a new number in the Enter new Port number field.3. Click OK.

The new port number is saved and the Network Services window is updated with the new setting.

Chapter 2: Maintaining the UniRPC

10

To use the new port number, you must restart the UniRPC daemon (see Starting the UniRPC daemonon UNIX systems, on page 12)

Maintaining the hosts file (UniVerse Only)

Use the Network Services option of UniAdmin to add, modify, and remove nodes in the hosts file.These tasks are performed from the Network Services window.

Adding a nodeTo add a new node to the hosts file:

1. Click Add on the Network Services window.The Add Node dialog box appears.

2. Enter the node name in the Machine Name field.3. Enter the node address in the IP Address field.4. Click OK.

The new node’s machine name and IP address are checked against existing entries in thehosts file. If the new node matches an existing entry, a message box appears. You mustacknowledge the message before you can enter alternative values. If the new node details areunique, the new node definition is added to the hosts file and the Network Services window isupdated.

Modifying a nodeTo modify the name or IP address of an existing entry in the hosts file:

1. Choose the node to modify by doing one of the following:

▪ Double-click the node in the Hosts list.

▪ Choose the node and click Modify.

The Modify Node dialog box appears.

2. Edit the entries in the Machine Name and IP Address fields.3. Click OK.

The node’s machine name and IP address are checked against existing entries in the hosts file.If the node details match an existing entry, a message box appears. You must acknowledgethe message before you can enter alternative values. If the node details are unique, the nodedefinition is added to the hosts file and the Network Services window is updated.

Removing a nodeTo remove a node definition from the hosts file:

1. Select the node from the Hosts list.2. Click Remove.

A message box appears.3. Click Yes. The node definition is removed from the hosts file and the Network Services window

is updated.

Starting the UniRPC on Windows platforms

On UniVerse systems you cannot use UniAdmin to start the UniRPC daemon because it uses theUniRPC daemon to connect to the UniVerse server. On Windows platforms, you can start the UniRPCdaemon or service in one of three ways:

From the Control Panel

11

▪ From the Windows Control Panel

▪ From the UniVerse Control Panel

▪ At the MS-DOS prompt

From the Control Panel1. Double-click the Services icon.2. Scroll down the list of services until you find three entries for UniVerse: UniVerse Resource

Service, UniRPC Service, and UniVerse Telnet Service.3. Choose UniRPC Service, then choose Start.4. Click Startup, then click Automatic.

This ensures that UniVerse starts automatically when the server is rebooted.

From the UniVerse Control Panel1. Choose Start > Programs > Rocket U2 > UniVerse Control.2. Click the Start All Services button to start all UniVerse services.

At the MS-DOS promptEnter the following command:D:\users>net start unirpc

The system reports the name of the service it is starting and whether the startup is successful.

Note: The UniVerse services are started automatically when the operating system is loaded unlessyou clear the automatic startup boxes during UniVerse installation.

Stopping the UniRPC on Windows platforms

You can shut down the UniRPC daemon or service in one of three ways:

▪ From the Windows Control Panel

▪ From the UniVerse Control Panel

▪ At the MS-DOS prompt

Note: If users are connected to the services when they are shut down, the users do not lose theirconnections; the connections remain active until the users terminate them. However, it is notpossible for new users to connect to UniVerse. If you want to do a complete shutdown of UniVerseto restart the services, be sure that all connections are terminated first.

From the Control Panel1. Double-click the Services icon.2. Scroll down the list of services until you find three entries for UniVerse:

▪ UniVerse Resource Service

▪ UniRPC Service

▪ UniVerse Telnet Service3. Choose UniRPC Service, then choose Stop.4. Click OK.

The UniRPC daemon or service is shut down.


12

From the UniVerse Control Panel1. Choose Start > Programs > Rocket U2 > UniVerse Control.2. Click Stop All Services to stop all UniVerse services. Wait for all services to stop.3. Click OK to exit the UniVerse Control Panel.

All four services are shut down.

At the MS-DOS promptYou can shut down the UniRPC daemon or service in one of three ways:

1. Enter the following command at the MS-DOS prompt:D:\users>net stop unirpc

A message appears prompting you to confirm that you want to stop the UniRPC.2. Enter Y to stop the UniRPC daemon or service.

Starting the UniRPC daemon on UNIX systems

Use the UniVerse System Administration menus on the UniVerse server to start the UniRPC daemon.See Administering UniVerse for more information.

1. Choose Rpc administration from the Package menu, then choose Start the rpc daemon.2. At the prompt, do one of the following to handle any error messages.

▪ Enter the name of the file to send all error and system messages to.

▪ Enter a space to display messages on your screen.

▪ Press Enter if you do not want to display or save message.

Once you start the UniRPC daemon, it automatically restarts whenever you boot UniVerse.

3. At the next prompt, click Yes to start the UniRPC daemon or No to return to the Rpcadministration menu.

Note: The file that receives all error and system messages can grow unchecked unless youmonitor it periodically.

Stopping the UniRPC daemon on UNIX systems

Use the UniVerse System Administration menus on the UniVerse server to stop the UniRPC daemon.See Administering UniVerse for more information.

1. Choose Rpc administration from the Package menu, then choose Halt the rpc daemon.2. At the next prompt, click Yes to stop the UniRPC daemon or No to return to the Rpc

administration menu.

Note: Stopping the UniRPC daemon does not interrupt active UniRPC processes.

UniRPC maintenance on UniVerse servers

On UniVerse servers, UniRPC maintenance is minimal. You cannot change the port number of theUniRPC, and there is no need to maintain a hosts file.

About the unirpcservices file

13

Use the stopud command to stop the UniRPC daemon or service. Use the startud command tostart the UniRPC.

About the unirpcservices fileEach process that uses the UniRPC automatically configures the unirpcservices file when it first starts.If no unirpcservices file exists, it is created in the unishared directory.

▪ On UNIX systems the default location of this file is /usr/unishared/unirpc.

▪ On Windows platforms the default location is <drive>:\u2\unishared\unirpc.

To determine the location of the unirpcservices file on your system, do the following:

▪ On UNIX systems, execute the command:$ cat /.unishared

▪ On Windows platforms, find the registry entry under the subkey \HKEY_LOCAL_MACHINE\SOFTWARE\Rocket Software\unishared.

When a client system requests a connection to a service on a server system, the UniRPC daemon(unirpcd) on the server uses the unirpcservices file to verify that the client system can start therequested service.

The UniRPC software uses field 3 of the unirpcservices file to verify that a machine making arequest for a service is allowed to do so.

The following table lists the fields in the unirpcservices file:

Field Contents

1 The name of the UniRPC service (for example, uvserver).2 The full path of the service engine executed by the UniRPC daemon.3 The names of nodes allowed to execute this service. This field is multivalued, with

values separated by commas (no spaces). If the field contains * (asterisk), all hostsdefined in /etc/hosts can execute this service.

4 The network transport mechanism for the service (TCP/IP).5 Reserved for future use.6 The value (in seconds) specifying how long an open connection can be idle before

automatic closure from the remote connection. The default is 3600, or 60 minutes.

UniVerse systems

On UniVerse systems,the unirpcservices file might contain entries such as the following:

uvnet /usr/uv/bin/uvnetd host1,host2,host3 TCP/IP 3 3600uvdrsrv /usr/uv/bin/uvdrsrvd * TCP/IP 0 3600uvcs /usr/uv/bin/uvapi_server * TCP/IP 0 3600uvfilefix /usr/uv/bin/uvfilefix_server * TCP/IP 0 3600uvserver /usr/uv/bin/uvsrvd * TCP/IP 0 3600

The version of uv.rc shipped with UniVerse systems (/usr/uv/sample/uv.rc) contains commandsthat:

▪ Check for the existence of the unirpcservices file


14

▪ Verify that services are defined in it

▪ Start the UniRPC daemon if the file contains services

The UniRPC daemon is executed as part of the UniVerse reboot procedure.

UniData systems

On UniData systems the unirpcservices file might contain:

udcs /usr/ud72/bin/udapi_server * TCP/IP 0 3600udserver /usr/ud72/bin/udsrvd * TCP/IP 0 36004

15

Chapter 3: The UCI Configuration EditorWhen an application requests a connection to a data source, UCI uses the information in the UCIconfiguration file (uci.config or another UCI configuration file you create) to connect to the datasource.

The UCI Configuration Editor lets you:

▪ Add, modify, or delete data sources.

▪ Create your own UCI configuration file.

▪ Set up your system registry to access a particular UCI configuration file.

▪ Open a UCI configuration file different from the one that currently appears in the UCI ConfigurationEditor window.

▪ Create secure configuration files.

This tool can generate the system registry key and create a default uci.config file in the c:\U2\UniDK\config directory, if either are missing. For more details about this, refer to Creatingthe UciCfgFile key in the registry, on page 16.

Note: You must be in Administrator mode to update the registry on computers that have useraccess controls (UAC) enabled.

UCI configuration fileApplications access data sources through entries in the UCI configuration file. This file containsconnection parameters needed to route connection requests to the appropriate UniData or UniVerseserver.

When an application tries to connect to a data source, the UCI configuration file on the client machineis read to determine the name of the host system, the DBMS type, and other information.

The UCI configuration file that UCI uses is specified in the UciCfgFile key in the system registry underHKEY_LOCAL_MACHINE \SOFTWARE\Rocket Software\UniClient\UCIorHKEY_LOCAL_MACHINE\Software\Wow6432Node\Rocket Software\UniClient\UCI.

Each entry in the UCI configuration file describes the physical attributes of a connection in sufficientdetail to perform three tasks:

▪ Establish communications

▪ Start a UniData or UniVerse server process

▪ Route query and update requests

In the UCI configuration file on the client machine, you must define the UCI data sources to whichyou want applications to connect. Use the UCI Configuration Editor to define and modify data sourcedefinitions.

For more information about the UCI configuration file, see UCI Developer’s Guide.

System requirements▪ .NET Framework 4.0 Client Profile

Chapter 3: The UCI Configuration Editor

16

This UCI Editor tool is installed as part of the UniDK, 32-bit U2ODBC, 64-bit U2ODBC, and VSG clientinstallations.

It is installed in one of the following directories:

▪ C:\U2\UniDK\U2ODBC_32bit\UCI_Editor

▪ C:\U2\UniDK\U2ODBC_64bit\UCI_Editor

▪ C:\U2\UniDK\bin\UCI_Editor

Starting the UCI Configuration EditorTo start the UCI Configuration Editor on a Windows computer, from the Start menu choose Programs> Rocket U2 > UniDK > UCI Editor.

The UCI Editor window opens

The data source information in this example represents the default settings in the uci.config file,as shipped with the client product.

Note: If the uci.config file is password protected, you will be prompted for a password beforethe editor will open. If you do not know the password, you can click the Help button forinstructions on how to resolve the issue.

Creating the UciCfgFile key in the registryThe UCI configuration file that the client uses is specified in the UciCfgFile key in the system registryunder HKEY_LOCAL_MACHINE\SOFTWARE\RocketSoftware\UCI. Initially this is set touci.config, the UCI configuration file U2 ships to you.

Adding a data source

17

You must create a new UciCfgFile key if it is not already included in the registry. You may also needto create a new UciCfgFile key if the registry becomes corrupt, making the key inaccessible to yoursystem.

If the registry key does not exist, the UCI Editor will open with the UCI RegKey button visible. Click UCIRegKey to create the UciCfgFile key in the registry and to set the path to the default uci.config file. Youmust restart the UCI Configuration Editor for the changes to take effect.

Note: If the UciCfgFile exists in the registry, the UCI RegKey button will not be visible.

Adding a data source1. Click New Data Source. The New Data Source dialog box opens, as shown in the following

example.

2. Enter a data source name.3. Under DBMSTYPE, click the type of database to which you want to connect.4. Enter the host name or the network IP address of the server to which you want to connect.


18

5. Click OK to save your definition and exit the New Data Source dialog box or click Cancel to exitthe dialog box without saving your definition.The data source information now shows in the UCI Configuration Editor.

The parameters that appear automatically on the Data Source Editing section are required foreach data source you add. Their values are set according to the information you provide on theNew Data Source dialog box.

Adding a parameterAfter a data source is defined, it may become necessary to add additional parameters.

Procedure

1. Click Add Parameter. The Parameter dialog box displays.2. Click the parameter you want to add from the Parameter list. For a list of parameters, see Data

source parameters, on page 19.3. In the Value field, enter an appropriate value for the parameter. Information about the parameter

appears under Parameter Description.4. Click Set to add the parameter.5. After you finish adding parameters, click Cancel. The Data Source Adding dialog box displays all

parameters associated with the data source.

Note: To edit parameters, see “Modifying a data source” on page 3-16.

6. After you finish adding parameters for the data source, click Save Data Source.

Data source parameters

19

7. When you finish adding data sources, click Save Configuration File to save your changes.

Data source parametersEach data source definition in the UCI configuration must include the following parameters:

▪ DBMSTYPE

▪ NETWORK

▪ SERVICE

▪ HOST

Two parameters you might want to change are MAXFETCHBUFF and MAXFETCHCOLS. Use theseparameters to increase the amount of data in each buffer sent from the server to the client. This willimprove performance by reducing the number of data transfers between server and client. For moreinformation about these two parameters, see the UCI Developer’s Guide.

If the UniVerse server you are connecting to has NLS enabled, you also can add or change the NLSparameters. For information about setting the NLS parameters, see the UCI Developer’s Guide.

Warning: Adding or changing other parameters can make UCI unusable. Entries in the uci.configfile are order dependent. Changing the order will cause an error.

The following table describes the parameters that are required for each data source entry:

Parameter Description Default

DBMSTYPE Specifies the type of database you want to access(UNIDATA, UNIVERSE, or any other database type,such as DB2).

None

NETWORK Specifies the network used to access the data source(TCP/IP or LAN).

None

SERVICE Specifies the name of the server process for theDBMSTYPE you specified. For UniData, specifyudserver; for UniVerse, specify uvserver.

None

HOST Specifies the name of the server machine or itsnetwork IP address.

None

The following table describes other parameters in the Parameters list that you may want to add orchange:


20


ACCOUNT Specifies one of the following:

▪ The full path of a UniData or UniVerse accountdirectory

▪ A valid UniVerse schema name

▪ A valid UniData database name

A UniData database name is valid if it appears as anentry in the ud_database file. For UNIX systems,this file is typically located in the /usr/udxx/include path, where xx is the UniData version, suchas /usr/ud73/include. For Windows systems,it is located in the equivalent Windows path, forexample C:\U2\ud73\INCLUDE.

None

AUTOINC Produces an SQLColAttributes report if the column isan auto-increment column.

No

CASE Produces an SQLColAttributes report if the column iscase-sensitive.

Yes

DESCB4EXEC (For internal use only) Indicates if the database’sdescribe operation is legal before executing the SQLstatement.

Yes

DSPSIZE Produces an SQLColAttributes report showing thecolumn display size.

Yes

IPVERSION Specifies the IP version through which the clientwill communicate with the server. Can be one of thefollowing:

▪ IPV4

▪ IPV6

▪ IPV4_IPV6

▪ IPV6_IPV4

▪ IPVANY

IPV4

MAPERROR Maps UniVerse error codes to standard ODBCSQLSTATE error codes. Whenever the server returnsone of the mapped codes as an error condition,UCI sets the SQLSTATE variable equal to the five-character code defined in the ODBC standard.

List

MARKERNAME Indicates if the database uses names for parametermarkers. If not, the ? (question mark) is the markercharacter.

No

MAXFETCHBUFF Controls the maximum buffer size on the server tohold data rows. The server usually fills this bufferwith as many rows as possible before sending datato the client. If any single row exceeds the lengthof MAXFETCHBUFF, SQLFetch fails, and you shouldincrease the value of this parameter.

8192 bytes

Data source parameters

21


MAXFETCHCOLS Controls the maximum number of column values theserver can put in the buffer before sending data tothe client. If the number of columns in the result setexceeds the number specified by MAXFETCHCOLS,SQLFetch fails, and you should increase the value ofthis parameter.

400 column values

NLSLCALL Specifies all components of a locale. NoneNLSLCCOLLATE Specifies the name of a locale whose sort order to

use.None

NLSLCCTYPE Specifies the name of a locale whose character typeto use.

None

NLSLCMONETARY Specifies the name of a locale whose monetaryconvention to use.

None

NLSLCNUMERIC Specifies the name of a locale whose numericconvention to use.

None

NLSLCTIME Specifies the name of a locale whose time conventionto use.

None

NLSLOCALE Specifies all components of a locale. NoneNLSMAP Specifies the name of the server’s NLS map for the

connection. For a client to connect to the serversuccessfully, the server must be able to locate thespecified map, which must also be installed in theserver’s shared memory segment.

None

NULLABLE Produces an SQLDescribeCol andSQLColAttributes report if the column is nullable.

Yes

SEARCH Produces an SQLColAttributes report if the column issearchable.

Yes

SECUREMODE Turns on/off a U2 ODBC-enabled SSL connection. NoneSSLPROPERTYLIST Specifies the SSLPROPERTY list name defined in the

SSL Configuration Editor.None

SSLPROPERTY-PASSWORD

Specifies the password defined for the SSLPROPERTYlist.

None

TXBEHAVIOR Defines default autocommit/ manual-committransaction behavior. Normally, UniVerse isautocommit by default.

1

TXCOMMIT (For internal use only) Database SQL statement forcommitting a transaction.

No

TXROLL (For internal use only) Database SQL statement forrolling back a transaction.

No

TXSTART (For internal use only) Database SQL statement forstarting a transaction.

No

TYPENAME Produces an SQLColAttributes report showing thename of the SQL TYPE for the column.

Yes

UNSIGNED Produces an SQLColAttributes report if the column isUNSIGNED.

No

UPDATE Produces an SQLColAttributes report if the column isupdatable.

Yes

USERNAME Specifies the user’s login name on the server. None


22


WALLETID Specifies the Wallet ID for Automatic DataEncryption.

None

WALLETPASS Specifies the Wallet password for Automatic DataEncryption.

None

Modifying a data source1. From the UCI Configuration Editor, click the data source you want to modify. The data source

information populates in the Data Source Editing area.You can add new parameters or edit existing ones. To add new parameters, see Adding a datasource, on page 17. To edit parameters, continue with the following steps.

2. Click the parameter you want to modify. The parameter name and current value appear underParameter Editor, as shown in the following example.

3. To remove the parameter, click Remove Parameter.4. To modify the parameter value, enter a new value in the Value field, then click Update

Parameter.5. After you finish modifying parameters for the data source, click Save Data Source.6. When you finish modifying data source information, click Save Configuration File to save your

changes.

Deleting a data source

23

Deleting a data source1. From the UCI Configuration Editor, select the data source you want to delete.2. Click the Delete Data Source button.3. When you finish deleting data sources, click Save Configuration File to save your changes.

Creating a UCI configuration fileComplete the following steps to create your own UCI configuration file.

1. From the UCI Configuration Editor, open the UCI configuration file you want to use as a base forthe new UCI configuration file. To open a file, see Opening an alternative UCI configuration file, onpage 23.

2. Choose File > Save As.3. From the Save As dialog box, navigate to the folder to which you want to save the new UCI

configuration file, specify a file name with the extension .config, then click Save.4. If there was a password set on the original configuration file, a dialog box opens and asks you to

define a password for the new configuration file. You are not required to create a password.5. Modify the new UCI configuration file with the appropriate data source information.

Opening an alternative UCI configuration file1. To open the UCI configuration file that is set in the UciCfgFile registry key, choose File > Set new

configuration file.2. To open a UCI configuration file that is different from the one set in the UciCfgFile registry key,

a. From the UCI Configuration Editor, choose File -> Open disk file.b. From the Open File dialog box, choose the appropriate UCI configuration file (the file should

have the extension .config), then click Open.

Reverting to the default uci.config file

If you have previously elected to use an alternative UCI configuration file, you can elect to use thedefault uci.config file at any time.

Click File > Use default uci.config.

Securing configuration filesThe UCI configuration files can be password-protected for an additional layer of security. When aconfiguration file is password protected, the information in the configuration file is encrypted and canthereafter only be accessed using the UCI Configuration Editor.

1. Open the UCI Configuration Editor if it is not already open.2. Make sure that the configuration file that you want to secure is the one open in the UCI

Configuration Editor. To select a new configuration file, click File > Open disk file, select theconfiguration file that you want to secure, and then click OK to return to the editor.

3. Click the Secure UCI configuration file check box.4. Click Save Config File. Click Yes when asked if you want to update the configuration file.


24

This opens a new password dialog box.5. Enter the new password information, and then click OK.

Note: When the secure password is not provided correctly, the secure uci.config file will notbe opened. You can delete the secure uci.config file and the tool will create a new defaultuci.config file.

Modifying a configuration file and making commentsAfter selecting the correct UCI configuration file, you can open the configuration file to manually makeany changes.

In the UCI Configuration Editor, click Text Editor to easily access the configuration file.

New data source parameters and comments

You can define additional parameters or comments to include in the UCI configuration file.

To do either of these, click New Items in the Parameter list, then under Parameter Editor, enter oneof the following in the Parameter field:

▪ A new parameter name

New data source parameters

New parameters must begin with a C– prefix. For example, you might name a new parameter C–CATEGORY. UCI ignores any parameter beginning with the C– prefix, but UCI applications can get theparameter information using the SQLDataSources function.

Comments

To include a comment in a data source definition, open the configuration file and then enter anasterisk (*) before any comments. The comments must appear at the top of the configuration file,before the parameters in the data source definition.

25

Chapter 4: Accessing UniVerse AccountsUniVerse databases are organized into accounts. A consumer connects to a UniVerse account andcan access the files there. You optionally can define the account as a database in the ud_databasefile on the server. You can also include the account path or database name in the UCI data sourcedefinition in the UCI configuration file.

For information about setting up the UCI Configuration file, see The UCI Configuration Editor, on page15.

You can also specify the account path or database name each time you try to connect to the account.In this case you need not include the account path or database name in the UCI configuration file.When you try to connect, you are prompted to specify either the full path to the account or thedatabase name.

If you want to access an account that has a UDTHOME directory different from the default UDTHOMEdirectory, you must include a definition for that account in the ud_database file on the server.On UNIX systems this file is located in the /usr/ud72/include path. On Windows platforms it islocated in \udthome\include. You can find the path for udthome by looking in the registry underHKEY_LOCAL_MACHINE\SOFTWARE\Rocket Software\UniVerse\7.3. Use any text editorto modify the ud_database file.

To determine your default UniVerse home directory, use the UNIX env command. Output from thiscommand includes the default setting for the UDTHOME environment variable.

The following Windows example shows an entry in the ud_database file for a database named db2:

DATABASE=db2UDTHOME=d:\disk2\test72UDTACCT=d:\disk2\test72\testacct

In the ud_database file entry the UDTHOME parameter is optional. You should include it only whenthe UDTHOME directory is different from the default UDTHOME directory.

Running concurrent UniVerse versionsWhen you install UniVerse 7.2 on a machine where 5.1 or 5.2 was previously installed, theunirpcservices file is overwritten with UniVerse 7.2 information. If you want to run UniVerse 5.1, 5.2,6.0, 6.1 or 7.1 concurrently with 7.2, you must edit certain files to enter the UniVerse 5.1, 5.2, 6.0, or 6.1definitions.

Running UCI, UniVerse ODBC, or UniOLEDB concurrently

If you are running UCI, UniVerse ODBC, or UniOLEDB with concurrent versions of UniVerse, you mustedit the unirpcservices file and the uci.config file to define locations of executables from the previousversion of UniVerse.

The following example illustrates unirpcservices file entries when running UniVerse 7.2 concurrentlywith UniVerse 7.3:

udserver_72 d:\u2\ud72\bin\udsrvd.exe * TCP/IP 0 3600udserver_73 c:\u2\ud73\bin\udsrvd.exe * TCP/IP 0 3600

Chapter 4: Accessing UniVerse Accounts

26

Make sure the uci.config file contains an entry for the server for each version of UniVerse, as shown inthe following example:

<UniVerse72>DBMSTYPE = UniVersenetwork = TCP/IPservice = udserver_72host = server1

<UniVerse73>DBMSTYPE = UniVersenetwork = TCP/IPservice = udserver_73host = server2

Running InterCall, UniObjects, or UniObjects for Java concurrently

If you are running InterCall, UniObjects, or UniObjects for Java with concurrent versions of UniVerse,you must edit the unirpcservices file to define the location of the udapi_server executable for theprevious version you are running.

The following example illustrates unirpcservices file entries when running UniVerse 7.2 concurrentlywith UniVerse 7.3:

udcs_72 C:\u2\ud72\bin\udapi_server.exe * TCP/IP 0 3600udcs_73 C:\u2\ud73\bin\udapi_server.exe * TCP/IP 0 3600

You can now set your service name to either service defined in the unirpcservices file, for example,udcs_72 for UniVerse 7.2 or udcs for UniVerse 7.3.

Tracing eventsYou can use the tracing feature to create logs of events between clients and the database through theserver. Logs enable support personnel to help troubleshoot problems. You can define trace levels fordatabase entries in the ud_database file. The following table describes the valid trace levels and theassociated information that is written to the trace log:

Trace level Description

0 Includes all fatal error information.1 Includes all UCI functions in addition to the information provided by trace level 0.2 Includes parameter information and column descriptions in addition to the

information provided by trace levels 0 and 1.3 Includes data values in addition to the information provided by trace levels 0, 1, and 2.

The following UNIX example shows a tracing level setting for a database named dbase3:

DATABASE=dbase3UDTHOME=/disk1/ud72UDTACCT=/home/test/udtestTRACE_LEVEL=3

27

Chapter 5: Device licensingThis chapter describes how device licensing works.

For more information about device licensing, see Installing and Licensing UniVerse Products andAdministering UniVerse.

Licensing modesUniVerse and UniData provide two licensing modes:

▪ Session licensing

▪ Device licensing

Session licensing

Session licensing is like the licensing system used before Release 9.5 of UniVerse and Release 5.1 ofUniVerse. Every connection from telnet or an API, even from the same PC, consumes one databaselicense.

On UniVerse systems, session licensing has been enhanced to include a new licensing tool, uvlictool,that reports on the current licensing state and cleans up current licensing.

Device licensing

Device licensing, sometimes called client-side licensing, tries to combine all remote connections froma single device to a database server at both the database license level and the package level.

Device licensing works with the following connection types (among others):

▪ UCI

▪ UniObjects

▪ UniObjects for Java

▪ UniObjects for .NET

▪ InterCall

▪ UniOLEDB

Why do I need device licensing?Users accessing a database server through one or more client application programs may want toput their licensing scheme on a one-license-per-device basis. Such applications often open multipleconnections to a database server. For example, an application might use one connection to browse,another connection to check data, yet another connection to update the database, and so forth.

Before UniVerse Release 9.5 and UniVerse Release 5.1, each connection to the server consumed itsown separate license, even though only one user was using all those connections from one PC. Device

Chapter 5: Device licensing

28

licensing lets such users consume one database license and the number of connections for which theyare licensed, up to ten, to the server from a single PC.

Device licensing requirements

Device licensing has the following requirements:

▪ Clients must run on a Windows platform.

▪ Clients must run on a LAN or TCP/IP with an Ethernet card.

Connection typesThere are three ways to connect to a database server:

▪ Direct connection. This is not a client/server connection.

▪ Two-tier client/server connection.

▪ Multiple-tier client/server connection.

Each PC can have up to ten connections to the server, but not all connections from a PC can becombined.

Direct connections

Direct connections are not really client/server connections because there is no real client. Examples ofdirect connections are:

▪ Directly invoking the database on a system

▪ TTY serial line

Two-tier connections

Two-tier connections are typical client/server connections where a client application connects toa database server either on the same machine or on a different machine. Telnet connections to thedatabase are an example of a two-tier connection.

Client applications running on PCs different from the database server appear to the server with uniqueidentifiers.

Multiple-tier connections

Multiple-tier connections are client applications that connect from a PC to a database server eitherthrough one or more different PCs, or through an application server component.

Examples of multiple-tier connections are:

Using device subkeys

29

▪ An HTTP server running scripts that use UniObjects or UniObjects for Java.

▪ An application that connects first to an application server either on a different PC or on the serversystem. The application server connects to the database server.

Using device subkeys

Each PC that connects immediately to the database server can have up to ten connections.

Using multiple-tier connections, each PC that connects to an intermediate application componentconsumes a separate license. But each of these PCs, at one or more removes from the server, can haveup to ten connections.

In order for a PC to have multiple connections to the database server and still consume only onelicense, users must ensure that each PC connecting to the server through another system specify aunique device subkey before requesting a connection to the server. This subkey is a string of up to 24characters. All client applications on a given device that connect to one database server must use thesame unique subkey.

30

Chapter 6: The U2 SSL Configuration EditorAt UniVerse 11.1 and UniData 7.3, U2 supports the ability of client applications to make secureconnections to the database server through Secure Sockets Layer (SSL). SSL is a transport layerprotocol that provides a secure channel between two communicating programs over whichapplication data can be transmitted securely. It is the most widely implemented security protocol onthe World Wide Web.

Applications can use U2 ODBC or UniOLEDB to access U2 data sources through entries in the UCIconfiguration file (uci.config) on the client machine.

When ODBC or UniOLEDB attempts to connect to a data source, U2 ODBC or UniOLEDB reads theUCI configuration file to determine the connection parameters. Three parameters indicate whetherthe client application requires a secure connection to the database server. One of these parametersis SSLPROPERTYLIST, which specifies the name of the SSL property list to be used to verify theproperties of the secure connection.

This chapter focuses on the SSL Configuration Editor, a graphical user interface (GUI) tool used tocreate or change an SSL property list. It first provides a high-level overview of SSL property lists anddetails the SSL properties.

It then shows you how to start the SSL Configuration Editor and use it to perform file creation andmaintenance tasks:

▪ Create a new SSL property list

▪ Edit an existing SSL property list

▪ Save to a new SSL property list

▪ Delete an SSL property list

▪ Copy an SSL property list

▪ Rename an SSL property list

If you need more information about the UCI configuration file, please see the UCI Developer’s Guide.

About SSL property listsAn SSL property list is an ASCII text file that stores the properties for a secure connection. Theseproperties define the characteristics and behaviors of the secure connection.

List encryptionAn SSL property list may contain sensitive information such as the password to a private key or thelocation of a certificate authority (CA) certificate.

For this reason, it is saved in encrypted form to the Windows Registry at:

HKEY_LOCAL_MACHINE\SOFTWARE\RocketSoftware\UniDK\SPL orHKEY_LOCAL_MACHINE\Software\Wow6432\RocketSoftware\UniDK\SPL

The SSL Configuration Editor uses an algorithm developed by U2 to encrypt the list.

If you do not assign your own password to the list, the algorithm uses a an internal default passwordto generate the encryption key for the list. Because the internal default password is fixed, thealgorithm always produces the same encryption key from this password. Consequently, anyone whouses the SSL Configuration Editor can access and read the contents of your SSL property list.

Working with SSL property lists

31

For increased security, we strongly recommend that you assign your own password to the SSLproperty list. In this case, the same algorithm uses your unique password as the seed for generatingan encryption key. The resulting encryption key is unique, so only users who know the password canaccess the list and read its contents.

Working with SSL property listsAlthough the property list is an ASCII text file, you should never edit it directly. Use the SSLConfiguration Editor to create, modify, or delete the property list; this ensures that the list is properlysaved to (or deleted from) the Registry.

Loading and decrypting an SSL property listBefore the SSL handshake takes place, the SSL property list must be loaded into memory anddecrypted. After the list has been decrypted, it is supplied in plain text form to a function that handlesthe SSL handshake.

Alternatively, the program can assemble the property list on demand in memory, eliminating the needto create a property list in advance.

When the property list is in decrypted form (only internally in U2), each property is stored on aseparate line in the file, as shown below:

propertyName=propertyValue

SSL propertiesThis section describes each property supported in the SSL property list to define the characteristicsand behaviors of a secure connection.

SSLVersion={SSLv3 | TLSv1 | TLSv1.1 | TLSv1.2}

Optional. Default is TLSv1.1. This property specifies the preferred protocol version.

Version Description

SSLv3 Not recommended.TLSv1 Not recommended.TLSv1.1 This is the default security protocol.TLSv1.2

CertificateStoreType={U2 | Windows}

Optional. Default is U2. This property specifies the type of certificate stores to be used for allcertificates issued for the secure connection.

Value Description

U2 All certificates specified in this file are PEM, DER, or PKCS #12-format OS-level files.

Chapter 6: The U2 SSL Configuration Editor

32

Value Description

Windows All certificates specified in this file are looked up from the native Windowscertificate store. Generally, a CA certificate is looked up from Windows CAand ROOT stores, while MyCertificate is looked up from MY stores.

In Microsoft’s terminology, these certificate stores are system stores: acollection of physical certificate stores that reside in the Windows Registry.U2 looks up these stores from both of the following Registry locations:

CERT_SYSTEM_STORE_CURRENT_USER

CERT_SYSTEM_STORE_LOCAL_MACHINE

CACertificate=<cert-path>[;<cert-path>...]

Each property value string can contain multiple CA certificate paths, with paths separated by asemicolon (;) as shown above. Specifying multiple CACertificate properties is allowed.

If the CA Certificate property is left empty, the SSL Property List (SPL) can still be created. Whena client using the created SPL starts an SSL connection, if the CertificateStoreType is Windows,the Windows’s root certificate will be used; Beginning at the JUL2014 client release, if theCertificateStoreType is U2, a U2-supplied default root certificate store will be used as the CAcertificate.

The default U2 Root Certificate Store (.u2rcs) is created in the C:\U2\UniDK folder. The U2 RootCertificate Store can only be maintained on U2 server and copied to the client machine. The U2 RootCertificate Store can be managed by the U2 rcsman utility tool, which is found in the U2 server binfolder. For more information about the rcsman utility or the U2 Root Certificate Store, refer to theUniVerse Security Features or UniData Security Features manuals.

U2 certificate store type

<cert-path> is the path of the certificate file that is used as a CA certificate. The format of thecertificate can be either PEM, DER, or PKCS #12. (However, see the CertificatePath property foradditional information on how U2 loads certificates when performing the SSL handshake.) With theU2 type, if a CA certificate chain is required, you have the choice of specifying multiple CACertificateproperties, or, for PEM-format certificates, concatenating the certificate files into one single file (usingOS-level editor or command line) and specifying the concatenated file once.

Windows certificate store type

Specify the same “friendly name” or “Common name” that is used for the certificate in the certificatestore. With the Windows type, specify only one certificate, which should be the most immediate CAcertificate (the one used directly to sign the certificate to which authentication is to be performed).

A certificate chain is automatically established and used in an SSL session. Note that the abovedescription is based on the assumption that a correct and complete trust relationship exists in theWindows certificate store for the certificate involved. If a complete chain cannot be formed, an error isreported. This also applies to other certificate-related properties described below.

MyCertificate=<cert-path>

Optional for client SSL property list; default is none. Required for server SSL property list.

MyPrivateKey=<key-path>

33

U2 certificate store type

Note that if you specify this property, you must also specify the MyPrivateKey and PrivateKeyPasswordproperties. The format of the certificate can be PEM, DER. or PCKCS #12.

Windows certificate store type

Specify the same “friendly name” or “Common name” that is used for the certificate in the certificatestore. Note that when you import a Windows store type certificate to the MY store, you must associatean exportable private key with it by selecting the Exportable private key check box.

See also ClientAuthentication (below).

MyPrivateKey=<key-path>

Applicable to U2 certificate store type only. Required if you entered a value in MyCertificate.

This property specifies the path for the file that contains the private key associated with MyCertificate.The format of the key file can be PEM, DER. or PCKCS #12.

When an SSL property list is created, the private key is loaded into memory and validated againstits corresponding certificate (My Certificate). If it passes validation, the key is stored with the SSLproperty list. This validation feature is designed to enhance the security and protection of the user’sprivate key.

After the SSL property list has been created, you do not need to keep the private key file on your harddisk. You can store the key file safely on offline media until the next time you want to edit the SSLproperty list.

See also ClientAuthentication=[TRUE | FALSE], on page 35.

PrivateKeyPassword=<pass-phrase>

Applicable to U2 certificate store type only.

Required if you specified a value for MyCertificate.

This property specifies the password for the private key file.

See also ClientAuthentication (below).

CRL=<cert-path>

Optional. Default is none. Specifying multiple CRL properties is allowed.

This property specifies the Certificate Revocation List (CRL) to be used for this secure connection.

The CRL is a special certificate published by certificate authority (CA); it contains the serial numbers ofcertificates revoked by CA. If an incoming server certificate is specified, it is checked against the CRL toverify that it has not been revoked before other verification is performed.

The format of the CRL can be PEM, DER, or PKCS #12.


34

AuthenticationDepth=<level>

Default is 5. This property determines the level at which to stop U2’s verification process inauthentication processing.

The default setting of 5 is a sufficient depth in most cases. If you set the depth for fewer levels ofauthentication than actually employed for the certificate, the certificate will not pass authentication.

CipherSuite=<cipher-suite-string>

Optional. Default is all ciphers supported by the OpenSSL open source library.

This property specifies a suite of ciphers to be used in a specific order in the SSL handshake.

For further details, see the description of addCipherSuite() in the UniBasic Extensions manual.

TrustedPeerName=<trusted-peer-name-string

Optional. Default is none. Specifying multiple TrustedPeerName properties is allowed.

<trusted-peer-name-string> is in the format of <peer-name>[;<peer-name>[;<peer-name>]...]

This property tells U2 that it needs to perform additional checking in authenticating the incomingcertificate. If you do not specify TrustedPeerName, the incoming certificate is considered validwhen the CA certificate has verified it. However, if you specify TrustedPeerName, a further checkis performed to verify that the incoming certificate’s SubjectAltName extension or CommonNamesubject field matches one of the specified TrustedPeerName.

TrustedPeerName can be either a fully specified name (such as [email protected]) or a wildcardname. Two wildcard characters are supported:

% Match any character strings

_ Match one character

For example, %@us.xyz.com matches both [email protected] and [email protected], [email protected] matches [email protected] only.

AuthenticationStrength=[STRICT | GENEROUS]

Optional. Default is STRICT.

STRICT authentication requires the following:

▪ The incoming server certificate is a well-formed X.509 certificate.

▪ A valid CA certificate exists and verifies the incoming server certificate.

▪ Peer name checking (if specified) is performed.

GENEROUS authentication requires only the following:

CertificatePath=[DEFAULT | RELATIVE | PATH=<path> | ENV=<env-var>]

35



Note: GENEROUS authentication is not highly secure. We recommend using it in test environmentsonly.

CertificatePath=[DEFAULT | RELATIVE | PATH=<path> | ENV=<env-var>]

Applicable to U2 certificate store type only. Optional. The default location is PATH:C:/U2/UniDK/certs.

When you specify a certificate by the CACertificate, MyCertificate, or CRL property, the value forthat property is registered internally. When loading the certificate into memory to establish an SSLconnection, U2 uses this registered path by default to retrieve the certificate.

The CertificatePath property allows you to specify different locations in which to search thecertificates. Note that this property applies to all certificates specified in the file.

Four options are available:

Table 1: CertificatePath Options

Option Description

DEFAULT Specifies the above-described behavior. This option is the default.RELATIVE U2 looks for the certificate in the current directory under which the client

process is running.PATH:<path> <path> is a user-specified path for loading certificates specified in this SSL

property list. It can be either an absolute path or a relative path. The defaultpath is C:\U2\UniDK\certs. With this path, the behavior is the same asthat of the DEFAULT option.

ENV:<env-var> <env-var> is an environment variable name. With this option, the clientprocess uses the value of the environment variable as the path to load thecertificates. Note that U2 looks up the environment variable for a clientprocess only once when the first SSL connection is made and its value iscached for later reference by that process.

ClientAuthentication=[TRUE | FALSE]

Optional. Default is FALSE.

This property should be specified for a server SSL property list only.

If the value is TRUE, the SSL server using this property list requires client authentication during the SSLhandshake. It asks the client to send its certificate.

If TRUE, U2 treats the SSL property list as a server property list. Consequently, you must also specifyMyCertificate, MyPrivateKey (for the U2 certificate store type only), PrivateKeyPassword, andCACertificate or the SSL property list will not be created.


36

RandomFileLocation=<directory-path>

Optional. Default is “.” (the current directory).

This property specifies the directory in which the client stores random data for the use of SSLoperations. The directory should be specified as an absolute path (for example, D:\mysys\work).The directory must currently exist and be writeable.

By default, random data is stored in the directory in which a client process runs. If you want to controlwhere the random data is stored (for example, to limit users’ access to the random data by storingit in a directory that has restricted permissions), you should use this property to specify the desireddirectory.

The random data file named U2SSL.rnd is created in the specified directory.

Starting the SSL Configuration EditorThe SSL Configuration Editor program files are placed in a subfolder under the Programs folder whenyou install U2. This section tells you how to navigate to the tool and start it. It also describes the layoutof the SSL Configuration Editor window.

Note: You must be in Administrator mode to update the registry key on computers that have useraccess controls (UAC) enabled.

▪ From the Start menu, choose All Programs > Rocket U2 > SSL Configuration Editor. The SSLConfiguration Editor window opens.

Components of this window are described in the following tables.

Creating an SSL property list

37

Menu Description

File Options for creating new SSL property lists, as well as deleting, saving, andperforming other tasks for managing SSL property lists

Help Help topics, including documentation.

View Usage

SSL Property Liststreeview

Use this view to review the directory structure of SSL property lists andcopy, rename, or delete existing SSL property lists.

Property List This view contains information about any item highlighted in the SSLConfiguration Editor.

Property Editor This editor is used to change the value of the property selected in theProperty List. It also describes the property in the description field.

Result view Use this view to review the details on any problems encountered whilecreating, editing, deleting, or performing other operations on an SSLproperty list.

Creating an SSL property listThis section takes you through the process of creating an SSL property list and defining all theproperties of a secure connection. The Create a New SSL Property List dialog wizard steps youthrough the process of entering these properties, helping you input the required information. Therequirements are based on whether the SSL property list is for the use of a client or a server, and onthe certificate store type.


38

1. In the SSL Configuration Editor window, select File > New.The Create a New SSL Property List dialog box opens.

2. In the Property list name box, enter a unique name for the SSL property list to be created.3. Optional: We strongly recommend that you establish a password for the SSL property list. An

algorithm is applied to your password to derive a unique encryption key for the list. To access apassword-protected list, users must enter the password as the key to decrypt the list and view itsplaintext contents. If you do not assign a password to the list, the algorithm uses a fixed internaldefault password to generate the encryption key. The key produced in this manner never variesand anyone who uses the SSL Configuration Editor can access the list and view its contents.In the Password box, enter a password for the SSL property list. There are no limitationson length or restrictions on characters allowed; however, the length of the password andrandomness of the characters contribute to its relative security. Use a password that is difficult toguess and share it only with users who need to access the list.

4. If you entered a password for the SSL property list, you must verify the password. In the Re-enterpassword box, type the same password again.

5. U2 supports SSL version 3 and TLS version 1, and the new protocols TLSv1.1 and TLSv1.2. UnderSSL version, select the version of the protocol to be used for this secure connection:

Option Description

SSLv3 Not recommended.TLSv1 Not recommended.TLSv1.1 This is the default security protocol setting.TLSv1.2

Specifying certificates

39

6. Under Certificate store type, select the type of certificate stores to be used for all certificatesissued for this secure connection.

Option Description

U2 This is the default setting. Use this setting if all certificates that apply tothis secure connection are PEM, DER, or PKCS #12 format OS-level files.

Windows All certificates for this connection are looked up from the native Windowscertificate store. Generally, a CA certificate is looked up from Windows CAand ROOT stores, while My Certificate is looked up from MY stores.

In Microsoft’s terminology, these certificate stores are system stores: acollection of physical certificate stores that reside in the Windows Registry.U2 looks up these stores from both of the following Registry locations:▪ CERT_SYSTEM_STORE_CURRENT_USER

▪ CERT_SYSTEM_STORE_LOCAL_MACHINE

7. Click Next to specify the certificate information.The Specify Certificates dialog box opens.

Specifying certificates

1. Specify the path of a certificate, set the private key and password if applicable, specify the path ofthe certificate revocation list (CRL), and specify cipher suites to be used in the handshake.


40

2. If applicable, in the CA certificate box, enter the path of the file to contain a certificate authority(CA) certificate for this secure connection, or click Browse to find the path. See specifics for thecertificate store type below.

U2 certificate store typeSpecify the path of the certificate file that is used as a CA certificate. The format of the certificate can be eitherPEM, DER, or PKCS #12. With the U2 type, you can specify multiple certificate paths, separating each with asemicolon (;).If a CA certificate chain is required, you have the choice of specifying multiple certificate files in the CAcertificate box, or, for PEM-format certificates, concatenating the certificate files into one single file (using OS-level editor or command line) and specifying the concatenated file once.Windows certificate store typeSpecify the same “friendly name” or “Common name” that is used for the certificate in the certificate store.With the Windows type, specify only one certificate, generally the most immediate CA certificate (the one useddirectly to sign the certificate to which authentication is to be performed).A certificate chain is automatically established and used in an SSL session. Note that the above descriptionis based on the assumption that a correct and complete trust relationship exists in the Windows certificatestore for the certificate involved. If a complete chain cannot be formed, an error is reported. This also appliesto other certificate-related properties.

3. Optional for a client SSL property list; required for a server SSL property list. In the MyCertificate box, enter the path for your certificate for this secure connection, or click Browse tofind the path. See specifics for the certificate store type below.

U2 certificate store typeNote that if you specify a path in My Certificate for a server SSL property list, you must also enter values forPrivate key and Private key password. The format of the certificate can be either PEM, DER, or PKCS #12.Windows certificate store typeSpecify the same “friendly name” or “Common name” that is used for the certificate in the certificatestore. Note that when you import a Windows store type certificate into the MY store, you must associate anexportable private key with it by selecting the Exportable private key check box.

4. Applicable to the U2 certificate store type only. Required if you entered a value in My Certificate.In the Private key box, enter the path for the file that contains the private key associated with MyCertificate, or click Browse to find the path. The format of the key file can be either PEM, DER, orPKCS #12.When an SSL property list is created, the private key is loaded into memory and validated againstits corresponding certificate (My Certificate). If it passes validation, the key is stored with the SSLproperty list. This validation feature is designed to enhance the security and protection of theuser’s private key.After the SSL property list has been created, you do not need to keep the private key file on yourhard drive. You can store the key file safely on external media until the next time you want tomodify properties of the SSL property list.

5. Applicable to the U2 certificate store type only. Required if you entered a value in My Certificate.In the Private key password box, enter the password for the private key file.

6. Under Authentication strength, select the appropriate option for this secure connection.

Option Description

Strict This is the default setting. Strict authentication requires that the followingconditions be met:




Specifying authentication properties, CRLs, and cipher suites

41

Option Description

Generous Generous authentication requires only that the incoming server certificate is awell-formed X.509 certificate.

Note: Generous authentication is not highly secure. We recommend using it intest environments only.

7. Choose one of the following actions:

▪ Click Finish to create the property list.

▪ Click Advanced to view the advanced options, such as defining trusted peers, ciphers, or CRLs.

Specifying authentication properties, CRLs, and cipher suites

After selecting the Advanced option, the Advanced Options dialog box opens with the followingoptions.

1. In the Trusted peers box, enter the name of a trusted peer as detailed below.This property tells U2 that additional checking needs to be performed in authenticating theincoming certificate. If you leave this box blank, the incoming certificate is considered valid whenthe CA certificate has verified it. However, if you specify a trusted peer name, a further check isperformed to verify that the incoming certificate’s SubjectAltName extension or CommonNamesubject field matches that of the trusted peer.The trusted peer name can be either a fully specified name (such as [email protected]) or awildcard name. Two wildcard characters are supported:

% Match any character string


For example, %@us.xyz.com matches both [email protected] and [email protected], [email protected] matches [email protected] only.You can enter the names of multiple trusted peers, separating each with a semicolon (;)

2. Optional: In the Random file location box, enter the absolute path of the directory in which U2stores random data for the use of SSL operations, or click Browse to find the path. For example,D:\mysys\work is an absolute path. The directory must currently exist and be writable. Thedefault is “.” (the current directory).By default, random data is stored in the directory in which a client process runs. If you want tocontrol where the random data is stored (for example, to limit users’ access to the random databy storing it in a directory that has restricted permissions), use this property to specify the desireddirectory.When the SSL property list is created, the random data file named U2SSL.rnd is created in thedirectory specified here.

3. Optional: In the Authentication depth list, select the level at which to stop U2’s verificationprocess in authentication processing. The default setting is 5, which is a sufficient depth inmost cases. If you set the authentication depth for fewer levels of authentication than actuallyemployed for the certificate, the certificate will not pass authentication.

4. Applicable to U2 certificate store type only.When you specify a certificate by the CA certificate, My Certificate, or CRL property, the value forthat property is registered internally. When the certificate is loaded into memory to establish anSSL connection, U2 uses this registered path by default to retrieve the certificate.The Certificate path property allows you to specify different locations in which to search thecertificates. Note that this property applies to all certificates in the file.


42

Under Certificate path, select one of the following options:

Option Description

Default Specifies the above-described behavior.Relative U2 looks for the certificate in the current directory under which the

client process is running.Path Enter the path for loading certificates specified in this property list, or

click Browse to find the path. This can be either an absolute path ora relative path. The default path is C:\U2\UniDK\certs. With thispath, the behavior is the same as that of the Default option.

Environment Variable Enter an environment variable name. With this option, the value ofthe environment variable is used as the path in which to load thecertificates. Note that U2 looks up the environment variable for a clientprocess only the first time the process makes an SSL connection; thevalue of the environment variable is cached for later reference by thatprocess.

5. Optional: In the CRL box, enter the path of a certificate revocation list (CRL) to be used forthis secure connection, or click Browse to find the path. You can specify multiple CRL paths,separating each with a semicolon (;).The CRL is a special certificate published by the certificate authority (CA), containing the serialnumbers of certificates that the CA has revoked. If an incoming server certificate is specified,it is checked against the CRL to verify that the certificate has not been revoked before otherverification is performed.The format of the CRL can be either PEM, DER, or PKCS #12.

6. Optional: In the Cipher Suites box, specify a suite of ciphers to be used in a specific order in theSSL handshake. If you make no entry, the default of all ciphers supported by the OpenSSL opensource library applies.For further details, see the description of addCipherSuite() in the UniBasic Extensions manual.Choose one of the following actions:▪ To return to the previous page of the dialog box, click Back.

▪ To discard your entries and cancel the process of creating an SSL property list, click Cancel.

▪ Otherwise, to finish entry of properties and create the SSL property list, click Finish.The SSL Configuration Editor tool checks your entries to ensure that you have input allrequired properties. The requirements are based on whether this is a client or server SSLproperty list, and on the selected certificate store type.If you left a required property blank or entered conflicting or inconsistent values in relatedproperties, when you click Finish, the SSL Configuration Editor issues an error message andredisplays the first page on which you to need to enter information.If the tool finds no errors, the program creates the new SSL property list, saving it in encryptedform to the Windows Registry at:HKEY_LOCAL_MACHINE/SOFTWARE/Rocket Software/UniDK/SPL

Editing an existing SSL property listThis section takes you through the process of editing an existing SSL property list, changing theproperties of a secure connection.

1. Open the SSL Configuration Editor.2. In the SSL Property Explorer, double-click the name of the SSL property list to be edited.

The information for the selected property list populated in the Property Editor.

Editing an existing SSL property list

43

3. If the selected SSL property list has an associated password, enter the password and click OK.Otherwise, if the property list has no associated password, leave the box blank and click OK.

4. In the Property List, select the line containing a property value to be changed.The Property Editor table displays information for the selected property.

Element Description

Property Display only. This box contains the name of the property as it is stored in theSSL Configuration Editor program. Property names cannot be changed

Description Provides guidelines and tips for setting the value of this property.Value Initially displays the current value of the property. In this box, you can change

the value of the selected property.

The following table provides information on changing the value of each SSL property. This tablelists properties in the order in which they appear in the Property List on the left side of the Editorview.

Element Description

SSLVersion U2 supports SSL version 3 and TLS version 1. Select the version of the protocolto be used for this secure connection:▪ SSLv3 – This is the default setting. It is the most widely used protocol.

▪ TLSv1 – This is the newer protocol. Most newer applications support it, butsome older applications may not.

To apply this change, click OK.CertificateStoreTypeSelect the type of certificate stores to be used for all certificates issued for this

secure connection.▪ U2 – This is the default setting. Use this setting if all certificates that apply to

this secure connection are PEM, DER, or PKCS #12 format OS-level files.

▪ Windows – All certificates for this connection are looked up from the nativeWindows certificate store. Generally, a CA certificate is looked up fromWindows CA and ROOT stores, while My Certificate is looked up from MYstores.In Microsoft’s terminology, these certificate stores are system stores: acollection of physical certificate stores that reside in the Windows Registry.U2 looks up these stores from both of the following Registry locations:CERT_SYSTEM_STORE_CURRENT_USERCERT_SYSTEM_STORE_LOCAL_MACHINE

To apply this change, click OK.


44

Element Description

CACertificate Enter the path of the file to contain a certificate authority (CA) certificate forthis secure connection, or click Browse to find the path. See specifics for thecertificate store type below.

U2 certificate store type:

Specify the path of the certificate file that is used as a CA certificate. The formatof the certificate can be either PEM, DER, or PKCS #12. With the U2 type, youcan specify multiple certificate paths, separating each with a semicolon (;).

If a CA certificate chain is required, you have the choice of specifying multiplecertificate files, or, for PEM-format certificates, concatenating the certificatefiles into one single file (using OS-level editor or command line) and specifyingthe concatenated file once.

Windows certificate store type:

Specify the same “friendly name” or “Common name” that is used for thecertificate in the certificate store. With the Windows type, specify only onecertificate path, generally the most immediate CA certificate (the one useddirectly to sign the certificate to which authentication is to be performed).

A certificate chain is automatically established and used in an SSL session.Note that the above description is based on the assumption that a correctand complete trust relationship exists in the Windows certificate store for thecertificate involved. If a complete chain cannot be formed, an error is reported.This also applies to other certificate-related properties.

To apply this change, click OK.MyCertificate Optional for a client SSL property list; required for a server SSL property list.

Enter the path for your certificate for this secure connection, or click Browse tofind the path. See specifics for the certificate store type below.

U2 certificate store type:

Note that if you specify a path in MyCertificate for a server SSL property list, youmust also enter values for MyPrivateKey and PrivateKeyPassword. The formatof the certificate can be either PEM, DER, or PKCS #12.

Windows certificate store type:

Specify the same “friendly name” or “Common name” that is used for thecertificate in the certificate store. Note that when you import a Windows storetype certificate into the MY store, you must associate an exportable private keywith it by selecting the Exportable private key check box.


Editing an existing SSL property list

45

Element Description

MyPrivateKey Applicable to the U2 certificate store type only. Required if you entered a valuein MyCertificate.

Enter the path for the file that contains the private key associated with MyCertificate, or click Browse to find the path. The format of the key file can beeither PEM, DER, or PKCS #12.

When an SSL property list is created, the private key is loaded into memoryand validated against its corresponding certificate (My Certificate). If it passesvalidation, the key is stored with the SSL property list. This validation feature isdesigned to enhance the security and protection of the user’s private key.

After the SSL property list has been created, you do not need to keep theprivate key file in memory. You can store the key file safely on media until thenext time you want to modify properties of the SSL property list.

To apply this change, click OK.PrivateKeyPasswordApplicable to the U2 certificate store type only. Required if you entered a value

in MyCertificate.

Enter the password for the private key file.

To apply this change, click OK.TrustedPeerNameOptional. Enter the name of a trusted peer as detailed below.

This property tells U2 that additional checking needs to be performed inauthenticating the incoming certificate. If you leave this box blank, theincoming certificate is considered valid when the CA certificate has verifiedit. However, if you specify a trusted peer name, a further check is performedto verify that the incoming certificate’s SubjectAltName extension orCommonName subject field matches that of the trusted peer.

The trusted peer name can be either a fully specified name (such [email protected]) or a wildcard name. Two wildcard characters aresupported:

% Match any character string


For example, %@us.xyz.com matches both [email protected] [email protected], while [email protected] matches [email protected].

You can enter the names of multiple trusted peers, separating each with asemicolon (;).



46

Element Description

AuthenticationStrengthOptional. Select the appropriate authentication strength option for this secureconnection:

▪ STRICT – This is the default setting. Strict authentication requires that thefollowing conditions be met:▪ The incoming server certificate is a well-formed X.509 certificate.



▪ GENEROUS – This strength requires only that the incoming server certificateis a well-formed X.509 certificate. Note that generous authentication is nothighly secure. We recommend its use in test environments only.

To apply this change, click OK.CertificatePath Applicable to U2 certificate store type only. Optional.

When you specify a certificate by the CACertificate, MyCertificate, or CRLproperty, the value for that property is registered internally. When thecertificate is loaded into memory to establish an SSL connection, U2 uses thisregistered path by default to retrieve the certificate.

The CertificatePath property allows you to specify different locations in whichto search the certificates. Note that this property applies to all certificates inthe file. Select one of the following options:

▪ DEFAULT – Specifies the above-described behavior.

▪ RELATIVE – U2 looks for the certificate in the current directory under whichthe client process is running.

▪ ENV – Enter an environment variable name. With this option, the valueof the environment variable is used as the path in which to load thecertificates. Note that U2 looks up the environment variable for a clientprocess only the first time the process makes an SSL connection; the valueof the environment variable is cached for later reference by that process.

▪ PATH – Enter the path for loading certificates specified in this property file,or click Browse to find the path. This can be either an absolute path or arelative path. The default path is C:\U2\UniDK\certs. With this path,the behavior is the same as that of the Default option.

To apply this change, click OK.CipherSuite Optional. Specify a suite of ciphers to be used in a specific order in the SSL

handshake. If you make no entry, the default of all ciphers supported by theOpenSSL open source library applies.

To apply this change, click OK.AuthenticationDepthOptional. Enter the level at which to stop U2’s verification process in

authentication processing. The default setting is 5, which is a sufficient depthin most cases. If you specify a depth with fewer levels of authenticationthan actually employed for the certificate, the certificate will not passauthentication.


Deleting an SSL property list

47

Element Description

CRL Optional. Enter the path of a certificate revocation list (CRL) to be used for thissecure connection, or click Browse to find the path. You can specify multipleCRL paths, separating each with a semicolon (;).

The CRL is a special certificate published by the certificate authority (CA),containing the serial numbers of certificates that the CA has revoked. If anincoming server certificate is specified, it is checked against the CRL to verifythat the certificate has not been revoked before other verification is performed.

The format of the CRL can be either PEM, DER, or PKCS #12.

To apply this change, click OK.RandomFileLocationOptional. Enter the absolute path of the directory in which U2 stores random

data for the use of SSL operations, or click Browse to find the path. Forexample, D:\mysys\work is an absolute path. The directory must currentlyexist and be writable. The default is “.” (the current directory).

By default, random data is stored in the directory in which a client process runs.If you want to control where the random data is stored (for example, to limitusers’ access to the random data by storing it in a directory that has restrictedpermissions), use this property to specify the desired directory.

When the SSL property list is created, the random data file named U2SSL.rndis created in the directory specified here.


5. When you have finished making changes to the properties in this SSL property list, save yourchanges.a. To save your changes to the list, click the Save button in the Property List panel.b. To save your changes as a new SSL property list, click the Save As button in the Property List

panel.The Property List Name and Password dialog box opens. Enter a unique name for the newlist, enter a password, and re-enter the password. Click OK.

Deleting an SSL property listThis section shows you how to delete an SSL property list. It is important that you use the SSLConfiguration Editor to perform this task so the file is properly deleted from the Windows Registry.

1. In the SSL Property List, select the SSL property list to be deleted.2. Click the Delete button.

The Property List Password dialog box opens.3. If the selected SSL property list has an associated password, enter the password and click OK.

Otherwise, if the property list has no associated password, leave the box blank and click OK.The Please Confirm dialog box opens. The message states that you are about to delete an SSLproperty list and requests your confirmation to proceed.

4. If you want to cancel the deletion, click Cancel. Otherwise, if you want to complete the procedureand delete the SSL property list, click OK. The SSL property list is deleted from the Registry.

Copying an SSL property listThis section details the steps for copying an SSL property list. The copy function allows you to create anew list from an existing list.


48

You can use this function for two different purposes:

▪ Create a list that is similar to the original – When you have a new list, you can edit its properties,specifying the characteristics of a secure connection that is similar to the connection defined bythe original list.

▪ Rename an existing list and assign it a password – If an existing list has no password or you want tochange its password, you can use this function to rename the list and assign a new password. Youcan then delete the original list if it is no longer needed.

Do not copy an SSL property list by any method other than the SSL Configuration Editor. You must usethis tool so the list is entered properly in the Registry.

1. In the SSL Property List, select the SSL property list to be copied.2. Click File > Copy.

The Property List Password dialog box opens.3. To continue with the copy procedure, if the SSL property list to be copied has an associated

password, enter the password and click OK. If the property list has no associated password, leavethe box blank and click OK.The Console displays the message “List ‘listname’ has been copied successfully.”

4. In the SSL Property Explorer pane, right-click the SSL Property Lists folder.5. In the Enter name for new propertylist box, the system-generated name for the new list is

highlighted. Enter a unique name for the new list.6. In the Enter password for property list box, assign a password to the new list.

To increase the level of security, we strongly recommend that you establish a password for theSSL property list.

7. If you entered a password for the SSL property list, you must verify the password. In the Re-enterpassword box, type the same password again.

Renaming an SSL property listThis section provides instructions for renaming an SSL property list. The rename function allows youto change the name of an existing list by overwriting the old name.

Do not rename an SSL property list by any method other than the SSL Configuration Editor. You mustuse this tool so the list is entered properly in the Registry.

1. In the SSL Property List, right-click the SSL property list to be renamed.2. Select the Rename option.

The Property List Name and Password dialog box opens.3. In the Enter name for new property list box, enter a unique name for the list.4. To continue with the rename procedure, if the SSL property list to be renamed has an associated

password, enter the password and click OK. If the property list has no associated password, leavethe box blank and click OK.The Console displays the message “List ‘old_listname’ has been renamed to ‘new_listname’.”Otherwise, to cancel the rename procedure, click Cancel.

Using the Trace featureThe SSL Configuration Editor provides a Trace feature for recording all operations performedthrough the tool on SSL property lists. The events of these operations are written to a file namedU2SSLConfig.log and also displayed in the Console pane.

Using the Trace feature

49

You can use the log to track activity on the lists and to troubleshoot any problems that may arise whenperforming operations on the lists.

The log is located by default in your C:\temp folder. The log file name and location can bechanged at the user’s discretion.

When you initially open the SSL Configuration Editor, Trace mode is turned off by default. This sectioncontains instructions for turning Trace mode on and off.

1. In the SSL Property List, right-click the SSL property list for which you want to use the Tracefeature.

2. Select Trace.The Trace Log dialog box opens with the following trace options:▪ Trace Log Level:

Log level Description

1 - Brief The information in the trace file will contain only the function name.2 - Detail The information provided in the trace file will contain the function

name and function details. This is the default setting.3 - All The information provided in the trace file will contain the function

name, function details, as well as all additional information. Thissetting has the potential to create very large SSL log files, so should beused with caution.

▪ Trace Log file: Browse to the location where the trace file should reside. The default locationfor the Trace file is C:\temp\U2SSLConfig_WIN.log.

3. With Trace mode turned on, perform operations on SSL property lists as you normally would. Theevents of these operations are recorded in the log.

4. To turn off Trace mode, choose File > Trace.5. Navigate to the folder containing the log and open the file to view its contents.

Rocket U2 Clients and APIs September 2015 UCC...

Documents

Transcript of Rocket U2 Clients and APIs September 2015 UCC...