Administrative Supplement for Client APIs · : Describes Using the IBM JDBC Driver for UniData and...

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\APISUPP\Front.fmMarch 5, 2010 2:23 pm

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

UniData

Administrative Supplement for Client
APIs
UDT-720-SUPP-1

ii Administrative Su

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\APISUPP\Front.fmMarch 5, 2010 2:23 pm

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Notices

EditionPublication date: July 2008Book number: UDT-720-SUPP-1Product version: UniData 7.2

Copyright© Rocket Software, Inc. 1988-2008. All Rights Reserved.

TrademarksThe following trademarks appear in this publication:

Trademark Trademark Owner

Rocket Software™ Rocket Software, Inc.

Dynamic Connect® Rocket Software, Inc.

RedBack® Rocket Software, Inc.

SystemBuilder™ Rocket Software, Inc.

UniData® Rocket Software, Inc.

UniVerse™ Rocket Software, Inc.

U2™ Rocket Software, Inc.

U2.NET™ Rocket Software, Inc.

U2 Web Development Environment™ Rocket Software, Inc.

wIntegrate® Rocket Software, Inc.

Microsoft® .NET Microsoft Corporation

Microsoft® Office Excel®, Outlook®, Word Microsoft Corporation

Windows® Microsoft Corporation

Windows® 7 Microsoft Corporation

Windows Vista® Microsoft Corporation

Java™ and all Java-based trademarks and logos Sun Microsystems, Inc.

UNIX® X/Open Company Limited

pplement for Client APIs

The above trademarks are property of the specified companies in the United States, other countries, or both. All other products or services mentioned in this document may be covered by the trademarks, service marks, or product names as designated by the companies who own or market them.

License agreementThis software and the associated documentation are proprietary and confidential to Rocket Software, Inc., are furnished under license, and may be used and copied only in accordance with the terms of such license and with the inclusion of the copyright notice. This software and any copies thereof may not be provided or otherwise made available to any other person. No title to or ownership of the software and associated documentation is hereby transferred. Any unauthorized use or reproduction of this software or documentation may be subject to civil or criminal liability. The information in the software and documentation is subject to change and should not be construed as a commitment by Rocket Software, Inc.

Restricted rights notice for license to the U.S. Government: Use, reproduction, or disclosure is subject to restrictions as stated in the “Rights in Technical Data-General” clause (alternate III), in FAR section 52.222-14. All title and ownership in this computer software remain with Rocket Software, Inc.

NoteThis product may contain encryption technology. Many countries prohibit or restrict the use, import, or export of encryption technologies, and current use, import, and export regulations should be followed when exporting this product.

Please be aware: Any images or indications reflecting ownership or branding of the product(s) documented herein may or may not reflect the current legal ownership of the intellectual property rights associated with such product(s). All right and title to the product(s) documented herein belong solely to Rocket Software, Inc. and its subsidiaries, notwithstanding any notices (including screen captures) or any other indications to the contrary.

Contact informationRocket Software275 Grove Street Suite 3-410Newton, MA 02466-2272 USA Tel: (617) 614-4321 Fax: (617) 630-7100Web Site: www.rocketsoftware.com

Administrative Supplement for Client APIs iii

http://www.rocketsoftware.com

http://www.rocketsoftware.com

Table of Contents

:\ProgMarch

Table of Contents

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

PrefaceOrganization of This Manual . . . . . . . . . . . . . . . viiDocumentation Conventions. . . . . . . . . . . . . . . . viii

Chapter 1 IntroductionWhat Are the Client APIs? . . . . . . . . . . . . . . . . 1-2

UCI . . . . . . . . . . . . . . . . . . . . . . 1-2UniOLEDB . . . . . . . . . . . . . . . . . . . 1-2InterCall . . . . . . . . . . . . . . . . . . . . 1-3UniObjects . . . . . . . . . . . . . . . . . . . 1-3UniObjects for Java . . . . . . . . . . . . . . . . . 1-3UniObjects for .NET . . . . . . . . . . . . . . . . 1-3IBM JDBC Driver for UniData and UniVerse. . . . . . . . . 1-3

Chapter 2 Maintaining the UniRPCSystem Requirements . . . . . . . . . . . . . . . . . . 2-3How the UniRPC Works . . . . . . . . . . . . . . . . . 2-4Maintaining the UniRPC . . . . . . . . . . . . . . . . . 2-5

UniRPC Maintenance on UniVerse Systems . . . . . . . . . 2-5UniRPC Maintenance on UniData Servers. . . . . . . . . . 2-10

About the unirpcservices File . . . . . . . . . . . . . . . 2-12

Chapter 3 The UCI Config EditorUCI Configuration File . . . . . . . . . . . . . . . . . 3-3Starting the UCI Editor . . . . . . . . . . . . . . . . . 3-4Adding a Data Source . . . . . . . . . . . . . . . . . . 3-5

Data Source Parameters . . . . . . . . . . . . . . . 3-8New Data Source Parameters and Comments . . . . . . . . . 3-11Comments . . . . . . . . . . . . . . . . . . . . 3-12

Modifying a Data Source. . . . . . . . . . . . . . . . . 3-13

ram Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\APISUPP\apisuppTOC.fm (bookTOC.template)5 2010 2:23 pm

Deleting a Data Source . . . . . . . . . . . . . . . . . 3-15Working with Multiple Data Sources . . . . . . . . . . . . . 3-16Creating a UCI Configuration File . . . . . . . . . . . . . . 3-17Setting the UciCfgFile Key in the Registry . . . . . . . . . . . 3-18Opening an Alternative UCI Configuration File . . . . . . . . . . 3-19Enabling and Disabling Logging . . . . . . . . . . . . . . 3-20Logging Client Connections . . . . . . . . . . . . . . . . 3-21

Chapter 4 Accessing UniData AccountsRunning Concurrent UniData Versions . . . . . . . . . . . . 4-3

Running UCI, UniData ODBC, or UniOLEDB Concurrently . . . . 4-3Running InterCall, UniObjects, or UniObjects for Java Concurrently . 4-4

Tracing Events . . . . . . . . . . . . . . . . . . . . 4-5

Chapter 5 Device LicensingLicensing Modes . . . . . . . . . . . . . . . . . . . 5-3Why Do I Need Device Licensing?. . . . . . . . . . . . . . 5-4

Device Licensing Requirements . . . . . . . . . . . . . 5-4Connection Types . . . . . . . . . . . . . . . . . . . 5-5

Direct Connections . . . . . . . . . . . . . . . . . 5-5Two-Tier Connections . . . . . . . . . . . . . . . . 5-5Multiple-Tier Connections . . . . . . . . . . . . . . . 5-5Using Device Subkeys . . . . . . . . . . . . . . . . 5-6

Chapter 6 The U2 SSL Configuration EditorAbout SSL Property Lists. . . . . . . . . . . . . . . . . 6-3

List Encryption . . . . . . . . . . . . . . . . . . 6-3Working with SSL Property Lists. . . . . . . . . . . . . 6-3Loading and Decrypting an SSL Property List . . . . . . . . 6-4SSL Properties . . . . . . . . . . . . . . . . . . 6-4

Starting the U2 SSL Configuration Editor . . . . . . . . . . . 6-12Creating a New SSL Property List . . . . . . . . . . . . . . 6-15Editing an Existing SSL Property List . . . . . . . . . . . . . 6-28Deleting an SSL Property List . . . . . . . . . . . . . . . 6-39Copying an SSL Property List . . . . . . . . . . . . . . . 6-40Renaming an SSL Property List . . . . . . . . . . . . . . . 6-43Using the Trace Feature . . . . . . . . . . . . . . . . . 6-45Using the Console/Problems View . . . . . . . . . . . . . . 6-46

Table of Contents v

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\APISUPP\Preface3/5/10

PrefaceThis manual introduces IBM’s seven common APIs. It also provides important information that developers using any of the common APIs will need. It includes information about the UniRPC, the UCI Config Editor, the ud_database file, and device licensing.

vi Administrative Supplement for Client APIs

C:\Program Files\Adobe\FrameMaker8\UniData

Organization of This ManualThis manual contains the following:

Chapter 1, “Introduction,” introduces the seven common APIs.Chapter 2, “Maintaining the UniRPC,” describes the UniRPC daemon (unirpcd) or service (unirpc), and the unirpcservices file.Chapter 3, “The UCI Config Editor,” describes how to use the UCI Config Editor to create and maintain data source definitions in the UCI configuration file.Chapter 4, “Accessing UniData Accounts,” describes UniData’s ud_database file.Chapter 5, “Device Licensing,” describes how device licensing on UniVerse and UniData servers works with multiple client connections.

vii


Documentation ConventionsThis manual uses the following conventions:

Documentation Conventions

Convention Usage

Bold In syntax, bold indicates commands, function names, and options. In text, bold indicates keys to press, function names, menu selections, and MS-DOS commands.

UPPERCASE In syntax, uppercase indicates database commands, keywords, and options; UniBasic statements and functions; and SQL state-ments and keywords. In text, uppercase also indicates database identifiers such as file names, account names, schema names, and Windows file names and paths.

Italic In syntax, italic indicates information that you supply. In text, italic also indicates UNIX commands and options, file names, and paths.

Courier Courier indicates examples of source code and system output.

Courier Bold In examples, courier bold indicates characters that the user types or keys the user presses (for example, <Return>).

[ ] Brackets enclose optional items. Do not type the brackets unless indicated.

{ } Braces enclose nonoptional items from which you must select at least one. Do not type the braces.

itemA | itemB A vertical bar separating items indicates that you can choose only one item. Do not type the vertical bar.

... Three periods indicate that more of the same type of item can optionally follow.

? A right arrow between menu options indicates you should choose each option in sequence. For example, “Choose File ? Exit” means you should choose File from the menu bar, then choose Exit from the File menu.

viii Administrative Supplement for Client APIs


The following are also used:

Syntax definitions and examples are indented for ease in reading.All punctuation marks included in the syntax—for example, commas, parentheses, or quotation marks—are required unless otherwise indicated.Syntax lines that do not fit on one line in this manual are continued on subse-quent lines. The continuation lines are indented. When entering syntax, type the entire syntax entry, including the continuation lines, on the same input line.

API DocumentationThe following books document application programming interfaces (APIs) used for developing client applications that connect to UniVerse and UniData servers.

Administrative Supplement for Client APIs: Introduces IBM’s seven common APIs, and provides important information that developers using any of the common APIs will need. It includes information about the UniRPC, the UCI Config Editor, the ud_database file, and device licensing.

UCI Developer’s Guide: Describes how to use UCI (UniCall Interface), an interface to UniVerse and UniData databases from C-based client programs. UCI uses ODBC-like function calls to execute SQL statements on local or remote UniVerse and UniData servers. This book is for experienced SQL programmers.

IBM JDBC Driver for UniData and UniVerse: Describes Using the IBM JDBC Driver for UniData and UniVerse, an interface to UniData and UniVerse databases from JDBC applications. This book is for experienced programmers and application developers who are familiar with UniData and UniVerse, Java, JDBC, and who want to write JDBC applications that access these databases.

InterCall Developer’s Guide: Describes how to use the InterCall API to access data on UniVerse and UniData systems from external programs. This book is for experi-enced programmers who are familiar with UniVerse or UniData.

UniObjects Developer’s Guide: Describes UniObjects, an interface to UniVerse and UniData systems from Visual Basic. This book is for experienced programmers and application developers who are familiar with UniVerse or UniData, and with Visual Basic, and who want to write Visual Basic programs that access these databases.

ix


UniObjects for Java Developer’s Guide: Describes UniObjects for Java, an interface to UniVerse and UniData systems from Java. This book is for experienced programmers and application developers who are familiar with UniVerse or UniData, and with Java, and who want to write Java programs that access these databases.

UniObjects for .NET Developer’s Guide: Describes UniObjects, an interface to UniVerse and UniData systems from .NET. This book is for experienced programmers and application developers who are familiar with UniVerse or UniData, and with .NET, and who want to write .NET programs that access these databases.

Using UniOLEDB: Describes how to use UniOLEDB, an interface to UniVerse and UniData systems for OLE DB consumers. This book is for experienced programmers and application developers who are familiar with UniVerse or UniData, and with OLE DB, and who want to write OLE DB programs that access these databases.

x Administrative Supplement for Client APIs

:\ProgMarch

1Chapter

ram Fi5 2010

Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta Beta

Introduction

What Are the Client APIs?. . . . . . . . . . . . . . . . 1-2 UCI . . . . . . . . . . . . . . . . . . . . . 1-2 UniOLEDB . . . . . . . . . . . . . . . . . . . 1-2 InterCall . . . . . . . . . . . . . . . . . . . . 1-3 UniObjects . . . . . . . . . . . . . . . . . . . 1-3 UniObjects for Java . . . . . . . . . . . . . . . . 1-3 UniObjects for .NET . . . . . . . . . . . . . . . . 1-3 IBM JDBC Driver for UniData and UniVerse . . . . . . . . 1-3

les\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\APISUPP\Ch1TOC.fm2:23 pm

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\APISUPP\Ch13/5/10

What Are the Client APIs?IBM provides seven common APIs for writing client application programs that connect to UniVerse and UniData databases. We call them common APIs because programs written in them can access data in both databases.

The seven Client APIs are:

UCI (Uni Call Interface)UniOLEDBInterCallUniObjectsUniObjects for JavaUniObjects for .NETIBM JDBC Driver for UniData and UniVerse

UCIUCI is a C-language API. It lets developers write UNIX and Windows client programs that use SQL statements to access and manipulate data in UniVerse and UniData databases. UCI is modelled on the 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 standard ODBC interface, UCI is more closely integrated with the extended relational database model used by UniVerse and UniData, with their nested tables, transaction processing support, and so forth.

UniOLEDBUniOLEDB is IBM’s OLE DB provider for UniData and UniVerse. It uses Microsoft’s Universal Data Access (UDA) technology to provide applications in an enterprise network with direct access to UniData and UniVerse databases.

1-2 Administrative Supplement for Client APIs


InterCallInterCall is an open API that lets client application programs developed on UNIX or Windows systems access data on UniVerse or UniData 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 tool that 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 UniData from Visual Basic, or from any other program development environment that uses the Microsoft ActiveX interface. 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 UniVerse and UniData databases. UniObjects for Java, based on the UniOb-jects model, is a 100% Pure Java™ Class Library whose objects can 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 UniVerse and UniData databases. UniObjects for .NET is fully integrated with the Microsoft environment.

IBM JDBC Driver for UniData and UniVerseThe IBM JDBC driver for UniData and UniVerse is an interface to UniData and UniVerse databases from JDBC applications. This book is for experienced programmers and application developers who are familiar with UniData and UniVerse, Java, JDBC, and who want to write JDBC applications that access these databases.

1-3


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


:\ProgMarch

1Administering UniData on Windows NT or Windows 20000

2Chapter

ram Fi5 2010


Maintaining the UniRPC

System Requirements . . . . . . . . . . . . . . . . . 2-3How the UniRPC Works . . . . . . . . . . . . . . . . 2-4Maintaining the UniRPC . . . . . . . . . . . . . . . . 2-5 UniRPC Maintenance on UniVerse Systems . . . . . . . . . 2-5 UniRPC Maintenance on UniData Servers . . . . . . . . . 2-10About the unirpcservices File . . . . . . . . . . . . . . . 2-12

les\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\APISUPP\Ch2TOC.fm2:23 pm Administering UniData on Windows NT or Windows 2000


The UniRPC lets local UniVerse and UniData systems communicate with remote systems. The communicating systems must use TCP/IP networking software to make connections.

Note: 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 does not 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 UniData servers requires little maintenance, other than starting and stopping the UniRPC daemon or service. On UniVerse servers, you can also do the following:

Change the port numberAdd entries to a UNIX hosts file



System RequirementsBefore installing layered or third-party products that use the UniRPC, such as the UniDK, UniOLEDB, the IBM JDBC Driver for UniData and UniVerse, or UniAdmin, you must install and configure TCP/IP using the instructions supplied by the TCP/IP facility vendor. On UniVerse systems, you should then identify the systems to be networked with the database by defining them in the /etc/hosts file. See “Maintaining the hosts File (UniVerse Only)” on page 2-6 for more information.

2-3


How the UniRPC WorksThe UniRPC daemon unirpcd (or the UniRPC service unirpc) waits for a request from a client system to connect to a server process. When it receives a connection request, it checks the unirpcservices files to verify that the client system 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 server process 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 SystemsUse UniAdmin to:

Define the UniRPC port numberMaintain the hosts file on a UNIX server

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

This window has the following components:

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

2-5


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), you do not need to use the /etc/hosts file to define, change, and delete network nodes. See the UNIX networking 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. You specify the port number on the client and the server systems.

Note: If you specify a port number other than the 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 Services window. To change the number, do the following:

1. Click Change. The Change Port Number dialog box appears. Enter a new number in the Enter new Port number field.

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

Note: To use the new port number, you must restart the UniRPC daemon (see “Starting the UniRPC Daemon” on page 2-10).

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 Node

To 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 the hosts file. If the new node matches an existing entry, a message box appears. You must acknowledge the message before you can enter alternative values. If the new node details are unique, the new node definition is added to the hosts file and the Network Services window is updated.

Modifying a Node

To 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 acknowledge the message before you can enter alternative values. If the node details are unique, the node definition is added to the hosts file and the Network Services window is updated.

Removing a Node

To 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 and Stopping the UniRPC on Windows Platforms

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

From the Windows Control Panel

2-7


From the UniVerse Control PanelAt the MS-DOS prompt

From the Control Panel

To start the UniRPC:

1. 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 Panel

To start the UniRPC:

1. Choose Start -> Programs -> IBM U2 -> UniVerse Control.2. Click the Start All Services button to start all UniVerse services.

At the MS-DOS Prompt

Enter 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 unless you 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 PanelFrom the UniVerse Control PanelAt the MS-DOS prompt



Note: If users are connected to the services when they are shut down, the users do not lose their connections; the connections remain active until the users terminate them. However, it is not possible for new users to connect to UniVerse.

If you want to do a complete shutdown of UniVerse to restart the services, be sure that all connections are terminated first.

From the Control Panel

To stop the UniRPC:

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

UniVerse Resource ServiceUniRPC ServiceUniVerse Telnet Service

3. Choose UniRPC Service, then choose Stop.4. Click OK. The UniRPC daemon or service is shut down.

From the UniVerse Control Panel

To stop the UniRPC:

1. Choose Start -> Programs -> IBM 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 Prompt

To stop the UniRPC:

1. Enter the following command at the MS-DOS prompt:D:\users>net stop unirpcA message appears prompting you to confirm that you want to stop the UniRPC.

2. Enter Y to stop the UniRPC daemon or service.

2-9


Starting and Stopping the UniRPC Daemon on UNIX Systems

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

Starting the UniRPC Daemon

To start the UniRPC daemon:

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 messages.

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

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

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

Stopping the UniRPC Daemon

To stop the UniRPC daemon:

1. Choose Rpc administration from the Package menu, then choose Halt the rpc daemon.

2. At the 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 UniData ServersOn UniData servers, UniRPC maintenance is minimal. You cannot change the port number of the UniRPC, and there is no need to maintain a hosts file.



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

2-11


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/ibm/unishared/unirpc.On Windows platforms the default location is <drive>:\ibm\unishared\unirpc.

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

On UNIX systems, execute the command:$ cat /.unisharedOn Windows platforms, find the registry entry under the subkey \HKEY_LOCAL_MACHINE\SOFTWARE\ibm\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 the requested service.

The UniRPC software uses field 3 of the unirpcservices file to verify that a machine making a request for a service is allowed to do so. The following table lists the fields in the unirpcservices file:

unirpcservices File Fields

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 hosts defined 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/ibm/uv/bin/uvnetd host1,host2,host3 TCP/IP 3 3600 uvdrsrv /usr/ibm/uv/bin/uvdrsrvd * TCP/IP 0 3600 uvcs /usr/ibm/uv/bin/uvapi_server * TCP/IP 0 3600 uvfilefix /usr/ibm/uv/bin/uvfilefix_server * TCP/IP 0 3600 uvserver /usr/ibm/uv/bin/uvsrvd * TCP/IP 0 3600

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

Check for the existence of the unirpcservices fileVerify that services are defined in itStart 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 3600 udserver /usr/ud72/bin/udsrvd * TCP/IP 0 3600

2-13

:\ProgMarch


3Chapter

ram Fi5 2010


The UCI Config Editor

UCI Configuration File . . . . . . . . . . . . . . . . . 3-3Starting the UCI Editor . . . . . . . . . . . . . . . . . 3-4Adding a Data Source . . . . . . . . . . . . . . . . . 3-5 Data Source Parameters . . . . . . . . . . . . . . . 3-8 New Data Source Parameters and Comments . . . . . . . . 3-11 Comments . . . . . . . . . . . . . . . . . . . 3-12Modifying a Data Source . . . . . . . . . . . . . . . . 3-13Deleting a Data Source . . . . . . . . . . . . . . . . . 3-15Working with Multiple Data Sources . . . . . . . . . . . . 3-16Creating a UCI Configuration File . . . . . . . . . . . . . 3-17Setting the UciCfgFile Key in the Registry . . . . . . . . . . 3-18Opening an Alternative UCI Configuration File . . . . . . . . . 3-19Enabling and Disabling Logging . . . . . . . . . . . . . . 3-20Logging Client Connections . . . . . . . . . . . . . . . 3-21



The UCI Config Editor lets you define and configure data sources. When an application requests a connection to a data source, UCI uses the information in the UCI configuration file (uci.config or another UCI configuration file you create) to connect to the data source.

The UCI Config 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 Config Editor window.Enable or disable logging for the UCI Config Editor.

3-2


UCI Configuration FileApplications access data sources through entries in the UCI configuration file. This file contains connection parameters needed to route connection requests to the appropriate UniData or UniVerse server.

When an application tries to connect to a data source, the UCI configuration file on the client machine is 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 under HKEY_LOCAL_MACHINE \SOFTWARE\IBM\UCI.

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

Establish communicationsStart a UniData or UniVerse server processRoute query and update requests

In the UCI configuration file on the client machine, you must define the UCI data sources to which you want applications to connect. Use the UCI Config Editor to define and modify data source definitions.

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



Starting the UCI EditorTo start the UCI Config Editor, from the Start menu choose Programs -> IBM U2 -> UniDK -> UCI Editor. The UCI Editor window appears:

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

3-4


Adding a Data SourceTo add a data source:

1. From the UCI Config Editor, right-click the folder icon for [ODBC DATA SOURCES], then click Add. The New Data Source dialog box appears, 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.



5. Click Ok to save your definition and exit the New Data Source dialog box. Click Cancel to exit the dialog box without saving your definition. The Data Source Adding dialog box appears, as shown in the following example:

The parameters that appear automatically on the Data Source Adding dialog box are required for each data source you add. Their values are set according to the information you provide on the New Data Source dialog box.

3-6


6. To add additional parameters, click Add. The Parameter Adding dialog box appears, as shown in the following example:

7. Click the parameter you want to add from the Parameter list. For a list of parameters, see “Data Source Parameters” on page 3-8.

8. In the Value field, enter an appropriate value for the parameter. Information about the parameter appears under Parameter Description.

9. Click Set to add the parameter.10. 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-13.

11. After you finish adding parameters for the data source, click Save.12. When you finish adding data sources, choose File ? Save disk file to save

your changes.



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

DBMSTYPENETWORKSERVICEHOST

You also should include the ACCOUNT and USERNAME parameters for each entry.

Two parameters you might want to change are MAXFETCHBUFF and MAXFETCHCOLS. Use these parameters to increase the amount of data in each buffer sent from the server to the client. This will improve performance by reducing the number of data transfers between server and client. For more information 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 NLS parameters. For information about setting the NLS parameters, see the UCI Developer’s Guide.

Warning: Adding or changing other parameters can make UCI unusable.

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

Parameters for 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 the DBMSTYPE you specified. For UniData, specify udserver; for UniVerse, specify uvserver.

none

HOST Specifies the name of the server machine or its network IP address.

none

3-8


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


ACCOUNT Specifies one of the following:? The full path of a UniData or UniVerse account

directory

? A valid UniVerse schema name

? A valid UniData database name

A UniData database name is valid if it appears as an entry in the ud_database file. For UNIX systems, this file is located in the /usr/ud60/include path. For Windows systems, it is located in \udthome\include.

none

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

No

CASE Produces an SQLColAttributes report if the column is case-sensitive.

Yes

DESCB4EXEC (For internal use only) Indicates if the database’s describe operation is legal before executing the SQL statement.

Yes

DSPSIZE Produces an SQLColAttributes report showing the column display size.

Yes

MAPERROR Maps UniVerse error codes to standard ODBC SQLSTATE error codes. Whenever the server returns one 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 parameter markers. If not, the ? (question mark) is the marker character.

No

Other Parameters for Data Source Entry



MAXFETCHBUFF Controls the maximum buffer size on the server to hold data rows. The server usually fills this buffer with as many rows as possible before sending data to the client. If any single row exceeds the length of MAXFETCHBUFF, SQLFetch fails, and you should increase the value of this parameter.

8192 bytes

MAXFETCHCOLS Controls the maximum number of column values the server can put in the buffer before sending data to the client. If the number of columns in the result set exceeds the number specified by MAXFETCHCOLS, SQLFetch fails, and you should increase the value of this parameter.

400 column values

NLSLCALL Specifies all components of a locale. none

NLSLCCOLLATE Specifies the name of a locale whose sort order to use.

none

NLSLCCTYPE Specifies the name of a locale whose character type to use.

none

NLSLCMONETARY Specifies the name of a locale whose monetary convention to use.

none

NLSLCNUMERIC Specifies the name of a locale whose numeric convention to use.

none

NLSLCTIME Specifies the name of a locale whose time convention to use.

none

NLSLOCALE Specifies all components of a locale. none

NLSMAP Specifies the name of the server’s NLS map for the connection. For a client to connect to the server successfully, the server must be able to locate the specified map, which must also be installed in the server’s shared memory segment.

none

NULLABLE Produces an SQLDescribeCol and SQLCo-lAttributes report if the column is nullable.

Yes

SEARCH Produces an SQLColAttributes report if the column is searchable.

Yes


Other Parameters for Data Source Entry (Continued)

3-10


New Data Source Parameters and CommentsYou 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 one of the following in the Parameter field:

A new parameter nameA hash sign (#) to indicate a comment

New 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 the parameter information using the SQLDataSources function.

TXBEHAVIOR Defines default autocommit/ manual-commit transaction behavior. Normally, UniVerse is autocommit by default.

1

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

No

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

No

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

No

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

Yes

UNSIGNED Produces an SQLColAttributes report if the column is UNSIGNED.

No

UPDATE Produces an SQLColAttributes report if the column is updatable.

Yes

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


Other Parameters for Data Source Entry (Continued)



CommentsTo include a comment in a data source definition, enter a hash sign (#) in the Parameter field, then enter your comment in the Value field. Comments appear before parameters in the data source definition.

3-12


Modifying a Data SourceTo modify a data source:

1. From the UCI Config Editor, right-click the data source you want to modify, then click Edit. The Data Source Editing dialog box appears, as shown in the following example:

2. You can add new parameters or edit existing ones. To add new parameters, see “Adding a Data Source” on page 3-5. To edit parameters, continue with the following steps.

3. Click the parameter you want to modify. The parameter name and current value appear under Parameter Editor.

4. To remove the parameter, click Remove. To modify the parameter value, enter a new value in the Value field, then click Change.Note: You also can modify a parameter value by double-clicking the value at the top of the dialog box, then entering the new value.

5. After you finish modifying parameters for the data source, click Save.



6. When you finish modifying data source information, choose File -> Save disk file to save your changes.

3-14


Deleting a Data SourceTo delete a data source:

1. From the UCI Config Editor, right-click the data source you want to delete, then click Delete.

2. When you finish deleting data sources, choose File -> Save disk file to save your changes.



Working with Multiple Data SourcesYou can add or modify several data sources at the same time. Each data source appears in its own dialog box. For example, while editing the corp1 data source, you could add a new data source named corp2. You can resize and move the Data Source Editing and Data Source Adding dialog boxes within the UCI Config Editor window.

You also can use conventional Windows key combinations to copy (Ctrl-C) and paste (Ctrl-V) data source information.

To switch between dialog boxes, on the Window menu, click the dialog box you want to make active.

3-16


Creating a UCI Configuration FileComplete the following steps to create your own UCI configuration file:

1. From the UCI Config Editor, open a UCI configuration file you want to use as a base for the new UCI configuration file. To open a file, see “Opening an Alternative UCI Configuration File” on page 3-19.

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. Modify the new UCI configuration file with the appropriate data source information.



Setting the UciCfgFile Key in the RegistryThe UCI configuration file that the client uses is specified in the UciCfgFile key in the system registry under HKEY_LOCAL_MACHINE \SOFTWARE\IBM\UCI. Initially this is set to uci.config, the UCI configuration file IBM ships to you.

To change this setting to point to a different UCI configuration file:

1. From the UCI Config Editor, make sure the data source information in the left pane of the UCI Config Editor window represents the UCI configuration file you want to set in the UciCfgFile registry key.

2. Choose File -> Reset Registry.

3-18


Opening an Alternative UCI Configuration FileTo open the UCI configuration file that is set in the UciCfgFile registry key, choose File -> Get Registry.

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

1. From the UCI Config Editor, choose File -> Open disk file.2. From the Open File dialog box, choose the appropriate UCI configuration

file (the file should have the extension .config), then click Open.3. If you try to open a file with an extension other than .config, the following

dialog box appears:

In this case, indicate whether you want to continue working on this file.



Enabling and Disabling LoggingYou can produce log information for the UCI Config Editor that can help IBM troubleshoot problems in your UCI configuration file.

To enable or disable logging:

1. From the UCI Config Editor, on the Logging menu, click Logging.

2. From the Logging Configuration dialog box, specify the appropriate configuration information. The following table describes each parameter that appears on the Logging Configuration dialog box:

Logging Configuration Dialog Box Parameters

Parameter Description

Logging Enables or disables logging.

Destination Indicates whether logging information is written to the monitor or to the file specified in the Log File field.

Log File Specifies the file to which logging information is written if File is specified as the Destination. By default, logging information is written to uciconfig.log.

3. Click OK to save your settings and exit the Logging Configuration dialog box. Click Cancel to exit the dialog box without saving changes.

3-20


Logging Client ConnectionsA server-side debugging log is available for tracking client connections.

The debugging log is located in the /tmp/ directory on UNIX, or C:\tmp on Windows platforms, by default.

Complete the following steps to set up the debugging log:

1. Edit the serverdebug file in the UVHOME directory.2. In the first column, enter uvcs, indicating that you want to log the

connection progress for both uvapi_server and uvapi_slave.3. In the next column, enter an integer indicating the level of logging infor-

mation you want to maintain. The valid integers are:0 – No debugging.1 – Captures information about the startup connection only.9 – Captures information about every call.

4. In the third column, enter the full path for the log file location. If this value does not exist, the logs are written to /tmp/uvapiserver_###.log as the default on UNIX systems, or C:\tmp\uvapiserver####.log as the default on Windows systems. #### is the uvapi_server process ID.


:\ProgMarch


4Chapter

ram Fi5 2010


Accessing UniData Accounts

Running Concurrent UniData Versions . . . . . . . . . . . . 4-3 Running UCI, UniData ODBC, or UniOLEDB Concurrently . . . 4-3 Running InterCall, UniObjects, or UniObjects for Java Concurrently . 4-4Tracing Events . . . . . . . . . . . . . . . . . . . 4-5



UniData databases are organized into accounts. A consumer connects to a UniData account and can access the files there. You optionally can define the account as a database in the ud_database file on the server. You can also include the account path or database name in the UCI data source definition in the UCI configuration file. For information about setting up the UCI Configuration file, see Chapter 3, “The UCI Config Editor.”

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 the database name.

If you want to access an account that has a UDTHOME directory different from the default UDTHOME directory, 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 is located in \udthome\include. You can find the path for udthome by looking in the registry under HKEY_LOCAL_MACHINE\SOFTWARE\IBM\UniData\7.2. Use any text editor to modify the ud_database file.

To determine your default UniData home directory, use the UNIX env command. Output from this command 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=db2 UDTHOME=d:\disk2\test72 UDTACCT=d:\disk2\test72\testacct

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



Running Concurrent UniData VersionsWhen you install UniData 7.2 on a machine where UniData 5.1 or UniData 5.2 was previously installed, the unirpcservices file is overwritten with UniData 7.2 infor-mation. If you want to run UniData 5.1, UniData 5.2, UniData 6.0, UniData 6.1or UniData 7.1 concurrently with UniData 7.2, you must edit certain files to enter the UniData 5.1, UniData 5.2, UniData 6.0, or UniData 6.1 definitions.

Running UCI, UniData ODBC, or UniOLEDB ConcurrentlyIf you are running UCI, UniData ODBC, or UniOLEDB with concurrent versions of UniData, you must edit the unirpcservices file and the uci.config file to define locations of executables from the previous version of UniData.

The following example illustrates unirpcservices file entries when running UniData 5.2 concurrently with UniData 7.2:

udserver_52 d:\IBM\ud52\bin\udsrvd.exe * TCP/IP 0 3600udserver_71 c:\IBM\ud72\bin\udsrvd.exe * TCP/IP 0 3600

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

<unidata52> DBMSTYPE = UNIDATA network = TCP/IP service = udserver_52 host = server1

<unidata72> DBMSTYPE = UNIDATA network = TCP/IP service = udserver_72 host = server2

4-3


Running InterCall, UniObjects, or UniObjects for Java ConcurrentlyIf you are running InterCall, UniObjects, or UniObjects for Java with concurrent versions of UniData, you must edit the unirpcservices file to define the location of the udapi_server executable for the previous version you are running.

The following example illustrates unirpcservices file entries when running UniData 5.2 concurrently with UniData 7.2:

udcs_52 C:\IBM\ud52\bin\udapi_server.exe * TCP/IP 0 3600udcs C:\IBM\ud72\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_52 for UniData 5.2 or udcs for UniData 7.2.



Tracing EventsYou can use the tracing feature to create logs of events between clients and the database through the server. Logs enable support personnel to help troubleshoot problems. You can define trace levels for database entries in the ud_database file.

The following table describes the valid trace levels and the associated information that is written to the trace log:

Valid Trace Levels

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=dbase3 UDTHOME=/disk1/ud72 UDTACCT=/home/test/udtest TRACE_LEVEL=3

4-5

:\ProgMarch


5Chapter

ram Fi5 2010


Device Licensing

Licensing Modes . . . . . . . . . . . . . . . . . . . 5-3Why Do I Need Device Licensing? . . . . . . . . . . . . . 5-4 Device Licensing Requirements . . . . . . . . . . . . 5-4Connection Types . . . . . . . . . . . . . . . . . . 5-5 Direct Connections. . . . . . . . . . . . . . . . . 5-5 Two-Tier Connections. . . . . . . . . . . . . . . . 5-5 Multiple-Tier Connections . . . . . . . . . . . . . . 5-5 Using Device Subkeys . . . . . . . . . . . . . . . 5-6



This chapter describes how device licensing works. For more information about device licensing, see Installing and Licensing UniData Products and Administering UniVerse.

5-2


Licensing ModesUniVerse and UniData provide two licensing modes:

Session licensingDevice licensing

Session Licensing

Session licensing is like the licensing system used before Release 9.5 of UniVerse and Release 5.1 of UniData. Every connection from telnet or an API, even from the same PC, consumes one database license. 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 from a 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):

UCIUniObjectsUniObjects for JavaUniObjects for .NETInterCallUniOLEDB



Why Do I Need Device Licensing?Users accessing a database server through one or more client application programs may want to put their licensing scheme on a one-license-per-device basis. Such applications often open multiple connections 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 UniData Release 5.1, each connection to the server consumed its own separate license, even though only one user was using all those connections from one PC. Device licensing lets such users consume one database license and the number of connections for which they are licensed, up to ten, to the server from a single PC.

Device Licensing RequirementsDevice 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.

5-4


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 be combined.

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

Directly invoking the database on a systemTTY serial line

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

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

Multiple-Tier ConnectionsMultiple-tier connections are client applications that connect from a PC to a database server either through one or more different PCs, or through an application server component. Examples of multiple-tier connections are:

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 server system. The application server connects to the database server.



Using Device SubkeysEach 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 component consumes a separate license. But each of these PCs, at one or more removes from the server, can have up to ten connections.

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

5-6

:\ProgMarch


6Chapter

ram Fi5 2010


The U2 SSL Configuration Editor

About SSL Property Lists . . . . . . . . . . . . . . . . 6-4 List Encryption . . . . . . . . . . . . . . . . . . 6-4 Working with SSL Property Lists . . . . . . . . . . . . 6-4 Loading and Decrypting an SSL Property List . . . . . . . . 6-5 SSL Properties . . . . . . . . . . . . . . . . . . 6-5Starting the U2 SSL Configuration Editor . . . . . . . . . . . 6-13Creating a New SSL Property List . . . . . . . . . . . . . 6-16Editing an Existing SSL Property List . . . . . . . . . . . . 6-29Deleting an SSL Property List . . . . . . . . . . . . . . 6-40Copying an SSL Property List . . . . . . . . . . . . . . 6-41Renaming an SSL Property List . . . . . . . . . . . . . . 6-44Using the Trace Feature . . . . . . . . . . . . . . . . 6-46Using the Console/Problems View . . . . . . . . . . . . . 6-47



At version 7.2, UniData supports the ability of client applications to make secure connections to the database server through Secure Sockets Layer (SSL). SSL is a transport layer protocol that provides a secure channel between two communicating programs over which application data can be transmitted securely. It is the most widely implemented security protocol on the World Wide Web.

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

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

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

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

Create a new SSL property listEdit an existing SSL property listDelete an SSL property listCopy an SSL property listRename an SSL property list

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

1-2

C:\Program Files\Adobe\FrameMaker8\UniData 7.2\7.2rebranded\APISUPP\Ch6.fm3/5/10

About SSL Property ListsAn SSL property list is an ASCII text file that stores the properties for a secure connection. These properties 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 the location of a certificate authority (CA) certificate. For this reason, it is saved in encrypted form to the Windows Registry at:

HKEY_LOCAL_MACHINE/SOFTWARE/IBM/UniDK/SPL

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

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

For increased security, we strongly recommend that you assign your own password to the SSL property list. In this case, the same IBM algorithm uses your unique password as the seed for generating an encryption key. The resulting encryption key is unique, so only users who know the password can access 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 U2 SSL Configuration Editor to create, modify, or delete the property list; this ensures that the list is properly saved 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 and decrypted. After the list has been decrypted, it is supplied in plain text form to a function that handles the SSL handshake.

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

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

propertyName=propertyValue

SSL PropertiesThis section describes each property supported in the SSL property list to define the characteristics and behaviors of a secure connection.

SSLVersion={SSLv3 | TLSv1}

Optional. Default is SSLv3.

This property specifies the preferred protocol version.

Protocol Versions

Version Description

SSLv3 This is most widely used protocol.

TLSv1 This is the newer protocol. Most newer applications support it, but some older applications may not.

1-4


CertificateStoreType={U2 | Windows}

Optional. Default is U2.

This property specifies the type of certificate stores to be used for all certificates issued for the secure connection.

Certificate Store Types

Value Description

U2 All certificates specified in this file are PEM or DER–format OS-level files.

Windows All certificates specified in this file are looked up from the native Windows certificate store. Generally, a CA certificate is looked up from Windows CA and ROOT stores, while MyCertificate is looked up from MY stores.In Microsoft’s terminology, these certificate stores are system stores: a collection of physical certificate stores that reside in the Windows Registry. UniData 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 a semicolon (;) as shown above. Specifying multiple CACertificate properties is allowed.

U2 certificate store type

<cert-path> is the path of the certificate file that is used as a CA certificate. The format of the certificate can be either PEM or DER. (However, see the CertificatePath property for additional information on how U2 loads certificates when performing the SSL handshake.) With the U2 type, if a CA certificate chain is required, you have the choice of specifying multiple CACertificate properties, 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 type

Specify 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, which should be the most immediate CA certificate (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 above description is based on the assumption that a correct and complete trust relationship exists in the Windows certificate store for the certificate involved. If a complete chain cannot be formed, an error is reported. 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.

U2 certificate store type

Note that if you specify this property, you must also specify the MyPrivateKey and PrivateKeyPassword properties. The format of the certificate can be either PEM or DER.

Windows certificate store type

Specify the same “friendly name” or “Common name” that is used for the certificate in the certificate store. Note that when you import a Windows store type certificate to the MY store, you must associate an 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 My Certificate.

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

1-6


When an SSL property list is created, the private key is loaded into memory and validated against its corresponding certificate (My Certificate). If it passes validation, the key is stored with the SSL property list. This validation feature is designed 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 the private key file on your hard disk. You can store the key file safely on offline media until the next time you want to edit the SSL property list.


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.


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 of certificates revoked by CA. If an incoming server certificate is specified, it is checked against the CRL to verify that it has not been revoked before other verification is performed.

The format of the CRL can be PEM or DER.

AuthenticationDepth=<level>

Optional. Default is 5.

This property determines the level at which to stop UniData’s verification process in authentication processing. The default setting of 5 is a sufficient depth in most cases. If you set the depth for fewer levels of authentication 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 UniData that it needs to perform additional checking in authenticating the incoming certificate. If you do not specify TrustedPeerName, the incoming certificate is considered valid when the CA certificate has verified it. However, if you specify TrustedPeerName, a further check is performed to verify that the incoming certificate’s SubjectAltName extension or CommonName subject field matches one of the specified TrustedPeerName.

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

% Match any character strings

_ Match one character

For example, %@us.xyz.com matches both [email protected] and [email protected], while [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.

1-8


Peer name checking (if specified) is performed.

GENEROUS authentication requires only the following:

The incoming server certificate is a well-formed X.509 certificate.Peer name checking (if specified) is performed.

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

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

Applicable to U2 certificate store type only. Optional. Default is PATH:C:/IBM/UniDK/certs.

When you specify a certificate by the CACertificate, MyCertificate, or CRL property, the value for that property is registered internally. When loading the certificate into memory to establish an SSL connection, UniData uses this registered path by default to retrieve the certificate.

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

Four options are available:

Option Description

DEFAULT Specifies the above-described behavior. This option is the default.

RELATIVE UniData looks for the certificate in the current directory under which the client process is running.

CertificatePath Options



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 SSL handshake. It asks the client to send its certificate.

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

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 SSL operations. The directory should be specfied 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 control where the random data is stored (for example, to limit users’ access to the random data by storing it in a directory that has restricted permissions), you should use this property to specify the desired directory.

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 default path is C:\IBM\UniDK\certs. With this path, the behavior is the same as that of the DEFAULT option.

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

Option Description

CertificatePath Options (Continued)

1-10


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



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

To start the U2 SSL Configuration Editor:

From the Start menu, choose Programs ? IBM U2 ? UniData Tools ? SSL Config Editor. The U2 SSL Configuration Editor window appears.

Components of this window are described below.

1-12


Main MenuAt the top of the U2 SSL Configuration Editor window are four menus:

U2 SSL Configuration Editor Main Menu

Menu Description

File Options for opening, closing, saving, printing, and performing other tasks for managing SSL property lists.

Edit Options for performing standard Windows file edit actions, including undo, redo, cut, copy, paste, and delete.

Window Options for controlling the view and navigation of panes in the U2 SSL Configuration Editor window.

Help Options for accessing help.

Shortcut ToolbarUnder the main menu is a toolbar with shortcuts for the most common tasks. Roll the mouse over a shortcut tool to see a brief description of the task.



PanesThe U2 SSL Configuration Editor window is divided into three panes:

U2 SSL Configuration Editor: Main Window Panes

Pane Usage

U2 SSL Property Explorer (left)

Use this pane to view the directory structure of SSL property lists and copy, rename, or delete existing SSL property lists.

Editor view (upper right)

This pane contains a Welcome tab with information about using the U2 SSL Configuration Editor.

Console/Problems view (lower right)

This pane contains two tabs:Console for viewing error and informational messages and a log of transactions performed in Trace mode.Problems for details on any problems encountered while creating, editing, deleting, or performing other operations on an SSL property list.

From the main window, you can perform the following tasks to manage SSL property lists:

Creating a New SSL Property ListEditing an Existing SSL Property ListDeleting an SSL Property ListCopying an SSL Property ListRenaming an SSL Property ListUsing the Trace FeatureUsing the Console/Problems View

1-14


Creating a New SSL Property ListThis section takes you through the process of creating an SSL property list, defining all the properties of a secure connection.

The Create a New U2 SSL Property List dialog box provides a form for entering these properties, helping you input the required information. The requirements are based on whether the SSL property list is for the use of a client or a server, and on the certificate store type.

The properties are grouped on three pages of the dialog box. The instructions for creating a new SSL property list are broken down into tasks, with one task for each page of the dialog box:

Task 1: Assign name, password, SSL version, and store type to property listTask 2: Specify certificates, private key and password, certificate revocation list, and cipher suitesTask 3: Specify authentication properties



Task 1: Assign name, password, SSL version, and store type to property list

1. In the U2 SSL Configuration Editor window, select File ? New. The Create a New SSL Property List dialog box appears.

On the SSL Property List Name, Password, SSL Version, and Store Type page of this dialog box, you define the basic properties of the SSL property list.

2. In the Property list name box, enter a unique name for the SSL property list to be created.

1-16


3. Optional. We strongly recommend that you establish a password for the SSL property list. An IBM algorithm is applied to your password to derive a unique encryption key for the list. To access a password-protected list, users must enter the password as the key to decrypt the list and view its plaintext contents. If you do not assign a password to the list, the algorithm uses a fixed internal default password to generate the encryption key. The key produced in this manner never varies and anyone who uses the U2 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 limitations on length or restrictions on characters allowed; however, the length of the password and randomness of the characters contribute to its relative security. Use a password that is difficult to guess 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-enter password box, type the same password again.

5. UniData supports SSL version 3 and TLS version 1. Under SSL version, select the version of the protocol to be used for this secure connection:

SSL Versions

Option Description

SSLv3 This is the default setting. It is the most widely used protocol.

TLSv1 This is the newer protocol. Most newer applications support it, but some older applications may not.



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

Certificate Store Type

Option Description

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

Windows All certificates for this connection are looked up from the native Windows certificate store. Generally, a CA certificate is looked up from Windows CA and ROOT stores, while My Certificate is looked up from MY stores.In Microsoft’s terminology, these certificate stores are system stores: a collection of physical certificate stores that reside in the Windows Registry. UniData looks up these stores from both of the following Registry locations:? CERT_SYSTEM_STORE_CURRENT_USER

? CERT_SYSTEM_STORE_LOCAL_MACHINE

1-18


7. Choose one of the following actions:To discard your entries and cancel the process of creating an SSL property list, click Cancel.Otherwise, to continue defining properties of the new SSL property list, click Next.The Certificates, Private Key and Password, CRL, and Cipher Suites page of the Create a New SSL Property List dialog box appears.

On this page of the dialog box, you specify the path of a certificate, set the private key and password if applicable, specify the path of the certificate revocation list (CRL), and specify cipher suites to be used in the handshake.



Task 2: Specify certificates, private key and password, certificate revocation list, and cipher suites

1. 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 the certificate store type below.

U2 certificate store type:Specify the path of the certificate file that is used as a CA certificate. The format of the certificate can be either PEM or DER. With the U2 type, you can specify multiple certificate paths, separating each with a semicolon (;).If a CA certificate chain is required, you have the choice of specifying multiple certificate files in the CA certificate 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 type:Specify 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 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 above description is based on the assumption that a correct and complete trust relationship exists in the Windows certificate store for the certificate involved. If a complete chain cannot be formed, an error is reported. This also applies to other certificate-related properties.

2. Optional for a client SSL property list; required for a server SSL property list. In the My Certificate box, enter the path for your certificate for this secure connection, or click Browse to find the path. See specifics for the certificate store type below.

U2 certificate store type:Note that if you specify a path in My Certificate for a server SSL property list, you must also enter values for Private key and Private key password. The format of the certificate can be either PEM or DER.

1-20


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

3. 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 My Certificate, or click Browse to find the path. The format of the key file can be either PEM or DER.When an SSL property list is created, the private key is loaded into memory and validated against its corresponding certificate (My Certificate). If it passes validation, the key is stored with the SSL property list. This validation feature is designed 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 the private key file on your hard drive. You can store the key file safely on external media until the next time you want to modify properties of the SSL property list.

4. 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.

5. Optional. In the CRL box, enter the path of a certificate revocation list (CRL) to be used for this 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 serial numbers 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 other verification is performed.The format of the CRL can be either PEM or DER.



6. Optional. In the Cipher Suites box, 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 the OpenSSL open source library applies.For further details, see the description of addCipherSuite() in the UniBasic Extensions manual.

7. 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 continue defining properties of the new SSL property list, click Next.

1-22


The Authentication Properties page of the Create a New SSL Prop-erty List dialog box appears.

On this page of the dialog box, you specify properties related to peer authentication for the secure connection.



Task 3: Specify authentication properties

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

% Match any character string


For example, %@us.xyz.com matches both [email protected] and [email protected], while [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 UniData stores random data for the use of SSL opera-tions, or click Browse to find the path. For example, D:\mysys\work is an absolute path. The directory must currently exist 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 limit users’ access to the random data by storing it in a directory that has restricted permissions), use this property to specify the desired directory.When the SSL property list is created, the random data file named U2SSL.rnd is created in the directory specified here.

3. Optional. In the Authentication depth list, select the level at which to stop UniData’s verification process in authentication processing. The default setting is 5, which is a sufficient depth in most cases. If you set the authen-tication depth for fewer levels of authentication than actually employed for the certificate, the certificate will not pass authentication.

1-24


4. Applicable to a server SSL property list only. Optional.Under Client authentication, if the SSL server using this property list requires client authentication during the SSL handshake, select the Require client authentication check box. A server that requires client authentication asks the client to send its certificate as an additional security measure.If you select this check box, UniData treats the SSL property list as a server property list. For a server property list, you must also specify these properties:

CA certificateMy CertificatePrivate key (U2 certificate store type only)Private key password (U2 certificate store type only)

If you leave a required property blank, the U2 SSL Configuration Editor issues an error message after you click Finish, and redisplays the first page on which you to need to enter missing information.

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

Authentication Strength

Option Description

Strict This is the default setting. Strict authentication requires that the following conditions be met:? 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 Generous authentication requires only that the incoming server certificate is a well-formed X.509 certificate.

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



6. Applicable to U2 certificate store type only. Optional.When you specify a certificate by the CA certificate, My Certificate, or CRL property, the value for that property is registered internally. When the certificate is loaded into memory to establish an SSL connection, UniData uses this registered path by default to retrieve the certificate.The Certificate path property allows you to specify different locations in which to search the certificates. Note that this property applies to all certificates in the file.Under Certificate path, select one of the following options:

Certificate Path Options

Option Description

Default Specifies the above-described behavior.

Relative UniData 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 or a relative path.The default path is C:\IBM\UniDK\certs. With this path, the behavior is the same as that of the Default option.

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

1-26


7. 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 U2 SSL Configuration Editor tool checks your entries to ensure that you have input all required properties. The requirements are based on whether this is a client or server SSL property list, and on the selected certificate store type.If you left a required property blank or entered conflicting or inconsistent values in related properties, when you click Finish the U2 SSL Configuration Editor issues an error message and redisplays 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 encrypted form to the Windows Registry at:HKEY_LOCAL_MACHINE/SOFTWARE/IBM/UniDK/SPL



Editing an Existing SSL Property ListThis section takes you through the process of editing an existing SSL property list, changing the properties of a secure connection.

To edit an existing SSL property list:

1. In the U2 SSL Configuration Editor window, open the U2 SSL Property Explorer pane if it is not already displayed. To open this pane, choose Window ? Show View ? U2 SSL Property Explorer.

2. In the U2 SSL Property Explorer pane, double-click the name of the SSL property list to be edited. The Property List Password dialog box appears.

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.

Note: If the SSL property list does not have an associated password, you can rename the list and enter a password during this process. For instructions, see “Renaming an SSL Property List” on page 43.

The SSL property list opens in the Editor view in the upper right pane of the U2 SSL Configuration Editor window.

The Editor view is split into two components: the Property List on the left side and the Property Editor on the right.

1-28


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

Property Editor

Element Description

Property Display only. This box contains the name of the property as it is stored in the U2 SSL 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 table lists properties in the order in which they appear in the Property List on the left side of the Editor view.

Property Value

SSLVersion UniData supports SSL version 3 and TLS version 1. Select the version of the protocol to 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, but some older applications may not.

To apply this change, click OK.

Editing Property Values



CertificateStoreType Select 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 or DER format OS-level files.

? Windows – All certificates for this connection are looked up from the native Windows certificate store. Generally, a CA certificate is looked up from Windows CA and ROOT stores, while My Certif-icate is looked up from MY stores.

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


Property Value

Editing Property Values (Continued)

1-30


CACertificate 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 the certificate store type below.

U2 certificate store type:Specify the path of the certificate file that is used as a CA certificate. The format of the certificate can be either PEM or DER. With the U2 type, you can specify multiple certificate paths, separating each with a semicolon (;).If a CA certificate chain is required, you have the choice of specifying multiple certificate files, 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 type:Specify the same “friendly name” or “Common name” that is used for the certificate in the certificate store. With the Windows type, specify only one certif-icate path, generally the most immediate CA certificate (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 above description is based on the assumption that a correct and complete trust relationship exists in the Windows certificate store for the certificate 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.

Property Value




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 to find 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, you must also enter values for MyPrivateKey and PrivateKeyPassword. The format of the certificate can be either PEM or DER.

Windows certificate store type:Specify the same “friendly name” or “Common name” that is used for the certificate in the certificate store. Note that when you import a Windows store type certificate into the MY store, you must associate an exportable private key with it by selecting the Exportable private key check box.To apply this change, click OK.

MyPrivateKey Applicable to the U2 certificate store type only. Required if you entered a value in MyCertificate.Enter the path for the file that contains the private key associated with My Certificate, or click Browse to find the path. The format of the key file can be either PEM or DER.When an SSL property list is created, the private key is loaded into memory and validated against its corre-sponding certificate (My Certificate). If it passes validation, the key is stored with the SSL property list. This validation feature is designed 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 the private key file in memory. You can store the key file safely on media until the next time you want to modify properties of the SSL property listTo apply this change, click OK.

Property Value


1-32


PrivateKeyPassword Applicable 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.

TrustedPeerName Optional. Enter the name of a trusted peer as detailed below. This property tells UniData that additional checking needs to be performed in authenticating the incoming certificate. If you leave this box blank, the incoming certificate is considered valid when the CA certificate has verified it. However, if you specify a trusted peer name, a further check is performed to verify that the incoming certificate’s SubjectAltName extension or CommonName subject field matches that of the trusted peer.The trusted peer name can be either a fully specified name (such as [email protected]) or a wildcard name. Two wildcard characters are supported:

% Match any character string


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

Property Value




AuthenticationStrength Optional. Select the appropriate authentication strength option for this secure connection:? STRICT – This is the default setting. Strict authen-

tication requires that the following conditions be met:

– 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 – This strength requires only that the incoming server certificate is a well-formed X.509 certificate. Note that generous authentication is not highly secure. We recommend its use in test environments only.


Property Value


1-34


CertificatePath Applicable to U2 certificate store type only. Optional.When you specify a certificate by the CACertificate, MyCertificate, or CRL property, the value for that property is registered internally. When the certificate is loaded into memory to establish an SSL connection, UniData uses this registered path by default to retrieve the certificate.The CertificatePath property allows you to specify different locations in which to search the certificates. Note that this property applies to all certificates in the file. Select one of the following options:? DEFAULT – Specifies the above-described

behavior.

? RELATIVE – UniData looks for the certificate in the current directory under which the client process is running.

? ENV – Enter an environment variable name. With this option, the value of the environment variable is used as the path in which to load the certificates. Note that UniData looks up the environment variable for a client process only the first time the process makes an SSL connection; the value of 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 a relative path. The default path is C:\IBM\UniDK\certs. With this path, the behavior is the same as that of the Default option.


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 the OpenSSL open source library applies.To apply this change, click OK.

Property Value




AuthenticationDepth Optional. Enter the level at which to stop UniData’s verification process in authentication processing. The default setting is 5, which is a sufficient depth in most cases. If you specify a depth with fewer levels of authentication than actually employed for the certificate, the certificate will not pass authentication.To apply this change, click OK.

CRL Optional. Enter the path of a certificate revocation list (CRL) to be used for this 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 serial numbers 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 other verification is performed.The format of the CRL can be either PEM or DER.To apply this change, click OK.

Property Value


1-36


ClientAuthentication Applicable to a server SSL property list only. Select the appropriate option for this secure connection:? true – Use this setting if the SSL server using this

property list requires client authentication during the SSL handshake. A server that requires client authentication asks the client to send its certificate as an additional security measure.

If you select true, UniData treats the SSL property list as a server property list. For a server property list, you must also specify these properties:– CACertificate– MyCertificate– MyPrivateKey (U2 certificate store type only)– PrivateKeyPassword (U2 certificate store type only)If you leave a required property blank, the U2 SSL Configuration Editor issues an error message after you click Finish, and redisplays the first page on which you to need to enter missing information.

? false – Use this setting if the SSL server does not require client authentication.


Property Value




5. When you have finished making changes to the properties in this SSL property list, take one of the following actions:

To save your changes to the list, click the Save button in the Property List panel.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 appears. Enter a unique name for the new list, enter a password, and re-enter the password. Click OK.

RandomFileLocation Optional. Enter the absolute path of the directory in which UniData stores 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. 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 limit users’ access to the random data by storing it in a directory that has restricted permissions), use this property to specify the desired directory.When the SSL property list is created, the random data file named U2SSL.rnd is created in the directory specified here.To apply this change, click OK.

Property Value


1-38


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

To delete an SSL property list:


2. In the U2 SSL Property Explorer pane, select the SSL property list to be deleted.

3. Click the X button. The Property List Password dialog box appears.4. 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.

5. The Please Confirm dialog box appears. The message states that you are about to delete an SSL property list and requests your confirmation to proceed.If you want to cancel the deletion, click Cancel.Otherwise, if you want to complete the procedure and delete the SSL prop-erty 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 a new list from an existing list.

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 by the original list.Rename an existing list and assign it a password – If an existing list has no password or you want to change its password, you can use this function to rename the list and assign a new password. You can then delete the original list if it is no longer needed.

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

To copy an SSL property list:


2. In the U2 SSL Property Explorer pane, right-click the SSL property list to be copied.

3. Select the Copy option.The Property List Password dialog box appears.

1-40


4. 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, leave the box blank and click OK.The Console displays the message “List ‘listname’ has been copied successfully.”

Otherwise, to cancel the copy procedure, click Cancel.5. The next task is to paste the copied list in the folder. In the U2 SSL Property

Explorer pane, right-click the U2 SSL Property Lists folder.6. Select the Paste option. The Property List Name and Password dialog

box appears.

7. In the Enter name for new property list box, the system-generated name for the new list is highlighted. Enter a unique name for the new list.

8. Optional. 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 the SSL property list.

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



10. Take one of the following actions:To paste the new list into the selected folder, click OK.The Console displays the message “New list has been created successfully.”To cancel the paste procedure, click Cancel.

1-42


Renaming an SSL Property ListThis section provides instructions for renaming an SSL property list. The rename function allows you to 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 U2 SSL Configu-ration Editor. You must use this tool so the list is entered properly in the Registry.

To rename an SSL property list:


2. In the U2 SSL Property Explorer pane, right-click the SSL property list to be renamed.

3. Select the Rename option.The Property List Name and Password dialog box appears.

4. In the Enter name for new property list box, enter a unique name for the list.



5. 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, leave the 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.

1-44


Using the Trace FeatureThe U2 SSL Configuration Editor provides a Trace feature for recording all operations performed through the tool on SSL property lists. The events of these operations are written to a file named U2SSLConfig.log and also displayed in the Console pane.

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

The log is located by default in your C:\temp folder. If you have no \temp folder, the log is written to the \tmp folder. If no \tmp folder exists, the program creates a \temp folder. The file name for the log cannot be changed.

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

To use the Trace feature:

1. In the U2 SSL Configuration Editor window, choose File.2. If the Trace option is not check-marked, select it.

When Trace mode is active, the Trace option is preceded by a check mark on the menu.

3. With Trace mode turned on, perform operations on SSL property lists as you normally would. The events 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.



Using the Console/Problems ViewThe lower right pane of the U2 SSL Configuration Editor window provides two views that help you manage the tasks performed on SSL property lists:

Console for viewing error/informational messages and a log of transactions performed in Trace mode.Problems for details on any problems encountered while creating, editing, deleting, or performing other transactions on SSL property lists.

You can switch back and forth from Console view to Problems view, or close and open a view as needed.

To use the Console view:

1. In the U2 SSL Configuration Editor window, open the Console view if it is not already displayed. To open this view, choose Window ? Show View ? Console.

2. Optional. If you want to keep a log of transactions performed on SSL property lists, turn on Trace mode. If you need instructions, see “Using the Trace Feature” on page 45.

1-46


3. Perform transactions on SSL property lists as you normally would. Messages and results from these transactions are displayed in the Console.If Trace mode is active, a log of transactions is displayed in the Console.

4. To close this view, click X on the Console tab.

To use the Problems view:

5. In the U2 SSL Configuration Editor window, open the Problems view if it is not already displayed. To open this view, choose Window ? Show View ? Problems.

6. Perform transactions on SSL property lists as you normally would. The details of any problems encountered are displayed in the Problems view.

Column Description

Description A description of a problem encountered while performing transactions on an SSL property list. Each problem is listed on a separate line.

Details in Problems View



7. To close this view, click X on the Problems tab.

Resource The name of the file that stores messages regarding the problem.

<MSG_PRBL_HOLDER> The folder that contains the file with messages about the problem.

Location The path of the message file for the problem.

Column Description

Details in Problems View

1-48

Date post:	07-Jul-2020
Category:	Documents
Upload:	others
View:	8 times
Download:	1 times

Administrative Supplement for Client APIs · : Describes Using the IBM JDBC Driver for UniData and...

Documents