GC32 9342 00

Administrator’s Guide
PathWAI™ Secure for WebSphere MQ
Version 300
GC32-9342-00
January 2003
Candle Corporation
100 North Sepulveda Blvd
El Segundo, California 90245
Registered trademarks and service marks of Candle Corporation: AF/OPERATOR, AF/PERFORMER, AF/REMOTE,
Availability Command Center, Candle, Candle Command Center, Candle Direct logo, Candle Electronic Customer Support, Candle
logo, Candle Management Server, Candle Management Workstation, CandleNet Portal, Candle Technologies, CL/CONFERENCE,
CL/SUPERSESSION, CommandWatch, CandleNet Command Center, CT, CT/Data Server, CT/DS, DELTAMON, eBA,
eBA*ServiceMonitor, eBA*ServiceNetwork, eBusiness Assurance, eBusiness Institute, ETEWatch, IntelliWatch, IntelliWatch Pinnacle,
MQSecure, MQView, OMEGACENTER, OMEGAMON, OMEGAMON/e, OMEGAMON II, OMEGAMON Monitoring Agent,
OMEGAVIEW, OMEGAVIEW II, PQEdit, Solutions for Networked Applications, Solutions for Networked Businesses, and Transplex.
Trademarks and service marks of Candle Corporation: Alert Adapter, Alert Adapter Plus, Alert Emitter, AMS, Amsys,
AutoBridge, AUTOMATED FACILITIES, Availability Management Systems, Candle Alert, Candle Business Partner Logo, Candle
Command Center/SentinelManager, Candle CommandPro, Candle CIRCUIT, Candle eDelivery, CandleLight, CandleNet, CandleNet
2000, CandleNet eBP, CandleNet eBP Access, CandleNet eBP Administrator, CandleNet eBP Broker Access, CandleNet eBP
Configuration, CandleNet eBP Connector, CandleNet eBP File Transfer, CandleNet eBP Host Connect, CandleNet eBP Object Access,
CandleNet eBP Object Browser, CandleNet eBP Secure Access, CandleNet eBP Service Directory, CandleNet eBP Universal
Connector, CandleNet eBP Workflow Access, CandleNet eBusiness Assurance, CandleNet eBusiness Exchange, CandleNet eBusiness
Platform, CandleNet eBusiness Platform Administrator, CandleNet eBusiness Platform Connector, CandleNet eBusiness Platform
Connectors, CandleNet eBusiness Platform Powered by Roma Technology, CandleNet eBusiness Platform Service Directory, CCC,
CCP, CEBA, CECS, CICAT, CL/ENGINE, CL/GATEWAY, CL/TECHNOLOGY, CMS, CMW, Command & Control, Connect-Notes,
Connect-Two, CSA ANALYZER, CT/ALS, CT/Application Logic Services, CT/DCS, CT/Distributed Computing Services, CT/Engine,
CT/Implementation Services, CT/IX, CT/Workbench, CT/Workstation Server, CT/WS, !DB Logo, !DB/DASD, !DB/EXPLAIN,
!DB/MIGRATOR, !DB/QUICKCHANGE, !DB/QUICKCOMPARE, !DB/SMU, !DB/Tools, !DB/WORKBENCH, Design Network, DEXAN,
e2e, eBAA, eBAAuditor, eBAN, eBANetwork, eBAAPractice, eBP, eBusiness Assurance Network, eBusiness at the speed of light,
eBusiness at the speed of light logo, eBusiness Exchange, eBusiness Institute, eBX, End-to-End, ENTERPRISE, Enterprise Candle
Command Center, Enterprise Candle Management Workstation, Enterprise Reporter Plus, EPILOG, ER+, ERPNet, ESRA, ETEWatch
Customizer, HostBridge, InterFlow, Candle InterFlow, Lava Console, MessageMate, Messaging Mastered, Millennium Management
Blueprint, MMNA, MQADMIN, MQEdit, MQEXPERT, MQMON, NBX, NetGlue, NetGlue Extra, NetMirror, NetScheduler, OMA, OMC
Gateway, OMC Status Manager, OMEGACENTER Bridge, OMEGACENTER Gateway, OMEGACENTER Status Manager,
OMEGAMON Management Center, OSM, PC COMPANION, Performance Pac, PowerQ, PQConfiguration, PQScope, Response Time
Network, Roma, Roma Application Manager, Roma Broker, Roma BSP, Roma Connector, Roma Developer, Roma FS/A, Roma
FS/Access, RomaNet, Roma Network, Roma Object Access, Roma Secure, Roma WF/Access, Roma Workflow Access, RTA, RTN,
SentinelManager, Somerset, Somerset Systems, Status Monitor, The Millennium Alliance, The Millennium Alliance logo, The
Millennium Management Network Alliance, TMA2000, Tracer, Unified Directory Services, Volcano and ZCopy.
Trademarks and registered trademarks of other companies: AIX, DB2, MQSeries and WebSphere are registered trademarks of
International Business Machines Corporation. SAP is a registered trademark and R/3 is a trademark of SAP AG. UNIX is a registered
trademark in the U.S. and other countries, licensed exclusively through X/Open Company Ltd. HP-UX is a trademark of
Hewlett-Packard Company. SunOS is a trademark of Sun Microsystems, Inc. All other company and product names used herein are
trademarks or registered trademarks of their respective companies.
Copyright © October 2002, Candle Corporation, a California corporation. All rights reserved. International rights secured.
Threaded Environment for AS/400, Patent No. 5,504,898; Data Server with Data Probes Employing Predicate Tests in Rule Statements
(Event Driven Sampling), Patent No. 5,615,359; MVS/ESA Message Transport System Using the XCF Coupling Facility, Patent No.
5,754,856; Intelligent Remote Agent for Computer Performance Monitoring, Patent No. 5,781,703; Data Server with Event Driven
Sampling, Patent No. 5,809,238; Threaded Environment for Computer Systems Without Native Threading Support, Patent No.
5,835,763; Object Procedure Messaging Facility, Patent No. 5,848,234; End-to-End Response Time Measurement for Computer
Programs, Patent No. 5,991,705; Communications on a Network, Patent Pending; Improved Message Queuing Based Network
Computing Architecture, Patent Pending; User Interface for System Management Applications, Patent Pending.
NOTICE: This documentation is provided with RESTRICTED RIGHTS. Use, duplication, or disclosure by the Government is subject to
restrictions set forth in the applicable license agreement and/or the applicable government rights clause.
This documentation contains confidential, proprietary information of Candle Corporation that is licensed for your internal use only.
Any unauthorized use, duplication, or disclosure is unlawful.
2 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

Contents
List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
List of Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Chapter 1. Introducing PathWAI Secure for WebSphere MQ . . . . . . . . . . . 23

What is PathWAI Secure? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
What is Public Key Cryptography? . . . . . . . . . . . . . . . . . . . . . . . . . . 26
How Does PathWAI Secure Work? . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Chapter 2. Configuring Key and Encryption Options . . . . . . . . . . . . . . . . . 37

Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
LDAP Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Hardware Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Symmetric Encryption Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Asymmetric Key Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Hashing Algorithms for Digital Signatures . . . . . . . . . . . . . . . . . . . . . 57
PathWAI Secure ID Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Certificate Revocation List Checking . . . . . . . . . . . . . . . . . . . . . . . . . 64
Online Certificate Revocation Checking . . . . . . . . . . . . . . . . . . . . . . 67
Triple Prime Key Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Message-Embedded Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Queue Authorization using PathWAI Secure Sender ID . . . . . . . . . . . 85
Symmetric Key Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Chapter 3. Managing Users and User Keys. . . . . . . . . . . . . . . . . . . . . . . . . 91

Managing Users and Keys in the PathWAI Secure Environment. . . . . 92
Users, User IDs, and Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Contents 3
Contents
Registering a Global Administrator . . . . . . . . . . . . . . . . . . . . . . . . . 104

Registering Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Registering Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Distributing Public Keys and Certificates . . . . . . . . . . . . . . . . . . . . . 117
Revoking Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Managing the Local User Key Databases . . . . . . . . . . . . . . . . . . . . . 131
Chapter 4. Managing the Candle LDAP Repository . . . . . . . . . . . . . . . . . 135

Using an LDAP Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Managing the LDAP Repository on Windows NT . . . . . . . . . . . . . . 137
Managing the LDAP Repository on UNIX . . . . . . . . . . . . . . . . . . . . 141
Chapter 5. Securing WebSphere MQ Messages Using Channel Exits . . . . 147

Securing Messages Using PathWAI Secure Channel Exits . . . . . . . . 148
Setting Channel Exit Definition Parameters . . . . . . . . . . . . . . . . . . . 151
Securing Autodefined Cluster Sender Channels. . . . . . . . . . . . . . . . 155
Appendixes
Appendix A. CASP Secure Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

About CASP Secure Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Using MQSecure Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Configuring MQSecure Connection Using Secure Side Files . . . . . . 170
Configuring MQSecure Connection Programmatically. . . . . . . . . . . 173
Usage Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
Appendix B. Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Administrative Utilities for Distributed Systems . . . . . . . . . . . . . . . . 189
Administrative Utility for OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Public Key Monitor for Distributed Systems . . . . . . . . . . . . . . . . . . . 204
Public Key Monitor for OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Validation Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Database Conversion Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

Contents
Appendix C. Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

PathWAI Secure–LDAP Connection . . . . . . . . . . . . . . . . . . . . . . . . 214
PathWAI Secure Hardware Crypto Interface . . . . . . . . . . . . . . . . . . 215
Transmission Failures in OS/390 Client Connections . . . . . . . . . . . . 219
UNIX Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Appendix D. Messages and Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 221

PathWAI Secure Messages and Return Codes . . . . . . . . . . . . . . . . . 222
BSAFE Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Appendix E. Guide to Candle Customer Support . . . . . . . . . . . . . . . . . . . . 247

Base Maintenance Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
Enhanced Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Customer Support Contact Information. . . . . . . . . . . . . . . . . . . . . . 254
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Contents 5
Contents

List of Figures
FIGURE 1. Symmetric and Asymmetric Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

FIGURE 2. Encrypting and Decrypting a Message with Public/Private Keys . . . . . 28
FIGURE 3. Digital Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
FIGURE 4. Using a Digital Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
FIGURE 5. PathWAI Secure Configuration Tool for Windows . . . . . . . . . . . . . . . 40
FIGURE 6. mqs_adm Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
FIGURE 7. KMFADM Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
FIGURE 8. The Windows LDAP Configuration Utility . . . . . . . . . . . . . . . . . . . . 140
FIGURE 9. UNIX Cluster Sender Channel Definition Based on
OS/390 Cluster Receiver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
FIGURE 10. CASP Secure Connector Operation. . . . . . . . . . . . . . . . . . . . . . . . . 163
FIGURE 11. Business Flow Using Put Only and Get Only Security . . . . . . . . . . . 164
FIGURE 12. Specifying CASP Secure Connector in the Directory Administrator . 169
FIGURE 13. Extract From C Example Program Showing Usage of Functions . . . 178
FIGURE 14. Securing a Partially-exposed Environment. . . . . . . . . . . . . . . . . . . . 185
FIGURE 15. Sample Command File cmdline.bat. . . . . . . . . . . . . . . . . . . . . . . . . 201
FIGURE 16. KMFADM Main Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
FIGURE 17. Sample JCL for Validation Programs . . . . . . . . . . . . . . . . . . . . . . . . 209
List of Figures 7
List of Figures

List of Tables
Table 1. Cryptographic Algorithms by Strength . . . . . . . . . . . . . . . . . . . . . . . . 50

Table 2. Cryptographic Algorithms by Throughput . . . . . . . . . . . . . . . . . . . . . 50
Table 3. X.509 Certificate Subject Name AVAs . . . . . . . . . . . . . . . . . . . . . . . . 60
Table 4. Symmetric Key Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Table 5. Channel Exit Definition Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 149
Table 6. Conversion of Channel Exit Names Using CHADEXIT . . . . . . . . . . 155
Table 7. Parameters for mqs_adm and mqs_admc . . . . . . . . . . . . . . . . . . . . 190
List of Tables 9
List of Tables
10 PathWAI™ Secure for WebSphere MQ Administrator’s Guide, Version 300

Preface
P
This is a guide for administrators of PathWAI™ Secure for WebSphere MQ, a
product that provides both node-to-node and application-to-application
security for WebSphere MQ networks and, via the CASP Secure Connector,
for CandleNet eBusiness Platform (eBP) or Candle Application Services Pac
(CASP) applications.
This guide provides a general introduction to PathWAI Secure, covers
PathWAI Secure adminstrative tasks, and details how to configure WebSphere
MQ channels to invoke PathWAI Secure security functions. It also documents
CASP Secure Connector, which allows eBP or CASP applications to invoke
PathWAI Secure as an inline service rather than using its APIs.
Who should read this book?

This guide is intended for individuals responsible for performing PathWAI
Secure administrative functions such as registering or revoking users and
distributing keys. It is also intended for WebSphere MQ administrators who
will be configuring WebSphere MQ channel exits to invoke PathWAI Secure
services.
It assumes that WebSphere MQ is already installed. If you are using CASP
Secure Connector, you must also have CandleNet eBP or CASP installed.
How this book is organized

n Chapter 1 introduces you to PathWAI Secure. It describes the security
services PathWAI Secure offers, provides a high-level view of public key
cryptography, and describes how it is implemented in PathWAI Secure.
Preface 11
n Chapter 2 describes PathWAI Secure’s user key and encryption options
and provides detailed instructions for configuring them.
n Chapter 3 covers the management of PathWAI Secure users and user
cryptokeys, including registering users, distributing public keys, revoking
keys, and managing user key databases
n Chapter 4 provides instructions for managing the Candle-provided LDAP
respository.
n Chapter 5 provides instructions for securing WebSphere MQ messages
using WebSphere MQ channel exits.
n Appendix A documents CASP Secure Connector, and provides
instruction for its use.
n Appendix B documents the PathWAI Secure administrative and helper
utilities.
n Appendix C provides advice for troubleshooting problems.
n Appendix D documents the messages and return codes.
n Appendix E provides information on contacting Candle Customer
Support.
Where to find more information

n Using the PathWAI Secure administration utility on OS/390—consult the
online help, using F1.
n Using the PathWAI Secure APIs to implement application-to-application
(end-to-end) security for WebSphere MQ messages—consult the PathWAI
Secure Programmer’s Guide.
n Defining WebSphere MQ channels—consult your WebSphere MQ
documentation.
n Using the CandleNet eBP LDAP repository—see your site eBP or CASP
administrator, the PathWAI Secure Installation Guide, and the Roma
BSP™ Directory Services User’s Guide (Version 3.0) or the CandleNet
eBP Administrator™ Directory Services User’s Guide (Version 3.1).

n Creating eBP directory records and specifying inline services—consult the
Roma BSP™ Directory Services User’s Guide (Version 3.0) or the
CandleNet eBP Administrator™ Directory Services User’s Guide (Version
3.1).
We would like to hear from you

Candle welcomes your comments and suggestions for changes or additions to
the documentation set. A user comment form, located at the back of each
manual, provides simple instructions for communicating with the Candle
Information Development department.
You can also send email to UserDoc@candle.com. Please include "PathWAI
Secure for WebSphere MQ Administrator’s Guide, Version 300" in the subject
line.
Ordering additional product documentation

To order additional product manuals, contact your Candle Support Services
representative.
Printing this book

Candle supplies documentation in the Adobe Portable Document Format
(PDF). The Adobe Acrobat Reader will print PDF documents with the fonts,
formatting, and graphics in the original document. To print a Candle
document, do the following.
1. Specify the print options for your system. From the Acrobat Reader Menu bar,
select File > Print Setup… and make your selections. A setting of 300 dpi is
highly recommended as is duplex printing if your printer supports this option.
2. To start printing, select File > Print on the Acrobat Reader Menu bar.
3. On the Print pop-up, select one of the Print Range options for
n a single page
n a range of pages
n all the document
4. (Optional). Select the Shrink to Fit option if you need to fit oversize pages to
the paper size currently loaded on your printer.
Preface 13
The print quality of your output is ultimately determined by your printer.
Sometimes printing problems can occur. If you experience printing problems,
potential areas to check are:
n settings for your printer and printer driver. (The dpi settings for both your
driver and printer should be the same. A setting of 300 dpi is
recommended.)
n the printer driver you are using. (You may need a different printer driver
or the Universal Printer driver from Adobe. This free printer driver is
available at www.adobe.com.)
n the halftone/graphics color adjustment for printing color on black and white
printers (check the printer properties under Start > Settings > Printer).
For more information, see the online help for the Acrobat Reader.
n the amount of available memory in your printer. (Insufficient memory can
cause a document or graphics to fail to print.)
For additional information on printing problems, refer to the documentation
for your printer or contact your printer manufacturer.

Restrictions
R
This product is subject to export and re-export restrictions and regulations
imposed by the government of the United States and, if applicable, the
country to which the product is shipped, and any related federal, state, or
local laws.
As of October 19, 2000, the new export rules for PathWAI Secure for
WebSphere MQ are as follows:
1. No shipments to or use by non-United States Government End Users
outside the United States are allowed without a special license for the
government end user, except for Members of the European Union (EU),
Australia, Czech Republic, Hungary, Japan, New Zealand, Norway,
Poland and Switzerland;
2. No shipments may be made to and the product may not be used or
licensed for use by any person or entity that is a member of, or located in,
any terrorist-supporting nations (currently, Cuba, Iran, Iraq, Libya, North
Korea, Sudan, and Syria); and
3. The product may not otherwise be used in violation of any applicable
license agreement. Some countries’ import regulations prohibit
importation or use of encryption software products, and it is the user's
responsibility to comply with those regulations.
Note: A Government End User is any foreign central, regional, or local
government department, agency, or other entity performing
governmental functions, including governmental research institutions,
governmental corporations or their separate business units (as defined
in part 772 of the EAR) which are engaged in the manufacture or
distribution of items or services controlled on the Wassenaar Munitions
List, and international governmental organizations. The term does not
Restrictions 15
include utilities (including telecommunications companies and Internet
service providers), banks and financial institutions, transportation,
broadcast or entertainment, educational organizations, civil health and
medical organizations, retail or wholesale firms, and manufacturing or
industrial entities not engaged in the manufacture or distribution of
items or services controlled on the Wassenaar Munitions List.
PathWAI Secure for WebSphere MQ Version 300. Copyright © 1997–2002,
Candle Corporation, a California corporation. All rights reserved.
International copyright secured.
This material is proprietary to Candle Corporation and is not to be
reproduced, used, or disclosed except in accordance with program licenses or
upon written authorization of Candle Corporation. This product contains
BSAFE sofware, owned exclusively by RSA™ Data Security, Inc., and
sublicensed by Candle Corporation.

W What’s New
PathWAI Secure Version 300 introduces

n New product names
n Support for third-party public/private key pairs and digital certificates,
including:
– importation and management of key pairs, public key certificates, and
certificate revocation lists issued by third-party certificate or
registration authorities
– certificate revocation checking through certificate revocation lists or
OCSP responders
– message embedding of digital certificates
– exposure of signature information for audit trails
– automatic exchange of public keys used for platform and channel
mutual authentication
n Optional three-prime key generation
n Offset-based range encryption
n Symmetric key reuse option for end-to-end encryption
n Key caching for enhanced performance
CASP Secure Connector Version 300 fully exploits the new features in
PathWAI Secure Version 300.
What’s New 17
The enhancements are described in the following sections. For information on
the new and revised API calls that support these enhancements, please refer
to the PathWAI Secure Programmer’s Guide.
New product names

This product, formerly called MQSecure, has been renamed PathWAI Secure
for WebSphere MQ. In most places, this guide abbreviates the product name
to PathWAI Secure.
Be aware that you may still see the term “MQSecure” in some places within
the installation/user interfaces and sample data.
CandleNet eBusiness Platform MQSecure Connection has been renamed
Candle Application Services Pac (CASP) Secure Connection.
Third-party key pairs and certificates

In addition to providing proprietary RSA key pair generation, PathWAI Secure
now accepts and manages third-party generated key pairs and their verifying
certificates. You can establish the end-point of certificate verification chains
for your environment based on your own certificate practices and standards.
PathWAI Secure imports private keys and public key digital certificates
exported from any Certificate Authority (CA) or Registration Authority (RA)
that supports the PKCS#12 standard.
PathWAI Secure also imports stand-alone public key certificates as
PKCS#7-format DER-encoded certificate files. This makes it possible to
import the trusted root certificates necessary to verify the public key
certificates associated with imported key pairs.
PathWAI Secure supports multiple trust points, as well as both hierarchical
and peer to peer cross-certification.
CRL and OCSP certificate revocation checking

To ensure the validity of imported certificates, PathWAI Secure supports
importation of certificate revocation lists (CRLs). CRLs are imported from CAs
and RAs just like third-party private keys and public key digital certificates,
stored in local certificate databases, and exported to the PathWAI Secure
LDAP repository for central distribution.

CRLs are typically updated on a 12-hour, daily, or weekly basis, but critical
transactions may require a much smaller window during which a potential
attacker can compromise the validity of a certificate and the public key it
contains. OCSP responders provide the means for real-time online checking
of certificate status. Using an OCSP responder also eliminates the need for
maintaining CRLs internally.
PathWAI Secure supports ValiCert’s OCSP responders.
Message-embedded digital certificates

Embedding the public key certificates of message signatories in a PathWAI
Secure message makes it possible for receivers to verify digital signatures
without having to access a PathWAI Secure LDAP repository or previously
imported public keys. This is useful, for example, in business-to-business
situations, where connection to a shared directory may not be possible or
desirable.
Multiple certificates may be sent with a message to enable the receiver to
establish a verification chain to an established local trust point.
Message embedding can be configured on a node-by-node or
channel-by-channel basis.
Audit support
Nonrepudiation typically involves archiving signed messages and the
certificates or public keys required to verify the message signature. PathWAI
Secure provides an API call that allows programmers to extract from the
security trailer the information needed to counter any future attempts to
repudiate the message: the signature, the signer’s public key, the supporting
certificate if included with the message, and the encrypted symmetric key.
This information can then be archived along with the message to create an
audit trail.
Automatic key exchange for mutual authentication

If you are using third-party keys and configure channel exits to perform
platform or channel mutual authentication, you do not have to exchange the
public keys for the platform or channel mutual authentication user IDs.
What’s New 19
At channel startup, the security exits will embed (as available) the full root
chain of certificates with each security exchange message to ensure both sides
of the channel trust each other. This feature avoids the overhead of sending a
certificate or chain of certificates with every signed message.
Triple-prime key generation

Standard generation of RSA public/private key pairs involves the
multiplication of two prime numbers to derive the modulus that is an integral
part of the key construct. The strength of an RSA key is based on the difficulty
of factoring the modulus into its two prime numbers, which can then be used
to establish the private key of the key pair.
Because of the characteristics of the techniques used to factor the modulus,
there is a point where more than two primes can be used to derive the
modulus without compromising security. Using more primes improves the
performance of private key operations.
Using MultiPrime encryption technology, developed by Compaq and
implemented by RSA, PathWAI Secure gives you the option of using three
primes instead of two when generating RSA key pairs with modulus lengths of
1024 bits or greater.
Offset-based range encryption

In addition to delimiter-based range encryption, PathWAI Secure now offers
range encryption based on an array of offset and length specifications. Each
member of the input array specifies the (zero-based) offset to the beginning of
an encryption range and the length of that range. This frees you from having
to edit the range delimiters directly into the text of the message and eliminates
the problem of delimiter characters appearing in the text unexpectedly.
(Range encryption is available only with the COBOL and C/C++ APIs.)
Symmetric key reuse

Previously available only on a channel-by-channel basis, symmetric key reuse
can now be specified on an application-to-application basis using the
PathWAI Secure APIs.
Reuse of symmetric keys allows significant improvement in performance
without sacrificing security. You specify the number of reuses or the maximum

lifetime of the key, and the key is saved at the sender to be reused as
configured. On reuse, the saved key is used to encrypt the message and the
public key encryption operation is bypassed by placing the saved key into the
security trailer.
For information on configuring symmetric key reuse using the PathWAI
Secure APIs, refer to the PathWAI Secure for WebSphere MQ Programmer’s
Guide.
Key caching for enhanced performance

Previously available only with channel exits, key caching is now available on
an application-to-application basis.
Instead of accessing the user key database each time a key is required for an
authentication or encryption operation, PathWAI Secure caches a key the first
time it is accessed and checks the cache first each time a key is required.
Key caching avoids I/O to the user key database and interprocess calls
between the PathWAI Secure application and the database server process.
Interprocess calls can cause huge bottlenecks on heavy throughput systems,
and it is when an application or channel is saturated that the interprocess
communication avoidance plays a major part in improving performance.
See the PathWAI Secure for WebSphere MQ® Programmer’s Guide for more
information on implementing key caching on an application-to-application
basis using the PathWAI Secure APIs.
CASP Secure Connector enhancements

CASP Secure Connector now supports symmetric key reuse and both offset-
and delimiter-based range encryption. CASP Secure Connector also takes
advantage of the performance benefits of key caching and offers more
fine-grained control of security operations in both its plug-and-play and
interactive modes of operation.
What’s New 21
Introducing
1 PathWAI Secure
for WebSphere MQ
Overview
This chapter introduces PathWAI Secure, a suite of software tools that provide
encryption and authentication for messages traveling over WebSphere MQ
networks. It also discusses public key cryptography and describes how
PathWAI Secure implements it.
Chapter Contents
What is PathWAI Secure? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
What does PathWAI Secure do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Why secure messages? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
What security services does PathWAI Secure provide? . . . . . . . . . . . . 24
How are PathWAI Secure services invoked? . . . . . . . . . . . . . . . . . . . . 25
What type of encryption does PathWAI Secure use? . . . . . . . . . . . . . . 25
What type of key management does PathWAI Secure provide? . . . . . 25
What is Public Key Cryptography? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Public/private keys pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Digital certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Digital envelopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Applications of public key cryptography . . . . . . . . . . . . . . . . . . . . . . . 31
How Does PathWAI Secure Work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Securing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Managing users and user keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Introducing PathWAI Secure for WebSphere MQ 23

What is PathWAI Secure?
What does PathWAI Secure do?

PathWAI Secure provides authentication and encryption services for messages
traveling over WebSphere MQ or CASP networks.
Why secure messages?

PathWAI Secure services address four critical aspects of security in distributed
applications:
n Authentication—assuring that the entity that sent the message is actually
who it says it is
n Nonrepudiation—assuring that the sender of a message cannot deny
having sent it
n Integrity—assuring that a message arrived without alteration
n Privacy—assuring that message contents are confidential while traveling
over the network
These services supplement the user authorization capabilities of external
security programs such as RACF, ACF2, and Top Secret on OS/390 and
operating system security tools on UNIX and Windows systems.
What security services does PathWAI Secure provide?

PathWAI Secure provides the following security services:
n Platform mutual authentication—Verifies the identity of communicating
nodes before channels between them are activated. (Available only with
WebSphere MQ channel exits)
n Channel mutual authentication—Verifies the identity of the two
communicating users on an individual channel before the channel is
activated. (Available only with WebSphere MQ channel exits)
n Channel mutual authentication for cluster channels—Verifies the identity
of the two communicating users on an individual cluster channel before
the channel is activated. (Available only with WebSphere MQ channel
exits)

n Signing/authentication—Confirms senders’ identity and the integrity of

messages.
n Encryption—Ensures total message privacy.
n Range encryption—Encrypts selected portions of a message, leaving other
portions in the clear. (Available only with C/C++ and COBOL APIs)
How are PathWAI Secure services invoked?

PathWAI Secure’s security services can be invoked using either WebSphere
MQ channel exits or PathWAI Secure’s APIs.
PathWAI Secure’s channel exit programs provide authentication and
encryption on a node-to-node or channel-specific basis. PathWAI Secure’s
APIs provide these services on an application-to-application (end-to-end)
basis.
What type of encryption does PathWAI Secure use?

PathWAI Secure uses a digital signature, based on a message digest, to
provide nonrepudiation, authentication, and message validation. The
message digests are created with either RSA’s Secure Hash Algorithm (SHA-1)
or MD5.
PathWAI Secure encrypts messages using a combination of RSA
public/private (asymmetric) key pairs and symmetric keys, employing the
concept of a digital envelope. Symmetric key encryption can be done using
any of the following algorithms: RC2,Triple-DES, RC4, RC5, RC6, and AES.
What type of key management does PathWAI Secure provide?

The public/private encryption key pairs used in PathWAI Secure security
operations can be generated by PathWAI Secure or by a third-party certificate
or registration authority. PathWAI Secure includes a set of administrative
utilities for importing, generating, distributing, and revoking user keys and any
certificates necessary for verification of third-party keys.

What is Public Key Cryptography?
Public/private keys pairs

Central to PathWAI Secure’s approach to cryptography is the notion of a
public/private key pair.
In traditional cryptography, a key is the system or pattern used to encode or
decode text. In digital cryptography, a key is a variable value applied using an
algorithm to encrypt or decrypt text or data.
In the secret, or symmetric, key approach, the sender and receiver of a
message share the same key. Under this approach, providing secure key
management (generation, transmission, and storage of keys) is often difficult.
Under the public/private, or asymmetric, key approach, each authorized user
is assigned a pair of keys, one private and one public. The two keys are linked
by a mathematical relationship such that neither of the keys can be derived
from the other. The public key, as its name implies, is made available to all
users of the system, while the private key is available only to its assigned user
and is never shared or transmitted.
FIGURE 1. Symmetric and Asymmetric Keys
Symmetric (Secret) Keys
n Sender and receiver use same key to

encrypt and decrypt messages
n Key must be securely transmitted to
receiver
Asymmetric Keys
n Users issued public/private key pair Private

n Private key held only by owner Public
n Public key distributed to everyone who
needs to communicate with owner

The public/private key pair can be used to prove a sender’s identity and to
confirm the integrity of messages (authenticate), as well as to encrypt and
decrypt them.
Since only the owner has access to the private key of a pair, use of the private
key is proof of the user’s identity. Thus, a sender uses his or her private key to
sign a message, and the receiver uses the sender’s public key to authenticate
the signature—since only the owner of the private key of the pair could have
had access to the private key that signed it. Similarly, public/private keys are
used to encrypt messages so they can be read only by the intended receiver.
The sender uses the intended receiver’s public key to encrypt a message, and
only the intended receiver has access to the matching private key to decrypt it
(see Figure 2 on page 28).
A digital certificate may be associated with the public key of a public/private
key pair to establish the identity of the key owner.
Digital certificates
Digital certificates establish, or certify, the identity of a public key holder. They
are issued by a trusted third party, or certification authority (CA). They contain
the key holder’s name, a serial number, a copy of the certificate holder's
public key, and other information such as expiration date of the certificate,
and are signed by the certification authority (CA) that issued the certificate.
Recipients can use the CA’s signatures to verify that the certificate is real. A
chain of certificates extending back to a mutually trusted third party may be
required to verify a key holder’s identity. Digital certificates are usually kept in
registries so that users can look up others' public keys to encrypt messages or
authenticate signatures.
Certificates are revoked through certificate revocation lists (CRLs), issued
periodically by the CAs. CRLs can be issued as complete lists of the serial
numbers of all revoked certificates, or as "delta" lists which contain only the
changes since the last full CRL was issued. Typically, CRLs are issued at
12-hour, 1-day, or 1-week intervals, depending on installation policies.
To ensure the most current certificate status, CRLs must be downloaded
frequently. For critical applications requiring virtually real-time status
information, or simply to offload the effort of CRL management, revocation
checking can be done through online certificate status protocol (OCSP)
requests to a network-based server application, or responder.

FIGURE 2. Encrypting and Decrypting a Message with Public/Private Keys
Sender encrypts
message using
receiver’s public key,
obtained from
repository.
Receiver decrypts
Public key repository
message using private
key, stored locally
Digital envelopes
The digital envelope is an extension of the public key approach. It combines
the security of asymmetric key encryption and the performance advantage of
symmetric key encryption.

FIGURE 3. Digital Certificate
Certificate
Name
Serial Number
Date
A digital envelope is created by using a symmetric key to encrypt the data,

then using the recipient’s public key to encrypt the symmetric key and the
ciphertext. On the receiving end, the recipient’s private key is used to decrypt
the symmetric key, then the symmetric key is used to decrypt the message (see
Figure 4 on page 30).
Digital envelopes are particularly suited to asynchronous messaging
environments where synchronous authentication protocols are not viable for
transmitting the symmetric encryption key to the recipient.

FIGURE 4. Using a Digital Envelope
Creating a digital envelope
Message text is
encrypted using
symmetric key to
produce ciphertext
message
text + ciphertext
The symmetric key

and the ciphertext
are then encrypted
using the
receiver’s public
ciphertext
+
key to produce a
digital envelope digital envelope
Opening a digital envelope
Digital envelope
is “opened” using
the receiver’s
private key
+ ciphertext
digital envelope
The ciphertext is
decrypted using
the symmetric key
ciphertext + message
text

Applications of public key cryptography
Authenticating senders’ identity

In the day-to-day world of business, signatures are used to prove people’s
identity. Signatures are also used to keep people from repudiating their
actions, such as agreeing to contracts or writing checks.
A digital signature plays the same role in cryptography: a digital signature
attached to a message proves the identity of the sender and prevents the
sender from later denying that he or she sent the message.
Digital signatures can also be used to certify that a public key belongs to a
specific person or entity. The key and information about its owner are signed
using the key of a trusted third party (see “Digital certificates” on page 27).
To sign a message, the sender first supplies the text of the message as input to
a one-way function, or hash, which produces a unique mathematical value,
called a message digest. The message digest cannot be used to recreate the
message, and the smallest change in the message results in a different value
for the digest. The sender then encrypts the message digest using his private
key. This creates the digital signature, which the sender attaches to the
message text.
Since the message digest was encrypted using the sender's private key, it can
only be decrypted using the sender’s public key. To verify that the message
did indeed come from the person it appears to come from, the receiver looks
up the sender's public key, uses it to decrypt the message digest, and saves the
original digest. If the decryption is successful, it proves that the message was
indeed sent by the sender and assures that the sender cannot deny having
sent it. If the decryption is unsuccessful, the receiver knows that the message
did not come from the person it purports to come from and can exercise the
necessary caution.
Verifying message integrity

To confirm that a message has not been tampered with, the receiver supplies
the decrypted message as input to the same one-way function used to
produce the original message digest. If the new message digest is identical to
the message digest received with the message, the receiver can be confident
that the message was not altered in transit. If it is not, the receiver is aware that
the message has been tampered with and can take the necessary precautions.

Ensuring message privacy

To ensure that a message that can only be read by its intended receiver, the
sender looks up the intended receiver’s public key and uses it to encrypt the
message. The message can only be decrypted by the receiver who holds the
associated private key.

How Does PathWAI Secure Work?
Securing messages
PathWAI Secure’s authentication and encryption services can be invoked in
two ways:
n through WebSphere MQ channel exit programs
n through APIs
PathWAI Secure channel exits provide security on a node-to-node or
channel-specific basis. You use channel exits to perform
signing/authentication and encryption/decryption of messages being passed
entirely over channels over which you have control. Channel exits can also be
used to ensure the identity of communicating nodes or individual channel
users before channels are activated.
To invoke PathWAI Secure security services at the channel exit level, a
WebSphere MQ administrator configures WebSphere MQ channels to invoke
channel exits and supplies parameters that tell the channel what PathWAI
Secure channel exit program to use and specify what type of security PathWAI
Secure should apply.
The PathWAI Secure APIs provide security on an application-to-application
basis. Because security is handled by the sending and receiving applications,
the route the messages travel does not matter and you do not need to know
the identity of the machines that handle the messages en route. This method
of securing messages is especially useful when messages must pass through
channels over which you have no control—for example, when messages
travel over the Internet.
The PathWAI Secure APIs allow you to encrypt all or only parts of a message.
Partial, or range, encryption is useful when parts of a message (such as
routing instructions) need to be in the clear, while other parts (such as account
numbers) need to be encrypted. Encryption ranges can be specified using
user-defined delimiters or the offset and length of message segments.
If you have existing applications that use WebSphere MQ MQPUT and MQGET
commands, you can simply add PathWAI Secure direct security function calls.
If you are creating new applications, or are willing to modify existing

programs, you can use integrated calls that make the WebSphere MQ MQPUT
and MQGET calls as well as calling the appropriate security routines.
PathWAI Secure provides APIs for COBOL, C/C++, and Java applications.
For more information on these APIs and developing applications that
implement PathWAI Secure security services, refer to the PathWAI Secure for
WebSphere MQ Programmer’s Guide.
Both channel exits and APIs let you encrypt messages for WebSphere MQ
clusters. Members of the cluster are assigned PathWAI Secure user IDs that
share a common prefix—for example, CLUS1QM1, CLUS1QM2,
CLUS1QM3—so the entire cluster can be identified using the prefix and an
asterisk wildcard (CLUS1*). When the destination ID is specified in this
manner, PathWAI Secure encrypts the message using a symmetric key, then
encrypts the symmetric key using the public key of each queue manager in the
cluster in turn.
Managing users and user keys

PathWAI Secure users are authorized through the process of registration, in
which users are assigned a user ID, a password, and a public/private key pair.
The public/private key pairs used in the PathWAI Secure infrastructure can be
generated by PathWAI Secure or by a third-party certificate or registration
authority (CA/RA). How users are verified depends upon the type of key they
hold.
Users and user keys are managed by a special class of users known as
administrators. The administrator for each PathWAI Secure node is
responsible for
n registering users
n importing and exporting public keys (and supporting certificates and
CRLs, if any)
n managing the local user key database
The administrator also acts as the certifying authority for users holding
PathWAI Secure-generated keys. When local users’ public keys are exported
for distribution to other PathWAI Secure nodes, they are signed using the
administrator’s private key. When those keys are imported by other nodes, the
administrator’s public key is used to authenticate the signature and verify the

identify of the key holder. Local administrators are responsible for revoking
users registered on their node.
PathWAI Secure users holding third-party public keys are verified through
certificate chains to a trusted certificate. The status of certificates is verified
through imported certificate revocation lists or status requests to an OCSP
responder.
Only a Global Administrator can designate certificates as trusted for a site.
Global Administrators are a special class of PathWAI Secure administrator,
with the authority to assign trust to imported certificates and to export trusted
certificates for distribution through the PathWAI Secure network.
For sites using PathWAI Secure-generated keys and distributing keys via an
LDAP repository, Global Administrators act as the certifying authority for local
administrators.
Users holding third-party keys are revoked through CRLs. PathWAI Secure
checks CRLs before any operation requiring verification of a public key
(authentication or encryption) is executed. If a PathWAI Secure-secured node
or channel is configured to use an OCSP responder, the responder is queried
for certificate status.


Configuring Key and Encryption
2 Options
Overview
PathWAI Secure offers a number of key management and encryption options.
Most of these options are configured on a node-by-node basis, using
environment variables. A few are configured on a channel-by-channel basis.
Typically, these options are set at the time PathWAI Secure is installed, but
they can be changed at any time. This chapter describes the available options
and provides instructions for configuring them.
Chapter contents
Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
LDAP Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Hardware Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
Symmetric Encryption Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Asymmetric Key Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Hashing Algorithms for Digital Signatures . . . . . . . . . . . . . . . . . . . . . . . . . 57
PathWAI Secure ID Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Certificate Revocation List Checking. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Online Certificate Revocation Checking . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Triple Prime Key Generation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Message-Embedded Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Queue Authorization using PathWAI Secure Sender ID. . . . . . . . . . . . . . . 85
Symmetric Key Reuse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Configuring Key and Encryption Options 37

Configuration Options
Overview
PathWAI Secure offers a number of options for key generation, key
management, and message encryption.
The following options are configured on a node-by-node basis:
n LDAP Repository—Enable or disable connection to an LDAP repository
for public key storage and distribution
n Hardware encryption—Enable or disable encryption/decryption using an
IBM hardware encryption device (S/390 Crypto Facility, 4758
Cryptographic Coprocessor, or 4963 feature)
n Symmetric encryption algorithm—Specify one of six algorithms at varying
degrees of strength
n Asymmetric key length—Set a modulus size for public/private key pairs
generated by PathWAI Secure
n Hashing algorithm—Select either MD5 or SHA-1 hashing for digital
signatures
n PathWAI Secure ID mapping—Specify how PathWAI Secure IDs are
mapped to certificates’ Subject Name
n Online certificate revocation checking—Enable and configure real-time
checking of certificate revocation status through an OCSP responder
n Triple prime key generation—Enable/Disable key generation with three
primes
n Message-embedded certificates—Embed message signers’ public keys
and supporting certificates in messages
n Queue authorization using PathWAI Secure sender user ID
The following options are configured on a channel-by-channel basis:
n Symmetric key reuse—Enable reuse of symmetric keys by specifying
number of reuses or maximum lifetime of the key

n Message-embedded certificates—Control certificate embedding on a

channel-by-channel basis, overriding default settings for the node.
These options are usually configured at the time PathWAI Secure is installed
on a node, but they may need to be changed or set at some later time. If no
value is set for a particular variable, its default value is in effect.
Configuration
On Windows and UNIX, options can be set using the PathWAI Secure
configuration tool (see Figures 5). On OS/390, they must be set manually.
There are two UNIX versions of the configuration utility: a GUI version and a
command line version. The GUI version requires X/Windows. To run either
version, home/candle/bin must be in the user's path, where candle is the
directory in which PathWAI Secure is installed).
On UNIX, if you reset a variable using the configuration tool, you must make
the same change to your environment by issuing the appropriate export
command from the command line or by modifying the login script (*.profile,
*.cshrc, or *.login).
On OS/390, options are configured by specifying a value for the appropriate
variable in the member pointed to by DD statement MQSCONF in the
MFSSRVR JCL on each server. After you have made the changes, you must
recycle the servers (MFSSRVR).
After you reset any of these variables on any platform, you must recycle all
PathWAI Secure-related processes, including any WebSphere MQ channels
using PathWAI Secure channel exits.

FIGURE 5. PathWAI Secure Configuration Tool for Windows

LDAP Repository
LDAP Repository
LDAP-based distribution of public keys

PathWAI Secure supports use of an LDAP repository for distribution of public
keys. Using an LDAP repository eliminates the need to distribute public keys
using files or queue managers.
If your site is configured to use an LDAP repository, public keys (and
supporting certificates, if any) are automatically exported to the repository
when users are registered, and automatically copied to remote nodes the first
time they are required to authenticate or encrypt messages.
Note: If no LDAP connection is available at the time users are registered,
their keys can be exported to the repository using the administrative
utility.
If you elect to use an LDAP repository, you must provide the host name or IP
address and port number of the LDAP server to which the node connects.
Administrators must enter an LDAP user ID and password for any operation
that accesses the repository. The LDAP user ID is entered prefixed by cn=.
For example:
LDAP Update User ID: cn=manager
Configuring an LDAP connection on Windows

To enable/disable LDAP connection or to change the LDAP host or port
number to which a node connects:
1. Select
Start > Programs > PathWAI Secure for WebSphere MQ >
PathWAI Secure for WebSphere MQ Configuration Tool.
2. In the LDAP connection area of the Configure PathWAI Secure for
WebSphere MQ Node tab:
– To enable the LDAP connection, click the checkbox for Use Connection.
– To disable the LDAP connection, uncheck the box for Use Connection.
– To set the LDAP host, type the host name or IP address in the LDAP
Server Address field.

LDAP Repository
– To set the LDAP port, type the port number in the LDAP Server Port
field.
The port number used by the node must match the port number set for
the LDAP server on the LDAP repository host.
3. If you are finished setting variables, click Apply to set the variables.
A message appears to inform you when the variables have been set. When
you dismiss the message, a dialog appears asking if you want to reboot now.
4. Either reboot the machine or recycle all the PathWAI Secure-related
processes.
Configuring an LDAP connection on UNIX (GUI)

1. Launch the configuration utility by entering the following command from the
command line:
MQConfig
The PathWAI Secure configuration tool appears.
2. In the LDAP Connection area of the Configure PathWAI Secure for
WebSphere MQ Node tab:
– To change or set the LDAP host, type the new host name or IP address in
the LDAP Server Address field.
– To set or change the LDAP port, type the new port number in the LDAP
Server Port field.
The port number used by the node must match the port number set for
the LDAP server on the LDAP repository host.
– To disable the connection to the LDAP repository, enter none in both the
server address and server port fields.
3. If you are finished changing variables, click Apply to set the variables.
4. Enter one or both of following commands from the command line or add
them to the login script:
export MQSECURE_LDAP_SERVER_ADDRESS=new_address

LDAP Repository
export MQSECURE_LDAP_SERVER_PORT=new_port_number
5. Recycle all the PathWAI Secure-related processes.
Configuring an LDAP connection on UNIX (text mode)

1. If necessary, launch the configuration utility by entering the following
command from the command line:
MQConfig -l
After the runtime settings and the CLASSPATH are displayed, the message
Starting PathWAI Secure Command Line Configuration...
appears, followed by a series of prompts.
2. To set or change the value of the LDAP server address or port number
variable, type the host name or IP address or port number, then press Enter.
The port number used by the node must match the port number set for the
LDAP server on the LDAP repository host.
– To keep the default name or number, just press Enter.
– To disable the connection to the LDAP repository, enter none for both the
server address and server port.
3. If you are finished changing variables, continue pressing Enter in response to
the subsequent prompts. If you want to change other variables, enter the
appropriate values, then press Enter.
When the variables have been reset, the message Configuration
complete is displayed.
4. Enter the following commands, as appropriate, from the command line or
add them to the login script:
export MQSECURE_LDAP_SERVER_ADDRESS=new_address
export MQSECURE_LDAP_SERVER_PORT=new_port_number
Configuring an LDAP connection on OS/390

To enable an LDAP connection, set

LDAP Repository
MQSECURE_LDAP_SERVER_ADDRESS=
to indicate the hostname or IP address of the machine to which PathWAI
Secure should connect, and
MQSECURE_LDAP_SERVER_PORT=
to indicate the port number to which PathWAI Secure should connect. The
default port number is 389.
To disable an existing LDAP connection, set both variables to NONE.

Hardware Encryption
Hardware Encryption
Hardware encryption devices
MQSecure supports IBM’s CMOS cryptographic coprocessor (including the

PCICC adapter), 4758 cryptographic coprocessor (Windows), and the 4958
and 4963 crytographic accelerators (AIX). Depending on the hardware
configuration and system workload, these processors can provide improved
performance for cryptographic operations (random number generation,
digital signature, and symmetric and asymmetric encryption and decryption).
However, usage of hardware encryption is optional and does not increase
cryptographic strength compared to a software implementation.
To take advantage of the hardware encryption, you must be using PathWAI
Secure encryption services through channel exits, APIs, or the CASP Secure
Connector.
If hardware encryption is not enabled, all encryption operations are done in
software.
Note: AIX is the only UNIX platform that supports hardware with PathWAI
Secure.
Configuring a Windows node

Note: If you are using Windows with a 4758 cryptographic coprocessor
installed, reconfiguring PathWAI Secure back to using software after
having configured for hardware may cause errors in other applications
that use CCA.
Before reconfiguring, check the setting for the PATH environment
variable at the system level. The directories containing the support
libraries for the 4758 must come before the PathWAI Secure libraries.
The order of these libraries on your system path depends on the order
of installation of PathWAI Secure and the 4758 support code. If
necessary, reorder the libraries so the PathWAI Secure libraries appear
after the IBM 4758 libraries.
To change the encryption type of a node:

Hardware Encryption
Note: If you are enabling the 4758 Cryptographic Coprocessor, you must
shut down all PathWAI Secure applications and channels and issue a
dbdown command before starting the configuration tool.
1. Start the PathWAI Secure Configuration tool, if necessary:
2. On the Configure PathWAI Secure for WebSphere MQ tab:
– To enable hardware encryption, for Hardware Enabled select
ADAPTER1 from the dropdown menu.
– To disable hardware encryption, for Hardware Enabled select none
from the dropdown menu.
3. If you are finished setting variables, click Apply to set the variables.
processes.
Configuring a UNIX node (GUI mode)

To change the encryption type of the node from hardware to software, or from
software to hardware:
command line:
MQConfig
2. On the Configure PathWAI Secure for WebSphere MQ Node tab:
– To enable hardware encryption, for Hardware Enabled select
ADAPTER1 from the dropdown menu.
– To disable hardware encryption, for Hardware Enabled select none
from the dropdown menu.
3. Click Apply to set the variables.

Hardware Encryption
4. Enter the appropriate command from the command line or add it to the login
script:
– if you are changing from software encryption to hardware encryption,
enter:
export MQSECURE_HARDWARE_ENABLED=ADAPTER1
– if you are changing from hardware encryption to software encryption,
enter:
export MQSECURE_HARDWARE_ENABLED=
Configuring a UNIX node (text mode)

To change the encryption type of the node from hardware to software, or from
software to hardware:
command line:
MQConfig -l
2. Press Enter to accept the defaults for MQSECURE_LDAP_SERVER_ADDRESS
and MQSECURE_LDAP_SERVER_PORT.
The following prompt is displayed:
Enter value of MQSECURE_HARDWARE_ENABLED (none or
adapter1) (Default is: none):
– If you want to use hardware-enabled encryption, enter ADAPTER1.
– If you want to use software encryption, enter none.
When the variables have been reset, the message “Configuration complete” is
displayed.

Hardware Encryption
4. Enter the following commands, as appropriate, from the command line or

add them to the login script:
– if you are changing from software encryption to the cryptographic
coprocessor, enter:
export MQSECURE_HARDWARE_ENABLED=ADAPTER1
– if you are changing from the cryptographic coprocessor to software
encryption, enter:
export MQSECURE_HARDWARE_ENABLED=
Configuring an OS/390 node

Several PathWAI Secure installation steps are necessary prior to enabling
hardware support on the OS/390. Also, security profiles (RACF, ACF2) need
to be considered. Please refer to the PathWAI Secure for WebSphere MQ
Installation Guide chapter on OS/390 installation and any current readme files
for additional information.
To enable the IBM OS/390 Crypto Facility, change the variable
MQSECURE_HARDWARE_ENABLED=
to
MQSECURE_HARDWARE_ENABLED=S390
To disable the Crypto Facility, change
MQSECURE_HARDWARE_ENABLED=S390
to
MQSECURE_HARDWARE_ENABLED=

Symmetric Encryption Algorithm
Symmetric key encryption algorithms

PathWAI Secure supports message encryption with symmetric keys using any
of the following algorithms. If no value is specified, the default value is RC2 at
128 bits.
RC2 A block cipher that operates on 8-byte blocks. This algorithm was
designed as a drop-in replacement for the DES algorithm, but
optimized for software. The only key length supported is 128 bits.
RC2 is the default alogrithm used by PathWAI Secure if no
symmetric encryption algorithm is explicitly specified.
Triple-DES A block cipher that uses three iterations of the DES (Data Encryption
(TDES) Standard) algorithm on each 8-byte block. PathWAI Secure uses
the 2-key EDE implementation of Triple-DES. This method uses two
different DES keys, the first used to encrypt each block, the second
used to decrypt the output of the first, encryption operation, and
finally the first key is used again to encrypt the output of the second,
decryption operation.
RC4 A stream cipher that operates on bit or byte streams. Its execution
speed is considered very fast, but the encryption key can only be
used once. As a result, PathWAI Secure’s channel exit key reuse
feature will not allow reuse of RC4 keys. Key lengths supported are
128, 192, and 256 bits.
RC5 A block cipher that operates on 8-byte blocks. It is a successor to the
RC2 algorithm and offers higher execution speed and comparable
strength of security at similar key lengths. Key lengths supported are
128, 192, and 256 bits.
RC6 A block cipher that operates on 16-byte blocks. It is a successor to
the RC5 algorithm and was a final candidate for the new Advanced
Encryption Standard (AES) algorithm to replace DES. Key lengths
supported are 128, 192, and 256 bits.
AES A block cipher that operates on 16-byte blocks. It was selected as the
(RijnDael) new Advanced Encryption Standard (AES) algorithm to replace
DES. Key lengths supported are 128, 192, and 256 bits.

Selecting the appropriate encryption algorithm for your site

There is a trade-off between encryption strength and performance: the
stronger the encryption algorithm, the greater the performance impact. Before
deciding which encryption algorithm to use, you need to evaluate your
security requirements and weigh their performance costs.
Table 1 lists the algorithms in descending of order of cryptographic strength.
Table 1. Cryptographic Algorithms by Strength

AES (strongest)
RC6
RC5
RC4
TDES
RC2 (weakest)
Table 2 lists the encryption algorithms in descending order of amount of

throughput.
Table 2. Cryptographic Algorithms by Throughput

RC4 (most)
RC5
RC6, AES
RC2, TDES (least)
You must also take into account the following constraints:

n If you intend to reuse symmetric keys, you cannot use RC4.
n If you intend to use hardware support (4758 or S/390 Crypto
Coprocessor), you must use TDES.
n If you are using software encryption and an PathWAI Secure Version 300
or 210 node is communicating with another Version 300 or 210 node,
you may specify any of the supported algorithms listed, including triple
DES.

n If an PathWAI Secure V210 or V300 node is communicating with a V200

node, you may use either RC2 or TDES. If an PathWAI Secure Version
210 or V300 node is communicating with a Version 110 node, you must
use RC2.

To set the encryption algorithm on a Windows node:
1. Launch the configuration utility by selecting Start > Programs >
PathWAI Secure for WebSphere MQ > PathWAI Secure for
WebSphere MQ Tool.
2. On the Configure PathWAI Secure for WebSphere MQ Node tab, use
the dropdown menu for the Symmetric Encryption field to select the
algorithm and key length you wish to use—for example, AES128.
3. Click Apply to set the variables, or continue selecting other variables.
processes.

To set the encryption algorithm on a UNIX node in GUI mode:
1. Launch the configuration utility by entering the following command on the
command line:
MQConfig
the dropdown menu for the Symmetric Encryption field to select the
algorithm and key length you wish to use—for example, AES128.
script. For example:
export MQSECURE_SYM_ENCRYPT=AES128


To set the algorithm used for encryption on a UNIX node (text mode):
1. Launch the configuration utility, if necessary, by entering the following
MQConfig -l
2. Accept the defaults for all prompts by pressing Enter until the following
prompt is displayed:
Enter value of MQSECURE_SYM_ENCRYPT (Default is:
current_value):
3. Enter one of the following values:
RC2 TDES RC4128 RC5128 RC6128 AES128

RC4192 RC5192 RC6192 AES192
RC4256 RC5256 RC6256 AES256
4. If you are finished configuring variables, continue pressing Enter in response

to the subsequent prompts. If you want to change other variables, enter the
displayed.
export MQSECURE_SYM_ENCRYPT=AES128


To set the algorithm used for symmetric encryption, set
MQSECURE_SYM_ENCRYPT=
to one of the following values
TDES RC2 RC4128 RC5128 RC6128 AES128

RC4192 RC5192 RC6192 AES192
RC4256 RC5256 RC6256 AES256
If you are using software encryption and a PathWAI Secure Version 300 or
210 node is communicating with another Version 300 or 210 node, you may
specify any of the supported algorithms listed, including triple DES (TDES). If
you are using hardware encryption, you must use TDES.
If a PathWAI Secure V210 or V300 node is communicating with a V200 node,
you may use either RC2 or TDES. If a PathWAI Secure Version 210 or V300
node is communicating with a Version 110 node, you must use RC2.

Asymmetric Key Length
Asymmetric key length

RSA keys use a modulus–exponent format. The RSA key length consists of
two different lengths (the private key length and the public key length), neither
of which has the same value as the modulus size. The modulus size is an input
to the RSA key pair values. The greater the modulus size, the greater the
length of the public/private key pair. Greater modulus size does not
significantly affect performance.
For PathWAI Secure-generated key pairs, the default modulus is 1024 bits, but
you can use any modulus between 768 and 2048 bits. The modulus set for a
node acts as a default, but it can be overriden when a new key pair is
generated.
Modulus size is set on a node-by-node basis, but you can override the default
modulus size when you generate new administrator or user keys. On
distributed systems, you use the parameter -l when you generate
administrator (-s ) or user (-g) keys. On OS/390, you specify the desired
modulus size in the RSA Modulus Size field.
You cannot specify key length for third-party keys.
Note: To exchange messages with nodes using PathWAI Secure Version 110
or 200, you must use an 800-bit key length. If you specify a number
that is not divisible by 8, the cryptographic services will round the
value up to one that is divisible by 8.

To set the modulus size on a Windows node:
1. Launch the configuration utility by selecting Start > Programs >
PathWAI Secure for WebSphere MQ > PathWAI Secure for
WebSphere MQ Configuration Tool.
2. On the Configure PathWAI Secure for WebSphere MQ Node tab, in the
Default RSA Modulus Size field type any modulus size between 768 and
2048 bits.

Note: If you specify a number that is not divisible by 8, the cryptographic

services will round the value up to one that is divisible by 8.
3. Click Apply to set the variables, or continue selecting other variables.
processes.
Configuring a UNIX node

Note: Although the PathWAI Secure configuration tool lets you set a value
for this variable, setting it has no effect. The configuration program
updates only the mqsecure.conf file, which is currently used only
by the PathWAI Secure channel exit programs, which do not care
about the default key length.
To set the modulus size on a UNIX node, set the environment variable
MQSECURE_RSA_MODULUS_SIZE in the shell where the administrative
utility is to be run. Enter the appropriate the appropriate statement from a
command prompt, or add it to the .profile, .cshrc, or .login file. For example:
bash, ksh:
export MQSECURE_RSA_MODULUS_SIZE=1024
sh:
MQSECURE_RSA_MODULUS_SIZE=1024
export MQSECURE_RSA_MODULUS_SIZE
csh:
set MQSECURE_RSA_MODULUS_SIZE=1024
You must recycle all the PathWAI Secure-related processes for the changes to
take effect.


To set the default modulus size for a node, set
MQSECURE_RSA_MODULUS_SIZE=
to a modulus length between 768 and 2048.

Hashing Algorithms for Digital Signatures
Hashing algorithms
PathWAI Secure supports both MD5 and SHA-1 hashing algorithms. SHA-1 is
considered more secure than the MD5 hashing algorithm and should be used
wherever possible. MD5 should be used where compatibility with existing
PathWAI Secure installations (V200 and before) is an issue.

To set the hashing algorithm on a Windows node:
1. Launch the configuration utility, if necessary, by selecting Start >
Programs > PathWAI Secure for WebSphere MQ > PathWAI
Secure for WebSphere MQ Configuration Tool.
the dropdown menu of the Signature Algorithm field to select either
RSASHA1 or RSAMD5.
3. Click Apply to set the new algorithm, or continue selecting other variables.
processes.

To set the hashing algorithm on a UNIX node in GUI mode:
command on the command line:
MQConfig
the dropdown menu of the Signature Algorithm field to select either
RSASHA1 or RSAMD5.


export MQSECURE_SIGNING_ALGORITHM=RSASHA1

To set the hashing algorithm on a UNIX node using text mode:
MQConfig -l
Enter value of Signature Algorithm (Default is:
current_value):
3. Enter either RSAMD5 or RSASHA1.
displayed.
5. Set the variable MQSECURE_SIGNING_ALGORITHM for use by the
administrative utility and the APIs by entering the appropriate command from
the command line or adding it to the login script. The possible values are
RSASHA1 and RSAMD5.
For example:
export MQSECURE_SIGNING_ALGORITHM=RSASHA1


To specify MD5, set
MQSECURE_SIGNING_ALGORITHM=RSAMD5
To specify SHA-1, set
MQSECURE_SIGNING_ALGORITHM=RSASHA1
If the MQSECURE_SIGNING_ALGORITHM variable is not set, or no value is
specified, the default value is MD5.

PathWAI Secure ID Mapping
Mapping PathWAI Secure IDs to certificate subject names

The user ID PathWAI Secure assigns to a third-party key pair is derived from
the subject name on its public key certificate. The subject name of a X.509 v.3
certificate is a Distinguished Name (DN)—a string of attribute–value pairs that
uniquely identifies an entity, such as a certificate holder. Each attribute–value
pair, or assertion, consists of an attribute identifier and its corresponding value
information. For example:
cn=PathWAI Secure User, ou=R and D, o=Candle, l=El
Segundo, c=US, e=PathWAI_Secure_User@Candle.com
The subject names of X.509 v.3 certficates may be comprised of one or more
of the attribute–value assertions (AVAs) listed in Table 3. By default, PathWAI
Secure uses the value of the COMMON_NAME (cn) attribute as the PathWAI
Secure user ID, but you can configure it to use the value of any other attribute
of the Distinguished Name.
Table 3. X.509 Certificate Subject Name AVAs

COMMON_NAME
LOCALITY
STATE
ORGANIZATION
ORG_UNIT
COUNTRY
STREET_ADDRESS
DOMAIN_COMPONENT
SERIAL_NUMBER
TITLE
POSTAL_CODE
EMAIL_ADDRESS
DN_QUALIFIER
SURNAME
GIVEN_NAME
INITIALS
GENERATION_QUALIFIER
NAME

The attributes included in the subject name vary from certificate authority to
certificate authority. You should be aware of, or set a standard for, the
attributes included in the subject name of the certificates that are used to
verify PathWAI Secure users keys.
PathWAI Secure has very strict naming conventions for channel and cluster
mutual authentication IDs (see “Users, User IDs, and Passwords” on page 98).
You must ensure that the component of the Distinguished Name used as the
PathWAI Secure user ID conforms to these conventions.

To set the ID mapping on a Windows node:
the dropdown menu of the ID Mapping Attribute field to select the desired
attribute.
3. Click Apply to set the new selection, or continue selecting other variables.
processes.
Configuring an UNIX node (GUI mode)

To set the ID mapping attribute on a UNIX node in GUI mode:
MQConfig
the dropdown menu of the ID Mapping Attribute field to select the desired
attribute.

3. Click Apply to set the new selection.

export MQSECURE_ID_MAPPING_ATTRIBUTE= EMAIL_ADDRESS
Configuring an UNIX node (text mode)

To configure PathWAI Secure ID mapping to a certificate Distinguished Name
attribute:
MQConfig -l
2. At the prompt
MQSECURE_ID_MAPPING_ATTRIBUTE(Default is: current_value):
enter one of the attributes from Table 3 on page 60.
the subsequent prompts to accept the current values. If you want to change
other variables, enter the appropriate values, then press Enter.
displayed.
export MQSECURE_ID_MAPPING_ATTRIBUTE=EMAIL_ADDRESS

To change the component of the Distinguished Name PathWAI Secure uses as
the user ID, set

MQSECURE_ID_MAPPING_ATTRIBUTE=
to one of the attributes shown in Table 3 on page 60.

Certificate Revocation List Checking
Disabling CRL Checking

If you are using third-party public key certificates, by default there must be
certificate revocation lists (CRL) in the local database for the issuers of the
certificates. If there is no CRL, certificate verification will fail and the
authentication or encryption operation will not be performed. For testing
purposes or in an emergency you may want to disable CRL checking so you
can use certificates without having CRLs in the local database.
While the ability to disable CRL checking can be useful, it defeats the purpose
of using certificates and should be exercised with caution.

To enable or disable CRL checking on a Windows node:
the dropdown menu of the Certificate Revocation List Checking field to
select Yes to enable CRL checking, No to disable CRL checking.
3. Click Apply to set the new selection, or continue selecting other variables.
processes.

To enable or disable CRL checking on a UNIX node in GUI mode:
MQConfig


the dropdown menu of the Certificate Revocation Lists Checking field
to select Yes enable CRL checking, or No to disable CRL checking.
3. Click Apply to set the new selection.
export MQSECURE_CRL_CHECKING= NO

To enable or disable CRL checking on a UNIX node using text mode:
MQConfig -l
2. At the prompt
MQSECURE_CRL_CHECKING (Default is: current_value):
enter NO to disable CRL checking, YES to enable checking.
displayed.
export MQSECURE_CRL_CHECKING=NO


To disable CRL checking, set
MQSECURE_CRL_CHECKING
to
MQSECURE_CRL_CHECKING=NO
To enable CRL checking, set
MQSECURE_CRL_CHECKING
to
MQSECURE_CRL_CHECKING=YES
If the environment variable is not present or has no value specified, CRL
checking will take place for every operation that requires verification of a
public key.

Online Certificate Revocation Checking
OCSP-based revocation checking

The online certificate status protocol (OCSP) defines a standard for
communicating a request for the revocation status of a certificate to a server,
or responder. The responder evaluates the request and returns the status of
the certificate. Typically, the OCSP responder is stationed on the network and
is accessed through a URL and port.
An OCSP responder may be used to provide real-time certificate status for
critical applications or to offload management of certificate revocation lists
(CRLs) to a focal point in an organization or to an external entity (such as
Identrus).
PathWAI Secure currently provides support for ValiCert responders.
How it works
Validation of a certificate and its revocation status through an OCSP
responder is triggered by configuration of PathWAI Secure and the presence
of certificate extensions, if any, which allow the OCSP requests to be
submitted to a network address. Revocation checking is done whenever a
public key is required for authentication of a signature or encryption of a
message.
Each certificate within the chain of verification back to a trust point is
validated through the responder. If you elect to use an OCSP responder and
the certificates contain extensions, all the certificates in the verification path to
a trust point must contain extensions specifying the same URL as the
certificate being validated.
Responders return a status of “valid”, “invalid”, or “unknown” for each
certificate. If the certificate status is “invalid” or “unknown”, the PathWAI
Secure operation fails. For channel exits, the error is logged to the problems
queue and the channel exit logs. For programs using the PathWAI Secure
APIs, an error message is issued.
The certificate for the signer of the response from the responder must be in the
local trusted database. This certificate must be imported by the Global
Administrator as trusted (see “Importing trusted certificates” on page 108)

and exported as trusted either to the LDAP repository or to a PKCS#7 file for
distribution to all nodes that will be communicating with the responder.
Enabling
You enable checking by specifying ValiCert as the OCSP responder type. In
addition, you must provide some or all of the following information.
Location of responder and proxy

You may need to supply the network location of your responder and its proxy.
You need to determine if your OCSP configuration requires specification of
the URLs for either or both. If the URLs are specified in a certificate’s AIA
extension, you do not need to provide them. URLs specified in the certificate
extension override those specified in the PathWAI Secure configuration. If
there are no URLs specified in the certificate extensions and you do not
provide them by configuring the PathWAI Secure variable, the request will fail.
You can specify multiple URLs, separated by a comma. Information encoded
within a certificate determines which OCSP responder from the list to use for
validation. Proxy URLs are matched to corresponding responder URLs based
on the protocol.
Note: Specified URLs are expected to comply with IETF RFC 1630. If the
URL contains a space, represent the space with the escape character
“%20”.
Certificate cache retention time

Network operations to retrieve certificate status information from OCSP
responders are relatively expensive and can affect message throughput. They
may also be the focus of denial-of-service attacks, in which messages are sent
using known revoked keys.
To reduce the number of responder requests for certificate validation,
PathWAI Secure uses in-memory caching for certificates. This cache is
checked before a request is sent to the responder. You can regulate the age of
the cache by specifying a cache retention time (in seconds).
In setting this variable, you should attempt to balance your need for real time
certificate revocation information with the cost of the overhead of collecting
this information. In some cases, the responder returns the "next update" date

and time for a certificate within its repository. The next update date/time
overrides the cache retention setting.
Scope of checking
By default, OCSP checking is configured on a node-by-node (GLOBAL)
basis. You can limit the overhead incurred by OCSP validation by limiting the
scope of OCSP revocation checking to specific channels. To enable checking
for specific channels, you specify CHANNEL as the scope of checking and
add the letter “V” in the MSGDATA parameter of each channel for which you
want checking enabled.
For application-level (API) checking, scope must be set to GLOBAL.
Request and response signatories

Some responders require that all certificate status requests be signed. All
responses from an OCSP responder must be signed. You specify the certificate
subject name (Distinguished Name) for the response and request signatories
when you configure OCSP checking.
Either the public key certificate for the responder signatory or the end point of
the certificate verification chain for the certificate must be a trusted certificate.
The certificates must be obtained from the responder and imported by the
Global Administrator. Either the signatory’s certificate itself or a certificate in
the chain must then be exported either to an LDAP repository or to a
PKCS#7 file with the trust flag set and imported to the local trusted certificate
databases.
When the response signatory’s certificate is first imported, the Global
Administrator should copy the Distinguished Name as it is displayed by
PathWAI Secure and transmit it to all nodes that are to be configured for
OCSP revocation checking. The Distinguished Name can also be looked up in
the trusted certificate database (see “Viewing registered users and certificates”
on page 101) or using any certificate management application on the
platform.)
If the specified Distinguished Name of a signer is not found in the trusted
certificate database, the WebSphere MQ channel will fail to start and an
API-based operation will fail.


To configure online revocation checking using an OCSP responder:
1. Launch the configuration utility, if necessary:
PathWAI Secure for WebSphere MQ Configuration Tool
2. On the Configure PathWAI Secure for WebSphere MQ Node tab,
select VALICERT from the dropdown menu of the OCSP Revocation
Checking field.
The OCSP communications options appear.
3. Specify the following values as required by your OCSP responder:
– For OCSP Scope, select GLOBAL to enable revocation checking for
all channels on the none; select CHANNEL to enable revocation
checking on only those channels which have been configured with a
“V” in the MSGDATA parameter.
– For OCSP_REQUESTOR_CERT, type the Distinguished Name on the
certificate of the PathWAI Secure user who will sign requests to the
OCSP responder from this node.
– For OCSP_RESPONSE_CERT, type the Distinguished Name on the
trusted certificate of the key holder who will sign responses to status
requests.
– For OCSP_TRANSPORT_DESTINATIONS, type the URL of the
reponder to which the status request will be sent. You can specify
multiple URLs, separated by a comma.
– For OCSP_TRANSPORT_PROXIES, type the URL for the responder
proxy, if any. You can specify multiple URLs, separated by a comma.
– For OCSP_CACHE_RETENTION, type the amount of time (in
seconds) status information should be kept in in-memory cache.
4. Click Apply to set the new settings, or continue selecting other variables.
processes.


To configure online revocation checking using an OCSP responder:
MQConfig
2. On the Configure PathWAI Secure for WebSphere MQ Node tab,
select VALICERT from the dropdown menu of the OCSP Revocation
Checking field.
The OCSP Communications Options dialog appears.
3. Specify the following values as required by your OCSP responder:
– For OCSP Scope, click Global to enable revocation checking for all
channels on the node; click Channel to enable revocation checking on
only those channels which have been configured with a “V” in the
MSGDATA parameter.
– For OCSP_REQUESTOR_CERT, type the Distinguished Name on the
certificate of the PathWAI Secure user who will sign requests to the OCSP
responder from this node.
– For OCSP_RESPONSE_CERT, type the Distinguished Name on the
trusted certificate of the key holder who will sign responses to status
requests.
– For OCSP_TRANSPORT_DESTINATIONS, type the URL of the
reponder to which the status request will be sent. You can specify multiple
URLs, separated by a comma.
– For OCSP_TRANSPORT_PROXIES, type the URL for the responder
proxy, if any. You can specify multiple URLs, separated by a comma.
– For OCSP_CACHE_RETENTION, type the amount of time (in seconds)
status information should be kept in in-memory cache.
4. Click OK to close the dialog and save the settings. Click Cancel to close the
dialog without saving the settings.
The Configure PathWAI Secure for WebSphere MQ Node tab
reappears.

6. Issue the appropriate export command from the command line or by
modifying the login script (*.profile, *.cshrc, or *.login) to export the modified
variables:
MQSECURE_OCSP_REVOCATION_CHECKING=VALICERT | NONE
MQSECURE_OCSP_SCOPE=GLOBAL | CHANNEL
MQSECURE_OCSP_TRANSPORT_DESTINATIONS=OCSP Responder
URL(s) | NONE
MQSECURE_OCSP_TRANSPORT_PROXIES=OCSP Responder Proxy
URL(s) | NONE
MQSECURE_OCSP_REQUESTOR_CERT=Distinguished Name | NONE
MQSECURE_OCSP_RESPONSE_CERT=Distinguished Name | NONE
MQSECURE_OCSP_CACHE_RETENTION=time_in_seconds

To configure OCSP revocation checking:
MQConfig -l
2. At the prompt
MQSECURE_OCSP_REVOCATION_CHECKING (Default is: NONE):
enter VALICERT to enable revocation checking with a ValiCert responder.
3. At the prompt
MQSECURE_OCSP_REQUESTOR_CERT (Default is: NONE):
enter the subject name (Distinguished Name) on the certificate of the PathWAI
Secure user who will sign requests to the OCSP responder from this node, if
required.

If no signature is required on OCSP requests, accept the default by pressing

Enter.
4. At the prompt
MQSECURE_OCSP_RESPONSE_CERT (Default is: NONE):
enter the subject name (Distinguished Name) on the trusted certificate of the
key holder who will sign the responder’s responses to status requests.
5. At the prompt
MQSECURE_OCSP_TRANSPORT_DESTINATIONS (Default is: NONE):
enter the URL of the reponder to which the status request will be sent. You
can specify multiple URLs, separated by a comma.
6. At the prompt
MQSECURE_OCSP_TRANSPORT_PROXIES (Default is: NONE):
enter the URL for the responder proxy, if any. You can specify multiple URLs,
separated by a comma.
7. At the prompt
MQSECURE_OCSP_CACHE_RETENTION (Default is: NONE):
enter the amount of time (in seconds) status information should be kept in
in-memory cache.
8. At the prompt
MQSECURE_OCSP_SCOPE (Default is: GLOBAL):
enter GLOBAL to enable revocation checking for all channels on the node;
enter CHANNEL to enable revocation checking on only those channels which
are configured with a “V” in the MSGDATA parameter.
displayed.
10. Enter the appropriate commands from the command line or add them to the
login script. For example:
export MQSECURE_OCSP_SCOPE=GLOBAL


To enable OCSP revocation checking, add or set the following variables. If a
variable is not present or no value is specified, the default value (indicated by
an underscore) is in force. Refer to “Enabling” on page 68 for a discussion of
the options for each variable.
MQSECURE_OCSP_REVOCATION_CHECKING=VALICERT | NONE
MQSECURE_OCSP_SCOPE=GLOBAL | CHANNEL
MQSECURE_OCSP_TRANSPORT_DESTINATIONS=OCSP Responder
URL(s) | NONE
MQSECURE_OCSP_TRANSPORT_PROXIES=OCSP Responder Proxy
URL(s) | NONE
MQSECURE_OCSP_REQUESTOR_CERT=Distinguished Name | NONE
MQSECURE_OCSP_RESPONSE_CERT=Distinguished Name | NONE
MQSECURE_OCSP_CACHE_RETENTION=time_in_seconds

Triple Prime Key Generation
Overview
By default, PathWAI Secure uses two prime numbers to generate a key pair
modulus. You can reduce processing overhead in private key operations by
enabling triple prime key generation.
Standard generation of RSA keys involves the multiplication of two prime
number to derive the modulus that is an integral part of the key construct.
The strength of an RSA key is based on the difficulty of factoring the modulus
into its two prime numbers which can then be used to establish the private key
of the key pair. Because of the characteristics of the techniques used when
attempting to factor the modulus, there is a point at which the use of more
than two prime numbers in deriving the modulus can be used without
compromising security. Using more primes improves the performance of
private key operations.
PathWAI Secure’s implementation of multiprime key generation (using RSA’s
version of Compaq’s MultiPrime technology) uses three primes in the
generation of RSA keys with a modulus length of 1024 through 2048 bits. If
shorter modulus lengths are specified, PathWAI Secure will use only two
prime numbers to generate the RSA key modulus even if multiprime key
generation is configured, so security is not compromised.

To enable or disable use of triple primes for asymmetric key generation:
2. On the Configure PathWAI Secure for WebSphere MQ Node tab, click
the dropdown menu for the MultiPrime Key field and select:
– YES to enable triple prime key generation.
– NO to disable triple prime key generation.

processes.

To enable/disable generation of PathWAI Secure asymmetric keys with three
primes:
MQConfig
the dropdown menu for the MultiPrime Key field and select:
– YES to enable triple prime key generation.
– NO to disable triple prime key generation.
modifying the login script to export the modified variables. For example:
export MQSECURE_MULTIPRIME_KEYS=YES

To enable/disable generation of PathWAI Secure asymmetric keys with three
primes:
MQConfig -l

2. At the prompt
MQSECURE_MULTIPRIME_KEYS (Default is: NO):
– Press Enter to accept the default.
– Enter NO to disable triple-prime key generation.
– Enter YES to enable triple-prime key generation.
displayed.
export MQSECURE_MULTIPRIME_KEYS=YES

To configure an OS/390 node to use three primes instead of two to generate
key pairs, set
MQSECURE_MULTIPRIME_KEYS=
to
MQSECURE_MULTIPRIME_KEYS=YES
If the variable is not defined or is set to NO, PathWAI Secure-issued RSA key
pairs are generated using two primes.
If the variable is set to YES, key pairs are generated using three primes.

Message-Embedded Certificates
Overview
Embedding the public key certificate of a message signatory in the MQSecure
message itself makes it possible for a receiver to verify a digital signature
without having to access an MQSecure LDAP repository or a previously
imported public key. Multiple certificates may be sent with a message to
enable the receiver to establish a verification chain to an established local trust
point.
When a message is received, any embedded certificates are used to verify the
signature on the message and, if necessary, replace the certificate and public
key associated with the signatory in the local MQSecure database. If the signer
does not already exist in the local user key database, a new “foreign” user is
registered. If the receiver has an LDAP repository configured, the public key
information is written to it.
You can configure certificate embedding on either a node-by-node or a
channel-by-channel basis.
Note: You do not need enable message embedding to exchange keys via
certificates between nodes connected by a channel using the PathWAI
Secure security exits (that is, for platform or channel mutual
authentication). At channel startup, the security exits automatically
embed (as available) the full chain of certificates with each security
exchange message. However, you must have imported a common
certificate, such as a ValiCert root certificate, into each node’s PathWAI
Secure certificate database for this operation to be successful.
See “Embedding public keys in messages” on page 122 for more information
on how message embedding works.
Configuring certificate embedding on a node-by-node basis

To enable or disable message embedding of certificates, you specify one of
the following values:

ALWAYS Certificates are always embedded.

If a certificate for a signatory cannot be retrieved, the signing
operation will fail with the error code
USER_CERTIFICATE_REQUIRED
AS AVAILABLE Certificates are embedded only if the signatory has a
certificate in the local database
NEVER (default) Certificates are never embedded
To embed a chain of certificates, you must specify one of the following values:
ONE (default) Embed only the certificate of the user who signed the
message
TRUSTED Embed only the minimum chain required to certify back to
certificates in the PathWAI Secure trusted certificate
database
ROOT Embed the entire chain back to the self-signed (root)
certificate in the trusted certificate database or the last
certificate in the database
If message embedding is enabled, the certificates necessary to verify the

signatures on the embedded certificates or certificate chains must already be
present in the trusted database of the receiving node (or available in an LDAP
repository to which the node has access). If NEVER is specified, no
embedding takes place, even if values are specified for the certificate chain.
The two communicating nodes must have their keys issued by either a
common certificate authority (CA) or by a CA whose verification chain
originates from a common CA, and that the common CA’s root certificate
must be present in each local PathWAI Secure trusted certificate database.
(See “Importing certificates” on page 126 for information on importing
trusted certificates.)
Specifying certificate embedding on a channel-by-channel basis

Specifying certificate embedding on a channel-by-channel basis overrides any
settings for the node. (For more information on configuring channel exits for

PathWAI Secure security functions, see “Securing Messages Using PathWAI

Secure Channel Exits” on page 148.)
To specify embedding on a channel-by-channel basis, an WebSphere MQ
administrator adds the following to the MSGDATA parameter of the sending
channel:
Cn
where n is a number derived by choosing one of the following options:
1 = AS AVAILABLE
2 = ALWAYS
3 = NEVER
and adding it to a number from the following choices:
00 = ONE
10 = TRUSTED
20 = ROOT
For example:
MSGDATA(AC01)
instructs PathWAI Secure to sign every message and send its certificate, if
available.
MSGDATA(AC11)
instructs PathWAI Secure to sign every message send its certificate, as well as
a supporting chain of certificates back to a trusted level, if they are available.
Note that if NEVER (3) is specified, no embedding takes place, regardless of
other values specified. For example, in
MSGDATA(AC23)
no embedding takes place, so specifying root as the end of the certificate
chain has no effect.

To enable or disable certificate embedding:


the dropdown menu for the Embed Public Key Certificate field and
select:
– NEVER (default) to disable certificate embedding.
– AS AVAILABLE to embed certificates only when available.
– ALWAYS to always embed certificates. If no certificates are available,
the operation will fail.
3. Click the dropdown menu for the Embed Certificate Chain field and
select:
– ONE to embed only the signer’s public key certificate.
– Select TRUSTED to embed a chain of verification certificates up to the
first certificate designated as trusted.
– Select ROOT to embed a chain of certificates up to a root (self-signed)
certifcate.
processes.

To enable or disable generation certificate embedding:
MQConfig
the dropdown menu for the Embed Public Key Certificate field and
select:

– NEVER to disable certificate embedding.

– ALWAYS to always embed certificates. If no certificate is available, the
operation will fail.
3. Click the dropdown menu for the Embed Certificate Chain field and
select:
– TRUSTED to embed a chain of verification certificates up to the first
certificate designated as trusted.
– ROOT to embed a chain of certificates up to a root (self-signed)
certifcate.
5. Issue the appropriate export commands from the command line or by
export MQSECURE_EMBED_PUBLIC_KEY_CERTIFICATE=ALWAYS
export MQSECURE_EMBED_CERT_CHAIN=TRUSTED

To enable or disable certificate embedding in messages:
MQConfig -l
2. At the prompt
MQSECURE_EMBED_PUBLIC_KEY_CERTIFICATE (Default is:
current_default):
enter

– NEVER to disable certificate embedding.

– ALWAYS to always embed certificates. If no certificate is available, the
operation will fail.
3. At the prompt
MQSECURE_EMBED_CERT_CHAIN (Default is: current_default):
enter
certifcate.
displayed.
export MQSECURE_EMBED_PUBLIC_KEY_CERTIFICATE=AS_AVAILABLE
export MQSECURE_EMBED_CERT_CHAIN=TRUSTED

To configure certificate embedding on an OS/390 node, set the variable
MQSECURE_EMBED_PUBLIC_KEY_CERTIFICATE=
to one of the following values:
– ALWAYS to always embed certificates. If no certificates are available,
the operation will fail
– AS_AVAILABLE to embed certificates only when available

– NEVER to disable certificate embedding (default)

If the environment variable is not present or has no value specified, certificates
are not embedded, even if present in the local database.
To embed a chain of certificates you must also set
MQSECURE_EMBED_CERT_CHAIN=
to one of the following values:
certifcate.

Queue Authorization using PathWAI Secure Sender ID
Extending channel security

This option allows you to restrict access to a queue to a specific channel user.
If this option is set:
n On Server-connection (SVRCONN) channels, the sending PathWAI
Secure user ID is substituted in the channel definition for any existing user
specified in the MCAUSER keyword variable. This forces authorization to
queues targeted by MQPUT requests from the receiver channel MCA to be
implemented under the security attributes of the PathWAI Secure user ID
used to secure messages at the client side of the client connection.
n On Queue Manager connection channels (RCVR, RQSTR, CLUSRCVR),
the sending PathWAI Secure user ID is substituted in the message
descriptor UserIdentifier of each message passing through the channel.
This forces authorization to queues targeted by MQPUT requests from the
receiver channel MCA to be implemented under the security attributes of
the PathWAI Secure user ID used to secure messages at the Sender,
Server, or Cluster-Sender channel on the other side of the connection.
This option requires that the PathWAI Secure security exit be specified on the
channel definition (see “Securing WebSphere MQ Messages Using Channel
Exits” on page 147). Message exits are required for Queue Manger
connections when using channel security with a PathWAI Secure sender user
ID.
Note: On Queue Manager connections, the Put Authority in the channel
definition must also be set to PUTAUT(ALTMCA) for OS/390
receiver-side channels, or PUTAUT(CTX) for non-OS/390
receiver-side channels. If this is not the case, the channel is not started
and a message is issued to the PathWAI Secure channel exit log.

To enable or disable queue authorization based on the PathWAI Secure user
ID of the sender:


the dropdown menu for the Channel Security field and select
– MQSECURE SENDER to enable authorization based on sender ID.
– NONE to disable authorization based on sender ID.
processes.

To enable or disable queue authorization based on the PathWAI Secure user
ID of the sender:
MQConfig
the dropdown menu for the Channel Security field and select:
export MQSECURE_CHANNEL_SECURITY=MQSECURE_SENDER


MQConfig -l
2. At the prompt
MQSECURE_CHANNEL_SECURITY (Default is: current_default):
enter
modifying the login script to export the modified variable. For example:
export MQSECURE_CHANNEL_SECURITY=MQSECURE_SENDER

To use the PathWAI Secure user ID from the receiving side of the channel for
authorization to queues on the receiver side of Server-connection, Receiver,
Requestor, and Cluster Receiver channels, set
MQSECURE_CHANNEL_SECURITY=
to
MQSECURE_CHANNEL_SECURITY=MQSECURE_SENDER
If the environment variable is not present or has no value specified, queue
authorization is not enabled.

Symmetric Key Reuse
Symmetric Key Reuse
Overview
Reusing symmetric keys provides significant improvement in performance
without sacrificing security. You specify the number of reuses or the maximum
lifetime of the key, and the key is saved at the sender to be reused as
configured. On reuse, the saved key is used to encrypt the message and the
public key encryption operation is bypassed by placing the saved key into the
security trailer.
The following table shows the number of messages that can be encrypted and
decrypted based on the same amount of CPU resource and the number of
times the symmetric encryption key is reused.
Table 4. Symmetric Key Reuse
Number of Keys Number of Messages

Used Encrypted
1 1
5 4.9
10 9.4
100 60.4
1000 131.3
The table indicates that reusing the symmetric key for 100 encryptions and
decryptions will allow approximately 60 messages to be processed for the
same amount of CPU resource as a single encryption and decryption without
reuse.
The risk of queue depth build-up at the receiving platform is considerably
reduced or eliminated
Symmetric key reuse can be configured on a channel-by-channel or an
application-by-application basis. (For information on configuring symmetric
key reuse using the PathWAI Secure APIs, refer to the PathWAI Secure for
WebSphere MQ Programmer’s Guide.)

Symmetric Key Reuse
If this variable is not set, a new symmetric key is generated for each
encryption operation.
Specifying reuse of symmetric key

The MSGDATA parameter is used to specify how many times PathWAI Secure
should use the symmetric before regenerating it, or the period of time that
should elapse before the secret key is regenerated, or both.
Use:
K to specify the number of key reuses

T to specify the amount of time (in seconds)
For example, for a sending channel:

MSGDATA(AEK100)
tells PathWAI Secure to sign and encrypt all messages and to regenerate the
symmetric key after 100 uses.
MSGDATA(AET1000)
secret key every 1000 seconds.
MSGDATA(AEK100T1000)
secret key after 100 uses or 1000 seconds, whichever comes first.
The default is one use (K1).
Note: Symmetric key reuse needs to be specified only on the sender side of
the channel. The receiver automatically detects consecutive public
key encrypted symmetric keys as being the same and doesn’t use the
expensive private key decryption operation to expose the symmetric
key. As the symmetric key changes this is also detected by the receiver
and the securely cached copies of the public key encrypted symmetric
key and the symmetric key itself ("shrouded" by the receiver’s platform
symmetric key) are replaced for comparisons with the future incoming
messages until the next key change is detected. Therefore, it is not

Symmetric Key Reuse
necessary to specify anything the receiver node for incoming

messages.
Refer to “Securing WebSphere MQ Messages Using Channel Exits” on page
147 for information on configuring security features using MSGDATA.

3 Managing Users and User Keys
Overview
This chapter discusses how users and user keys are managed in the PathWAI
Secure environment. It covers
n registration of PathWAI Secure administrators and users
n distribution of user keys
n verification and revocation of users keys
n management of PathWAI Secure user key databases
Chapter Contents
Managing Users and Keys in the PathWAI Secure Environment . . . . . . . . 92
Users, User IDs, and Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Registering a Global Administrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Registering Administrators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Registering Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
Distributing Public Keys and Certificates . . . . . . . . . . . . . . . . . . . . . . . . . 117
Revoking Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
Managing the Local User Key Databases . . . . . . . . . . . . . . . . . . . . . . . . 131
Managing Users and User Keys 91

Managing Users and Keys in the PathWAI Secure Environment
Managing Users and Keys in the PathWAI Secure

Environment
Overview
PathWAI Secure users are authorized through the process of registration.
During registration, a public/private RSA key pair is associated with an
PathWAI Secure user ID and a password for private key operations.
PathWAI Secure users and their keys are managed by a special class of users
known as administrators. The first user ID and password registered on each
node using the PathWAI Secure administrative utility becomes the
administrative ID and password for that system. The administrator’s ID and
password is required to:
n register users
n export and import public keys
n manage the local user key database
PathWAI Secure users may hold either PathWAI Secure-generated keys or
keys generated by a third-party certificate or registration authority (CA/RA).
The way in which users are verified depends on the type of key (PathWAI
Secure-generated or third-party) they hold.
Administrative utilities
Administrative functions are performed using one of the following utilities:
Windows and UNIX servers mqs_adm

Windows and UNIX clients mqs_admc
OS/390 KMFADM
mqs_adm and mqs_admc are command line utilities whose functions are
invoked through parameters. Each function has a series of prompts to help
you enter the required parameter values. You can also enter all the
parameters for a function on the command line at one time. This means that if
you need to perform multiple configuration tasks you can collect commands

in a single file and execute them all at once. The parameters and the syntax
for the commands are discussed in “Utilities” on page 187.
Figure 6 illustrates a typical mqs_adm session.
FIGURE 6. mqs_adm Session
KMFADM is the REXX equivalent of mqs_adm and mqs_admc. It invokes

a series of ISPF panels.
KMFADM is invoked from ISPF option 6. Figure 7 on page 94 shows the
KMFADM main menu.

FIGURE 7. KMFADM Main Menu
==============================================
KMFPADM0 PathWAI Secure Administration
User : MQSADMIN1 Select Administration Function Date: 2002/06/29
Terminal: 3278 Time: 15:26
UserData: CANDINST.PWSECURE.DATABASE
==============================================
Create/Specify user key database
Manage User Keys
Manage User Key Database
Manage Certificates
Manage LDAP Repository
==============================================
Select function using ’/’ and press ENTER Press END to exit.
COMMAND ===>
User keys
PathWAI Secure supports both PathWAI Secure-generated RSA key pairs and
keys issued by third party CA/RAs and their supporting certificates.
PathWAI Secure-generated keys offer simplicity and ease of use. They are
particularly useful when you want to secure a small number of channels
without incurring the overhead of certificate management. PathWAI
Secure-generated keys are suited to a self-contained environment, where
individual users are known and trust can be assigned implicitly rather than
explicitly. In such environments, use of PathWAI Secure-generated keys is
indicated unless company or industry standards require certificates.
Third-party keys are suitable for more complex security systems
encompassing business partners or customers, where verification to a
mutually trusted third party is desireable, no shared repository is feasible, or
security standards require certificates.

RSA keys use a modulus–exponent format. The RSA key length consists of
two different lengths (the private key length and the public key length), neither
of which has the same value as the modulus size. The modulus size is an input
to the RSA key pair values. The greater the modulus size, the greater the
length of the public/private key pair.
The default modulus for PathWAI Secure-generated key pairs is 1024 bits, but
you can use any modulus between 768 and 2048 bits. The modulus size is set
on a node-by-node basis (see “Asymmetric Key Length” on page 54), but can
be overridden at the time keys are generated.
PathWAI Secure databases

PathWAI Secure maintains several databases on each node. These databases
are created as part of the process of registering a local administrator. For
security purposes, these databases should be backed up regularly.
Local user key databases

Each instance of PathWAI Secure maintains information about the user IDs
and associated key pairs for its own users in a local encrypted database. This
user key database also contains user IDs and public keys for all “foreign” users
with which the host communicates, whether imported from a file, embedded
in a message, sent via a queue manager, or copied from a central LDAP
database.
On Windows and UNIX the user key database is a sequential file named
MQSS.USR. On OS/390 you assign a name to the user key database as part
of the process of registering an PathWAI Secure administrator for that system.
You can have multiple user key databases on OS/390.
Only PathWAI Secure can communicate with the user key database manager.
Nontrusted and trusted certificate database

The certificate databases are a collection of files with extensions like .cdx, .dbf,
and .fpt, representing internal Codebase tables.
The nontrusted certificate database contains certificates and certificate
revocation lists imported either directly through PKCS#12 files or from the
LDAP repository after posting by a Global Administrator. The certificates
represent all of the local and foreign PathWAI Secure users that have been

imported either via PKCS#7 or PKCS#12 files, through extraction from an

PathWAI Secure message, or automatically from the LDAP repository.
The trusted certificate database contains the certificates that act as the
end-points of certificate verification chains for an PathWAI Secure network.
These certficates must have been first imported by a Global Administrator
from PKCS#7 files as trusted and then imported to the local node from the
LDAP repository after posting by the Global Administrator or from a PKCS#7
file using the administrative utility.
To enhance performance, the entire database is cached.
User verification and revocation

For PathWAI Secure-generated keys, local administrators act as the certifying
authority. When local users’ public keys are exported for distribution to other
PathWAI Secure nodes, they are signed using the administrator’s private key.
When these keys are imported by other nodes, the administrator’s public key
is used to authenticate the signature and verify the identify of the key holder.
For this reason, administrators’ keys must be exchanged before users’ keys
can be exchanged.
Third-party keys are verified through certificates issued by third-party
certificate or registration authorities. Verification of third-party public keys on
any PathWAI Secure node requires a chain of verification to a certificate
designated as trusted by the site’s Global Administrator. Global Administrators
are administrators with the authority to designate imported certificates as
trusted. Local administrators can control which certificates are trusted by their
node by importing trusted certificates exported by the Global Administrator as
either trusted or untrusted. (For sites using PathWAI Secure-generated keys
and distributing keys via an LDAP repository, Global Administrators act as the
certifying authority for local administrators.)
Users holding third-party keys are revoked through certificate revocation lists
(CRLs). PathWAI Secure checks CRLs before any operation requiring
verification of a public key (authentication or encryption) is executed. If
PathWAI Secure is configured to use an OCSP responder, the responder is
queried for the revocation status of the public key certificate and any
certificates in the chain to a trusted certificate.

If you are using third-party keys, you should establish a policy for importing
and distributing CRLs from the issuing authorities on a regular basis.
Note: If you are using third-party public key certificates, by default there
must be a certificate revocation list (CRL) in the local database from
the issuer of the certificates. If there is no CRL, certificate verification
will fail and the authentication or encryption operations will not be
performed. You can disable CRL checking (see “Certificate
Revocation List Checking” on page 64), but this should be done only
for testing and in case of emergencies.

Users, User IDs, and Passwords
Users
From the standpoint of PathWAI Secure, a user can be any entity—a person,
a machine, an application, a channel, a group. PathWAI Secure distinguishes
two classes of users: regular users and administrators.
Administrators are intended to be role-based entities rather than actual
individuals. The first user ID and password registered on an PathWAI Secure
node becomes the administrative ID and password for that node. That ID and
password are required to execute most administrative functions, including
registering other users, exporting and importing keys, and managing the local
user key database.
The administrator’s private key is used to sign all public keys originating from
that node. When local users’ public keys are exported (to a file or a
repository), PathWAI Secure uses the local administrator’s private key to sign
the message containing the user keys. When the user keys are imported on
another PathWAI Secure node, PathWAI Secure authenticates the sending
administrator’s signature to ensure that the keys really originated at a trusted
source. For this reason, users’ public keys cannot be distributed until
administrators’ public keys have been exchanged between all communicating
nodes.
Sites using third-party keys or using an LDAP repository for public key
distribution must establish a special site administrator, known as a Global
Administrator.
Only a Global Administrator, using the administrative utility installed from the
Global Administrator’s CD, can designate certificates as trusted by the site for
purposes of verification of third-party keys.
For sites using PathWAI Secure-generated keys and distributing keys via an
LDAP repository, Global Administrators act as the certifying authority for all
other administrators. PathWAI Secure uses the Global Administrator’s private
key to sign the administrators’ public keys when they exported to the
repository, and uses the Global Administrator’s public key to authenticate the
keys when they are imported on other nodes.

The recommended way to administer the PathWAI Secure users is to treat the
Global Administrator as a subordinate certification authority. The Global
Administrator is tasked with establishing the trust chains required in the sphere
of his or her control. In most cases—certainly in a non-business-to-business
environment—there will probably be only two certificates in the verification
chain and these certificates would form the verification chain for all certificates
in that environment.
In other words, the registration of the Global Administrator would most likely
pull in the verification certificates required by all the other nodes in the
environment. In a business-to-business situation, the local Global
Administrator should be the one to initially receive the certificates from the
business partner that will be required to verify the certificates used in
communications between the businesses. So business partners should export
their certificates to the local Global Administrator, who then imports them as
trusted as necessary, exporting them to LDAP automatically, or manually,
depending on local policy.
User IDs
IDs play a critical role in key management and signature authentication.
PathWAI Secure uses IDs to locate keys in its secured, internal user key
database.
User IDs for PathWAI Secure-generated keys are assigned by the local
administrator. User IDs for third-party keys are derived by PathWAI Secure
from the Subject Name on the public key certificate. By default, PathWAI
Secure uses the Common Name (cn) portion of the Distinguished Name that
comprises the subject name of an X509v.3 certificate, but it can be configured
to use any of the component of a Distinguished Name (see “PathWAI Secure
ID Mapping” on page 60). In the case of special purpose IDs discussed below,
this means that you must ensure that the component of the Distinguished
Name used as the PathWAI Secure user ID conforms to the conventions
discussed below.
All PathWAI Secure user IDs must be unique systemwide. This prevents
conflicts with locally-defined PathWAI Secure user IDs when “foreign” user
IDs are imported to other nodes. Regular user IDs may consist of up to 47
alphanumeric characters and special characters !@#$%^&*. However, there

are restrictions on the IDs used for channel mutual authentication and for
WebSphere MQ clusters.
User IDs are case-sensitive on all platforms.
Note: If you are exchanging messages between OS/390 and other platforms,
you should create IDs in all uppercase, as WebSphere MQ changes the
casing of IDs to uppercase when it sends messages to other platforms
using channel exits. Many LDAP implementations are not case
sensitive. To avoid potential name collisions you should not specify
user IDs which are identical except for casing.
Channel authentication IDs

Channel authentication IDs are special-use PathWAI Secure user IDs created
specifically for use by the channel mutual authentication channel exit.
Channel authentication IDs are created in pairs, with each ID representing one
end of a specific channel.
The naming convention governing channel authentication IDs is strict. The
channel authentication IDs must be:
sender channel channelName.O
receiver channel channelName.I
The channel authentication ID for the sender end of a channel must be

defined on the sending platform. The channel authentication ID for the
receiver end of a channel must be defined on the receiving platform.
Channel authentication IDs are managed by PathWAI Secure in the same way
as user IDs. From the standpoint of key management, PathWAI Secure does
not differentiate between channel authentication IDs and regular user IDs.
Cluster authentication IDs

Cluster authentication IDs are special-use PathWAI Secure user IDs created
specifically for use by channel mutual authentication for cluster channels. For
each CLUSSDR/CLUSRCVR channel pair, three user IDs must be defined:
one representing the sending user, one representing the receiving user, and
one representing the receiving node. All three user IDs must specify the
channel name.

The naming convention governing cluster authentication IDs is strict. One ID

must be defined on sending platform, and two IDs must be defined on the
receiving platform as follows:
Channel Type Cluster Authentication ID

CLUSSDR SendingQMGRName.channelName.ReceivingQMGRName
CLUSRCVR ReceivingQMGRName.channelName.SendingQMGRName
CLUSRCVR ReceivingQMGRName.channelName
Cluster authentication IDs are managed by PathWAI Secure in the same way
as user IDs. From the standpoint of key management, PathWAI Secure does
not differentiate between cluster authentication IDs and user IDs.
Cluster IDs
To encrypt messages sent to an WebSphere MQ cluster, each member of the
cluster must be assigned an PathWAI Secure user ID with a shared prefix. For
example:
CLUS1QM1, CLUS1QM2, CLUS1QM2, . . .
The entire cluster can then be identified using the prefix and an asterisk
wildcard:
CLUS1*
When the destination user ID is specified in this manner, PathWAI Secure
encrypts the symmetric key with which the message is encrypted repeatedly,
using the public key of each member of the cluster in turn.
Viewing registered users and certificates
For various reasons you may need to review the user IDs for which public,
and possibly private, keys are known in the local PathWAI Secure user key
database.
To view a list of user IDs:
KMFADM Main Menu > Manage User Keys >

OS/390
List Users

Windows and UNIX mqs_adm -u, mqs_admc -u
In the displayed list:

LW indicates users exported to the LDAP repository
LI indicates users imported from the LDAP repository
LP indicates users pending export to the LDAP repository
R indicates users revoked in the local database but not in the LDAP
repository (for PathWAI Secure-generated keys)
LD indicates users revoked in both the local database and in the LDAP
repository (for PathWAI Secure-generated keys)
Note: The revocation status of third-party keys is not shown by the list users
command. If you want to see which third-party keys have been
revoked, you must check revocation lists issued by their certifying
authority.
To view a list of the certificates known in the local nontrusted certificate
database:
KMFADM Main Menu > Manage Certificates >

OS/390
List Certificates
Windows and UNIX mqs_adm -u -c, mqs_admc -u -c
To view a list of certificates in the local trusted certificate database:
KMFADM Main Menu > Manage Certificates >

OS/390
List Trusted Certificates
Windows and UNIX mqs_adm -u -c -t, mqs_admc -u -c -t
Passwords
Each PathWAI Secure user ID is associated with a password. The password is
required to use the private key associated with the user ID to sign or decrypt
messages.

Valid PathWAI Secure passwords may consist of up to 20 alphanumeric

characters or special characters !@#$%^&*.
Passwords are assigned by an administrator during registration, but may be
changed at any time.
To change a password:
KMFADM Main Menu > Manage User Keys> Change

OS/390
Password
Windows and UNIX mqs_adm -p or mqs_admc -p
Passwords may also required to access the private key information in

PKCS#12 files. The passwords required for files supplied by a third-party
certificate or registration authority must be acquired from the issuing
authority.
When exporting keys to a PKCS#12 file, PathWAI Secure administrators can
supply a password or have PathWAI Secure generate one randomly. Explicitly
specified passwords can be any printable character. Passwords created by
PathWAI Secure consist of a combination of 19 characters in the range a–z,
A–Z, 0–9, $,@, and #. The password must be securely transmitted to the
receiver importing the file.

Registering a Global Administrator
Overview
If you intend to use third-party keys, or to use an LDAP repository for key
distribution, your site must have a Global Administrator. Only a Global
Administrator can establish the end points for verification of public key
certificates for your site by designating certain verification certificates as
trusted certificates. If you are using PathWAI Secure-generated keys and your
site is configured to use an LDAP repository, the Global Administrator can
play a central role in the distribution of administrators’ public keys (see
“Distributing Public Keys and Certificates” on page 117). In order to
designate certificates as trusted, a Global Administrator must be registered
using the special Global Administrator CD. (If you are designating a Global
Administrator only for central distribution of PathWAI Secure-generated keys,
you do not have to register the Global Administrator using the special CD.)
Registering the Global Administrator should be the first step in setting up your
PathWAI Secure infrastructure. If you are using third-party keys, no other
administrators can be registered until the Global Administrator has imported
and distributed the trusted certificates required to verify the administrators’
public keys.
Registering a Global Administrator initializes the PathWAI Secure
environment in the same way as registering any administrator: The process
establishes the administrative ID and password for that node and initializes the
local user key database. All subsequent sessions using the administrative
utility on the node are validated against the Global Administrator’s ID and
password. The Global Administrator becomes the certifying authority for any
PathWAI Secure-generated keys originating from this node. Only the Global
Administrator, however, can export certificates as trusted.
Since keys exported to the LDAP repository are signed using the local
administrator’s private key, if you are using PathWAI Secure-generated keys
and an LDAP repository, the Global Administrator can act as the certifying
authority for local administrators by exporting their keys to the LDAP
repository.

The process of registering a Global Administrator should be completed when

PathWAI Secure is installed. Step-by-step instructions are given in the
PathWAI Secure for WebSphere MQ Installation Guide.
Notes: If you have configured the PathWAI Secure node to connect to an
LDAP repository, you must have a viable connection to the
repository to generate or import keys successfully.
If the node is configured to use an LDAP repository, you are
prompted for the user ID and password PathWAI Secure should use
to access the LDAP repository when you register an administrator.
You must enter the LDAP user ID prefixed by cn=. For example:
Using PathWAI Secure-generated keys

On OS/390 , you must supply a name for the user key database
(Create/Specify user key database) before you can register an
administrator.
To register Global Administrator and have PathWAI Secure generate the
administrator’s keys:
OS/390 KMFADM Main Menu > Create/Specify user key

database
Windows and UNIX mqs_adm -s, mqs_admc -s
On OS/390 you will see a panel asking you whether you want to generate your
administrator’s key using a PKCS#12 file (third-party key), or have PathWAI
Secure generate the key for you. Select “Register Administrator using
PathWAI Secure generated keys.” You are then asked to specify the
administrator ID and password to be associated with these keys (see “Users,
User IDs, and Passwords” on page 98 for a discussion of valid PathWAI
Secure user IDs and passwords). On OS/390 , you must also supply the name
of the configuration file holding the PathWAI Secure environment variables.
This name is specified during installation in the JCL used to start the Server
Address Space.

You can override the default key length by specifying the modulus size for the
OS/390 Specify the desired modulus size in the RSA Modulus Size
field on the New Adminid Signon panel
Windows and UNIX Use the switch -l to specify the modulus size
(mqs_adm(c) -s -l modulus_size)
You can use any modulus size between 768 and 2048 bits, but the value
should be divisible by 8. See “Asymmetric Key Length” on page 54 for more
information on determining key length by setting modulus size.
If you are using PathWAI Secure-generated keys, the Global Administrator’s
public key should be exported to a file that is securely transmitted to all other
PathWAI Secure nodes (see “Exporting keys to a flat file” on page 119) and
imported into the local user key databases (see “Importing public keys” on
page 124).
Using third-party keys

If your site is using imported third-party key pairs, the certifying authority
issuing the keys must securely communicate the following to your site before
the Global Administrator is registered:
n the PKCS#12 file containing the Global Administrator’s public/private key
pair and supporting certificates
n the password used to encrypt the PKCS#12 file, if any
n the PKCS#7 (or DER-encoded) format file containing the certificates that
will be used to verify other user keys for the site and any current CRLs
On OS/390 , you must supply a name for the user key database
(Create/Specify user key database) before you can register the
administrator.
Note: You cannot import third-party keys into an exisiting database. You
must delete any existing database before you attempt to initialize a
database with a third-party key.

To register a Global Administrator using an imported public/private key pair:
OS/390 KMFADM Main Menu > Create/Specify user key

database
mqs_adm -s -f pkcs#12filename, mqs_admc -s -f
Windows and UNIX
pkcs#12filename
On OS/390 you will see a panel asking you whether you want to generate your
administrator’s key using a PKCS#12 file (third-party key), or have PathWAI
Secure generate the key for you. Select “Register Administrator using third
party generated keys.” You will need to supply the name of the PKCS#12 file
containing the keys and verification certificates and the password required to
decrypt the private key information in the PKCS#12 file, if any.
PathWAI Secure extracts the user ID to be associated with the key pair from
the certificate (see “User IDs” on page 99 for how PathWAI Secure determines
the user ID), but you provide the password to be used for private key
operations (see “Passwords” on page 102 for a discussion valid passwords).
On OS/390 , you must also supply the name of the configuration file holding
the PathWAI Secure environment variables. This name is specified during
installation in the JCL used to start the Server Address Space.
After you enter the name of the PKCS#12 file to be imported, PathWAI
Secure displays the subject name on the certificate. The PathWAI Secure user
ID assigned to the key pair is the value of the attribute specified for the
MQSECURE_ID_MAPPING_ATTRIBUTE variable. (By default, this is the
common name attribute: cn=). Be sure to record this ID and password and
store them in a secure location.
If your site is configured to use an LDAP repository, the Global
Administrator’s public key certificate is automatically exported to the
repository. If you are not using an LDAP repository, the Global
Administrator’s public key certificate must be manually exported to a
PKCS#7 file and imported on other PathWAI Secure nodes (see “Exporting
certificates to a PKCS#7 file” on page 123). If the Global Administrator’s
certificate is to act as the end point in a chain of certificate verification, the
certificate must be flagged as trusted and exported either to the LDAP
repository or to a file and imported into the local trusted certificate database
(see “Exporting keys to an LDAP repository” on page 118, “Exporting

certificates to a PKCS#7 file” on page 123, and “Importing certificates” on

page 126).
Importing trusted certificates

In a PathWAI Secure infrastructure which uses third-party keys, each node
must be able to establish a chain of verification from a “foreign” user’s public
key to a certificate in its local trusted certificate database. Local administrators
can import as trusted only those certificates which have been imported as
trusted by the site’s Global Administrator and exported with a trust flag to the
LDAP repository or to other PathWAI Secure nodes.
Before other administrators can be registered using imported third party keys,
the Global Administrator must import and distribute the certificates required
to verify their public keys.
The certificates that will be designated as trusted for your PathWAI Secure
environment are usually imported as part of registering the Global
Administrator, but you can always import additional certificates as required.
To import stand-alone verification certificates and flag them as trusted:
OS/390 KMFADM Main Menu > Manage Certificates >

Import Certificates from a PKCS#7 File
mqs_adm -i -c -f pkcs#7filename -t, mqs_admc
Windows and UNIX
-i -c -f pkcs#7filename -t
The certificates will be extracted from the file and placed in the trusted
certificate database.
Note that some of the certificates in the PKCS#7 file may already have been
imported as part of the chain of verification certificates included in the
PKCS#12 file containing the Global Administrator’s keys. Those certificates,
however, were placed in the nontrusted databased. To be placed in the trusted
database, they must be explicitly imported as trusted.
If PathWAI Secure is configured to use an LDAP repository, certificates
imported by the Global Administrator as trusted are automatically exported to
the repository and copied to local trusted certificate database the first time
they are needed to verify a signature. If PathWAI Secure is not configured to
use an LDAP repository, the certificates must be exported by the Global

Administrator to a PKCS#7 file (see “Exporting certificates to a PKCS#7 file”

on page 123) and imported on each platform as trusted certificates (see
“Importing certificates” on page 126).

Registering Administrators
Overview
Registering an administrator initializes the PathWAI Secure environment on
that node. The process establishes the administrator’s ID and password and
initializes the local user key database. All subsequent sessions using the
administrative utility on the node are validated against the administrator’s ID
and password, and the administrator’s signature is used to certify any
PathWAI Secure-generated keys originating from that node.
The local administrator should be registered at the time PathWAI Secure is
installed on a node so that the installation can be verified. Consult the
PathWAI Secure for WebSphere MQ Installation Guide for detailed
instructions.
to access the LDAP repository when you register an administrator.

On OS/390 , you must supply a name for the user key database before you can
register an administrator (Create/Specify user key database).
To register an administrator and have PathWAI Secure generate the
OS/390 KMFADM Main Menu > Manage Users > Register

Administrator using PathWAI Secure generated
keys
Windows and UNIX mqs_adm -s, mqs_admc -s

You specify the ID and password to be associated with these keys (see “Users,
Secure user IDs and passwords). On OS/390 , you must also supply the name
of the configuration file holding the PathWAI Secure environment variables.
This name is specified during installation in the JCL used to start the Server
Address Space.
OS/390 Specify the desired modulus size in the RSA

Modulus Size field on the New Adminid Signon
panel
You can use any modulus size between 768 and 2048 bits, but the value
should be divisible by 8. See “Asymmetric Key Length” on page 54 for more
information on determining key length by setting modulus size.
When users’ public keys are imported on another PathWAI Secure node,
PathWAI Secure authenticates the sending administrator’s signature to ensure
that the keys really originated at a trusted source. For this reason, the
administrator’s public key must be distributed to all communicating nodes
before any user keys generated on the node can be distributed.
Administrators cannot export their own keys to an LDAP repository. If your
site is using an LDAP repository, the administrator’s key should be exported to
a file and securely transmitted to the site’s Global Administrator. The Global
Administrator can then export the administrator’s key to the repository (see
“Exporting keys to an LDAP repository” on page 118).
If your site is not using an LDAP repository, the administrator’s key should be
exported to a flat file and securely distributed to and imported on all other
PathWAI Secure nodes with which it will be communicating (see “Exporting
keys to a flat file” on page 119).


If an administrator is being registered using an third-party key pairs, the
PKCS#12 file containing the keys and any supporting certificates must be
obtained from the certifying authority (or the site’s Global Administrator, if
you are centralizing distribution of keys) before the administrator is registered.
If the private key information in PKCS#12 file is password encrypted, the
password must also be obtained from the certifying authority.
On OS/390 , you must supply a name for the user key database before you can
register an administrator (Create/Specify user key database).
Note: You cannot import third-party keys into an exisiting database. You
must delete any existing database before you attempt to initialize a
database with an imported key.
To register an administrator using an imported public/private key pair,
registration is initiated using the command:
OS/390 KMFADM Main Menu > Manage Users > Register

Administrator using third party generated
keys
mqs_adm -s -f pkcs#12filename, mqs_admc -s -f
Windows and UNIX
pkcs#12filename
You will need to supply the name of the PKCS#12 file containing the keys
and verification certificates assigned to the administrator and the password
required to decrypt the private key information in the PKCS#12 file, if any.
the certificate (see “User IDs” on page 99 for a discussion of how PathWAI
Secure determines user IDs), but you specify the password to be used for
private key operations (see “Passwords” on page 102 for a discussion of valid
passwords.) On OS/390 , you must also supply the name of the configuration
file holding the PathWAI Secure environment variables. This name is specified
during installation in the JCL used to start the Server Address Space.

store them in a secure location.
If your site is configured to use an LDAP repository, the administrator’s public
key certificate is automatically exported to the repository. Any supporting
certificates imported from PKCS#12 file, however, must be manually
exported to the repository. If the administrator's PKCS#12 file contains
supporting certificates that are not already in the chain of verification
established by the Global Administrator at registration, the local administrator
must export those certificates in a PKCS#7 file to the Global Administrator,
who then exports them to the LDAP repository.
Individual node administrators will become trusted users as they are
automatically imported from LDAP by other nodes and verified to a trust
point.
If you are not using an LDAP repository, the administrator’s public key
certificate (and its verification certificates) must be manually exported to a
PKCS#7 file and imported on other PathWAI Secure nodes (see “Exporting
certificates to a PKCS#7 file” on page 123).

Registering Users
Registering Users
Overview
Registering a new user involves:
1. Importing or generating a public/private key pair
2. Assigning the user ID (if necessary) and password
3. Exporting the user’s public key to a file or target systems
4. Importing the user’s public key on target systems
Only administrators can register other users. If PathWAI Secure is configured
to use an LDAP repository, steps 3 and 4 are performed automatically.
to access the repository. You must enter the LDAP user ID prefixed
by cn=. For example:

To register a user using PathWAI Secure-generated keys:
KMFADM Main Menu > Manage Users > Add a New

OS/390
User
Windows and UNIX mqs_adm -g, mqs_admc -g
You specify the ID and password to be associated with these keys. See “Users,
Secure user IDs and passwords.

Registering Users
keys:
OS/390 Specify the desired modulus size in the RSA

Modulus Size field on the New Adminid Signon
panel
If PathWAI Secure is configured to use an LDAP repository, user public keys

are automatically signed using the administrator’s key and exported to the
repository.
If you are not using an LDAP repository, users keys must be distributed to
other PathWAI Secure nodes by exporting them to a queue or file, and
importing them into the local user key database. For more information, see
“Distributing Public Keys and Certificates” on page 117.

If you are registering a user with a third-party key pair, the PKCS#12 file
containing the keys and any supporting certificates must be obtained from the
certifying authority (or the site’s Global Administrator, if you are centralizing
key distribution) before the user is registered.
The private key information in PKCS#12 files may be password encrypted. If
so, the password must also be obtained from the certifying authority.
To register a user using an imported public/private key pair:

Import Users/CRLs from a PKCS12 File
mqs_adm -g -f pkcs#12filename, mqs_admc -g -f
Windows and UNIX
pkcs#12filename
The password required to decrypt the private key, if required, must be

supplied before the file can be imported successfully.
the certificate (see “User IDs” on page 99 for a discussion how PathWAI

Registering Users
Secure determines user IDs), but the administrator assigns the password to be
used for private operations (see “Passwords” on page 102 for a discussion of
valid PathWAI Secure passwords).
store them in a secure location. The password must be communicated to the
user, if the user is an actual person, or to the application programmer, as
required for signing and decryption operations.
If your site is configured to use an LDAP repository, the user’s public key
certificate is automatically exported to the repository. If you are not using an
LDAP repository, the user’s public key certificate must be manually exported
to a PKCS#7 file and imported on other PathWAI Secure nodes (see
“Exporting certificates to a PKCS#7 file” on page 123).

Distributing Public Keys and Certificates
Overview
In public key cryptography, reciprocal functions are performed using opposite
members of a public/private key pair: Senders use their private keys to sign
messages, and receivers use the senders’ public keys to authenticate their
signatures. Conversely, senders use intended receivers’ public keys to encrypt
messages, and receivers decrypt the messages using their private keys.
Therefore, before communicating parties can sign and authenticate or encrypt
and decrypt messages, they must exchange public keys directly or make them
available in a repository accessible to all authorized parties. If the keys are
verified by a third-party certifying authorities, users’ must also have access to
the chain of certificates that authenticate the keys.
Since administrators’ public keys are used to verify public keys originating
from their nodes, their keys must be exchanged between all communicating
nodes before users’ keys can be exchanged.
Note: If you are using third-party keys, you do not need to exchange the
public keys used for platform or channel mutual authentication. At
channel startup, the security exits automatically embed (as available)
the full chain of certificates with each security exchange message.
However, you must have imported a common certificate, such as a
ValiCert root certificate, into each node’s trusted certificate database
for this operation to be successful.
PathWAI Secure supports four methods of distributing public keys:
n via an LDAP repository
n in flat file
n via an WebSphere MQ queue manager
n embedded in a message
In addition, PathWAI Secure allows you to
n export public/private key pairs and supporting certificates in a
password-encoded PKCS#12 file
n export stand-alone (“verification”) certificates in a signed PKCS#7 file

Until administrators’ keys have been exchanged, there is no way to use

WebSphere MQ to distribute public keys securely. For this reason Candle
recommends that you either use an LDAP repository to distribute
administrators’ key, or you export them to a file that can be securely
transmitted by other means.
Exporting keys to an LDAP repository

If your PathWAI Secure environment is configured to use an LDAP repository,
users’ public keys (and supporting certificates, if any) are automatically
exported to the repository when users are registered. Third-party
administrators’ keys are also automatically exported to the repository at
registration. However, PathWAI Secure-generated administrators’ keys must
be manually exported to the respository using the export to LDAP command,
and administrators cannot export their own keys.
(Third-party administrator keys can be automatically exported because the
nodes importing the key can use the trusted certificates they have already
imported to verify the certificate from these administrators. If administrators
try to introduce themselves into the network without having verification back
through a path of trusted certificates, the import to other nodes will fail and
security operations will not be performed with those administrators in the
verification path. PathWAI Secure-generated administrator keys, however,
must be “verified” by another admininstrator.)
If you are using PathWAI Secure-generated administrator keys, you should
designate a Global Administrator to be responsible for exporting
administrators’ keys to the LDAP repository. (Note that if you are using both
PathWAI Secure-generated and third party administrator keys, you must
designate a Global Administrator, see “Users” on page 98.) The Global
Administrator’s public key should be exported to a file and a copy transmitted
securely to every PathWAI Secure node. Local administrators’ keys should be
exported to a flat file and transmitted securely to the Global Administrator (see
“Exporting keys to a flat file” on page 119). The Global Administrator can
then import the files and export the administrators’ keys to the repository
using the export to LDAP command.
Local administrators can also use the export to LDAP command to manually
export users’ keys generated while the LDAP repository was unavailable, or

keys created under a previous version of PathWAI Secure to be exchanged

with new installations.
Note: No administrative functions can be run against a database created by a
previous version of PathWAI Secure unless the database has been
converted using kmfconv. See the PathWAI Secure for WebSphere
MQ Installation Guide for details.
To export public keys to an LDAP repository:
OS/390 KMFADM Main Menu > Manage LDAP Repository >

Export Local Public Keys
Windows and UNIX mqs_adm -e -r, mqs_admc -e -r
Note: PathWAI Secure does not allow you to export revoked users to the
LDAP repository. It also does not allow you to export users to the
LDAP repository which you have previously imported from the
repository.
Exporting keys to a flat file

Public keys can also be distributed by exporting the user’s public key and
supporting certificates, if any, to a flat file.
On Windows and UNIX , this file is normally written to a diskette, so that it may
be physically carried to another system and then imported from the diskette to
the local database.
On OS/390 systems, public keys are written to a file, which can be transferred
in binary format to another system and imported into the local database.
Administrator keys should always be distributed in this manner (or exported
to an LDAP repository as discussed above), rather than using a queue
manager. Until an PathWAI Secure administrator has been registered on the
receiving system, messages cannot be signed, and any tampering that occurs
while they are being transmitted across the network will not be detectable.
Therefore, a transportable medium is a more secure method for transmitting
adminstrative public keys.

To export a public key to a file:
OS/390 KMFADM Main Menu > Manage Users > Export

Admin/User > Export user to file
Windows and UNIX mqs_adm -e -f filename, mqs_admc -e -f

filename
On OS/390 , specify the fully qualified name of the dataset, without quotes.
You do not need to preallocate the dataset. If you specify a partitioned
dataset, the member name is required. For example:
CANDLE.MQSECURE.EXPORTS(MEMBER)
On Windows and UNIX , to specify a directory other than the current directory,
specify the full path name in the command. For example:
c:\mqs_adm -e -f \candle\mqsecure\export_users
\mqs_adm -e -f /home/mqsecure/export_users
Public keys exported to a flat file must be manually imported into the user key
database on each target system (see “Importing public keys” on page 124).
Exporting keys via a queue manager

The third method of distributing public keys is through an WebSphere MQ
queue manager. When you distribute keys using this method, PathWAI Secure
creates a message signed using the administrator’s private key. The message is
sent to an WebSphere MQ queue on the target machine called
SYSTEM.MQSECURE.COMMANDS. This queue is set up by the WebSphere
MQ administrator specifically to receive signed messages containing public
keys sent by other systems.
All messages containing new public keys (or invalidating old PathWAI
Secure-generated public keys) trigger the PathWAI Secure program
Windows and UNIX mqs_read or OS/390 KMFREAD. The program requests
the appropriate action (addition or revocation) by PathWAI Secure, which
then updates the local PathWAI Secure user key database.
If you want to export public keys to target systems using a WebSphere MQ
queue manager, the WebSphere MQ administrator must first:

1. Set up a queue named SYSTEM.MQSECURE.COMMANDS on the target

machine(s).
2. Create an initialization queue where the queue manager will place trigger
messages related to the SYSTEM.MQSECURE.COMMANDS queue. (You
can also use an existing initialization queue.)
3. Define a trigger process specifying Windows and UNIX mqs_read or OS/390
KMFREAD as the application to be invoked by the trigger monitor.
4. Specify the trigger attributes for the SYSTEM.MQSECURE.COMMANDS
queue (trigger options, process definition, initiation queue).
When triggering conditions are fulfilled, the trigger monitor invokes the
program, which updates the user key database by processing all messages in
the SYSTEM.MQSECURE.COMMANDS queue.
Note: The WebSphere MQ administrator should ensure that the
SYSTEM.MQSECURE.COMMANDS queue is sufficiently secured.
This is especially important in client/server configurations, where each
PathWAI Secure client can be an PathWAI Secure administrator. Refer
to WebSphere MQ administration documentation, as needed.
To export keys using a queue manager:
OS/390 KMFADM Main Menu > Export admin/users >

Export user to q-mgr <q-name>
Windows and UNIX mqs_adm -e -m q-mgr -q <q-name>
Specify q-mgr (queue manager name) and q-name (queue name) using these
guidelines:
– The queue manager name parameter can be either the remote queue
manager (the target system) or a local queue manager.
– If you specify a remote queue manager, you do not need to specify a
queue name, as this defaults to SYSTEM.MQSECURE.COMMANDS.
The message is put to a local default queue manager. This means that
there must be a transmit queue with the same name as the remote
queue manager and the sending channel of the local default queue
manager must use the transmit queue.

– If the queue manager name parameter specifies a local queue

manager, then the queue name must be the name of the local
definition of a remote queue, which points to
SYSTEM.MQSECURE.COMMANDS on the target system.
Note: This function is not available on PathWAI Secure clients.
Embedding public keys in messages

PathWAI Secure also lets you embed the public key certificate of a message
signatory in a PathWAI Secure message. This makes it possible to verify a
digital signature without having access to a shared LDAP repository or to
previously imported public keys. Multiple certificates may be sent with a
message to establish a verification chain to an established local trust point.
When a message is received, PathWAI Secure uses any embedded certificates
to verify the signature on the message and, if necessary, replace the certificate
and public key associated with the signatory in the local database. If the
receiver has an LDAP repository configured, the public key information is
written to it.
Receivers attempt to verify a message signature in the normal way through
first looking in the local user key database, then the LDAP repository. If the
user is not found, the certificate embedded in the message is used to verify the
signature after first being itself verified to an established trust point or root
certificate.
If a previously inserted public key associated with the certificate differs from
the key in the certificate, the public key from the certificate and the certificate
itself will replace the existing copies. This replacement occurs only if the
signature verification fails when using the local keys and the more recent
certificate is verified through the local certificate chain. The replacement
certificate must be more recently issued than the existing one.
The certificates necessary to verify the signature on the embedded certificate
or certificate chain must already be present in the local databases of the
receiving node. These certificates must either have been imported into the
receiving node via a PKCS#7 file, or be available in an LDAP repository to
which the node has access.
Message-embedded certificates are verified to a trust-point established at the
receiving platform. The certificate that acts as a trust-point must be located in

the local trusted certificates database. This database is populated by

certificates exported by the Global Administrator and imported by the local
administrator with the trust flag set.
The sending and receiving nodes must have their keys issued either by a
common certifying authority or by a certifying authority whose verification
chain originates from a common certifying authority. The public key certificate
for the common authority must be present in each local PathWAI Secure
database.
Message embedding can be configured for channels on a node-by-node or on
a channel-by-channel basis through an environmental variable (see the
section of “Message-Embedded Certificates” on page 78 for your platform).
Exporting private key/public key certificate pairs to a PKCS#12 file

In addition to exporting public keys or public key certificates, PathWAI Secure
can also export private key/public key certificate pairs to a
password-encrypted PKCS#12 file. This command gives you the opportunity
to establish central distribution of administrator keys and is typically used only
by a Global Administrator to distribute administrators’ imported key pairs.
To export third-party private/public key certificate pairs to a PKCS#12 file:
OS/390 MFADM Main Menu > Manage Certificates >

Export users to a PKCS12 file
mqs_adm -e -y -f pkcs#12filename, mqs_admc -e
Windows and UNIX
-y -f pkcs#12filename
When the command is entered, the administrator is prompted to supply an

encryption password. If no password is entered, a random one is generated,
used to encrypt the private key, and displayed. You should record the
password and communicate it securely to the receiver along with the
PKCS#12 file.
Exporting certificates to a PKCS#7 file

If your PathWAI Secure infrastructure uses a central LDAP repository, any
certificates imported by an administrator from either PKCS#12 or PKCS#7

files are automatically exported to the repository and copied into local
databases as they are required.
However, if for some reason you cannot distribute certificates through a
shared central repository—as may be the case in many business-to-business
situations—administrators can export selected certificates in a signed
PKCS#7 format message.
Note: The signer of a PKCS#7 message must be using a third-party private
key/public key pair verified through a certificate or certificates.
To export certificates to a PKCS#7 file:
OS/390 MFADM Main Menu > Manage Certificates >

Export certificates to a PKCS7 file
mqs_adm -e -c -f PKCS#7filename, mqs_admc -e
Windows and UNIX -c -f PKCS#7filename
Windows and UNIX Local administrators are presented with a list of all PathWAI
Secure users (that is, those holding third-party public and private keys) and
must provide the user ID of the certificate holder and the name of the
PKCS#7 file to which the certificate should be exported. The Global
Administrator is presented with a list of all certificates stored in both trusted
and nontrusted databases, including stand-alone, or verification, certificates,
not just the certificates for PathWAI Secure users.
OS/390Local and Global administrators must know in advance the user IDs
they wish to export.
In addition to specifying the user ID and PKCS#7 file name, the Global
Administrator can also specify that the certificate be exported with a Trusted
flag. Local administrators cannot export stand-alone certificates nor export
certificates as trusted.
Typically, this command is used to export certificates needed to establish the
verification chain for message-embedded public keys.
Importing public keys

If your PathWAI Secure environment is configured to use an LDAP repository,
“foreign” administrators’ and user’s public keys (and CRLs) that do not
already exist in the local databases, and any supporting certificates, are

imported automatically from the LDAP repository as needed to encrypt a

message or to authenticate a signature.
Note: All public keys imported from the LDAP repository to the local
database are automatically refreshed whenever the server is started on
OS/390 and can also be refreshed periodically using the
administration utility. See “Refreshing the user key database” on page
132
Keys imported into the user key database by means other than LDAP
(flat file, queue manager) will not be automatically refreshed by LDAP
processing.
Public key certificates embedded in messages are also imported automatically
into the local databases (see “Embedding public keys in messages” on page
122).
Public keys exported using a queue manager are imported by the utility
program Windows and UNIX mqs_read or OS/390 MQSREAD. (See
“Exporting keys via a queue manager” on page 120 for details.)
However, public keys exported to a flat file must be manually imported into
the key database on each target system.
On OS/390 , exported keys must be FTP’d into a dataset on the target system.
You must pre-allocate the dataset into which the keys will be placed. The
dataset can be either partitioned (PDS) or sequential. It must have the
following DCB attributes:
Sequential file RECFM=VB, LRECL=255, BLKSIZE=4000, DSORG=PS
PDS RECFM=VB, LRECL=255, BLKSIZE=4000, DSORG=PO
In the case of a PDS dataset, if you do not allocate a member name, the
member name will be allocated dynamically. PDSs are particularly handy
because you allocate the dataset only once and can then target different
member names to contain keys from different platforms if you want.
Note: If you have already imported remote administrators’ public keys to this
system, the dataset has already been allocated.

To import a public keys exported to a flat file:
OS/390 KMFADM Main Menu > Manage Users > Import User
mqs_adm -i -f filename, mqs_admc -i -f

Windows and UNIX filename
On OS/390 , the name of the dataset from which the keys are being imported
must be fully qualified, without quotes. If a PDS is specified, the member
name is required.
On Windows and UNIX , to specify a directory other than the current directory,
you must specify the fully qualified name of the file from which the key is to
be imported into the database. For example:
mqs_adm -i C:\mqsecure\export\export_keys
mqs_adm -i /home/mqsecure/export_keys
Importing certificates
If certificates are stored in a central LDAP repository, they are automatically
imported to local nodes as needed to verify signatures. However, if your site
uses PKCS#7 files to distribute certificates, they must be imported onto local
nodes manually.
To import a signed PKCS#7 file:

Import Certificates/CRLs from a PCKS7 File
mqs_adm -i -c -f filename, mqs_admc -i -c -f
Windows and UNIX
filename
where filename is the name of the signed PKCS#7 file.

Typically, this command is used to import the certificates used to establish the
verification chain for message-embedded public keys. On Windows and UNIX ,
to import such certificates as trusted certificates, the administrator must use
the -t switch:
mqs_adm -i -c -f filename -t

Only certificates previously exported from a trusted database by a Global

Administrator with a Trusted flag can be imported as trusted.

Revoking Keys
Revoking Keys
Overview
Third-party keys are revoked by the certifying authority that issued them, by
publishing the serial number of the public key certificate in a revocation list
(CRL). Key holders are reinstated when the serial number no longer appears
in the CRL.
PathWAI Secure-generated keys are revoked by the administrator of the node
on which they were issued, using the administrative utility. Revoking users’
keys invalidates the associated PathWAI Secure user ID and password.
This section discusses how PathWAI Secure-generated keys are revoked.
Revoking administrators’ keys

Since administrators’ keys are used to authenticate users’ signatures, revoking
an administrator’s keys invalidates all user IDs and keys issued by that
administrator. Therefore, Candle recommends that you treat administrator
keys as essentially system keys and change the password associated with the
keys instead of revoking them.
However, there may be circumstances where you find it necessary to actually
revoke an administrator’s user ID and keys. The only way to revoke an
administrator is to delete the entire user key database.
The database is a file named Windows and UNIX mqss.usr or OS/390 whatever
name you specified when you created it. You must then register a new
administrator and re-register all the local users.
Revoking users’ keys

Revoking a user’s keys invalidates the user ID and all associated information
in the local user key database. The user ID is marked as "revoked" and is still
visible in any user ID list.
If you are using an LDAP repository, local users are automatically marked as
revoked in the repository when they are revoked on the local database. The
revoked “foreign” users are invalidated on local user key databases when the

Revoking Keys
local databases are refreshed (see “Refreshing the user key database” on page
132).
If you are not using an LDAP repository, you must export the invalidated keys
to all nodes with which the keys have been previously exchanged, via a flat
file or a queue manager (see “Distributing Public Keys and Certificates” on
page 117). Until then, the previous public keys are still valid on the target
systems.
To revoke a local user:
OS/390 KMFADM Main Menu > Manage Users > Revoke Users
Windows and UNIX mqs_adm -d, mqs_admc -d
If you have configured the PathWAI Secure node to connect to an LDAP

repository, you must have a viable connection to the repository to execute this
command successfully.
If you want to bypass the LDAP repository (for example, for emergency key
deletion), you must reset the environment variables
MQSECURE_LDAP_SERVER_ADDRESS and MQSECURE_LDAP_SERVER_PORT
on the local node to none. (See “Configuring Key and Encryption Options”
on page 37 for instructions on resetting the LDAP server address and port
number on your platform.)
Note: If you disable the LDAP repository connection in this manner, you
must remember to reset the variables to re-establish the connection
and to re-issue the delete command.
Users revoked in the local database but not in the LDAP repository appear in
any list of users with the designation R. Users revoked in both the local
database and in the LDAP repository appear with the designation LD. (Users
who have been deleted in the local database and were never written to the
LDAP repository do not appear in the list.)
Forcing deletion of revoked users

Using the Revoke command does not actually delete the user record. It adds a
flag to the record indicating that the user ID has been revoked. This means
that you cannot recreate the same ID on the local machine nor can you use it
on any communicating node: If you create the user ID on another node, then

Revoking Keys
attempt to import the user’s public key into the local machine (for example, to
use to encrypt a message), PathWAI Secure recognizes that a revoked local
user is being reinstated using a foreign public key and the import fails.
However, there are circumstances where you may want to do exactly that. For
example, you may move an application from one machine to another and
want to reinstate its user ID on the local database. In this case, you can force
the deletion of the user record.
To force deletion of a user ID:
OS/390 KMFADM Main Menu > Manage Users > Delete Users
Windows and UNIX mqs_adm -d -t, mqs_admc -d -t
Note: This command may be used to delete users holding only PathWAI
Secure-generated keys.
Reinstating revoked users

To reinstate a revoked user, you must forcibly delete the user record and
recreate the keys, user ID, and password.

Managing the Local User Key Databases
Overview
The local user key database is created (or initialized) as part of the process of
registering the administrator.The administrator’s user ID, password, and
public/private key pair is the first information to be stored in it.
In addition, each local database maintains information about the user IDs and
associated key pairs for its own users. It also stores the public keys for all users
(“foreign” users) with which its host communicates.
The user key database is stored on disk, in encrypted form. Only PathWAI
Secure can communicate with the user key database manager.
Backing up the user key database

You should back up the user key database on each node any time keys are
exchanged or significant key updates are made. Candle recommends the
following procedures:
Windows and UNIX Copy mqss.usr and any *.cdx, *.dbf, and *.fpt files to
back-up files
Use the IDCAMS utility program to perform a REPRO
OS/390
function and create a back-up dataset of
&hilevdsn.USERS, where &hilevdsn is the highest-level
qualifier for PathWAI Secure datasets.
Note: You can use samples USRREPRO and
USRRESTO, located in dataset &hilevdsn.TMFSAMP, to
assist you in the backup/restore process.

Refreshing the user key database

You should periodically refresh the database. Refreshing the database
resynchronizes it with the LDAP repository by importing all CRLs related to
issuer names found on certificates in the untrusted certificate database. It also
refreshes the public keys previously imported from the repository and the
related certificates. This allows it to pick up, for example, user IDs that have
been revoked.
To refresh the user key database:
OS/390 KMFADM Main Menu > Manage LDAP Repository >

Refresh All Public Keys
Windows and UNIX mqs_adm -i -r, mqs_admc -i -r
Re-encrypting the user key database

To ensure the integrity of the database, you should periodically regenerate the
database encryption key and re-encrypt the database using the new key.
To re-encrypt the user key database:
OS/390 KMFADM Main Menu > Manage User Key Database >
Re-encrypt user key database
Windows and UNIX mqs_adm -k, mqs_admc -k
Note: On OS/390, LSR must be turned off before you can re-encrypt the
database.
Creating/Resetting the user key database

To create a user key database:
OS/390 KMFADM Main Menu > Create/Specify User Key

Database
Windows and UNIX mqs_adm -s or mqs_admc -s
Using the create/specify command when a database already exists causes the
database to be deleted and a new database initialized.

Resetting the user key database removes all user IDs from the user key
dataset. You might want to use this function, for example, when moving from
a test environment to a production environment to ensure that no previous
IDs or keys are left behind, or to clean up a database which contains many
revoked IDs.
If you have previously exported keys to an LDAP repository, you will not be
able to reset the local user key database unless you have a viable connection
to the LDAP repository at the time you issue the reset command.
Candle recommends that you make a backup of the user key database before
you invoke this command.
Resetting the LDAP user ID and password

When the user key database is first created, you are prompted for the user ID
and password PathWAI Secure should use to access the LDAP repository. The
user ID and password are then encrypted into the local user key database.
However, it may become necessary to change the LDAP user ID and
password.
If you change the ID and password required to access the repository, the ID
and password must be reset on every instance of PathWAI Secure, so that
PathWAI Secure can export users’ public keys to or import public keys from
the repository. To reset the user ID and password on PathWAI Secure nodes:
KMFADM Main Menu > Manage LDAP Repository >

OS/390
Set/Reset LDAP Repository Update User ID and
Password
Windows and UNIX mqs_adm -s -r, mqs_admc -s -r


Managing the Candle LDAP
4 Repository
Overview
This chapter provides information on managing the Candle-provided LDAP
repository. It documents how to:
n start and stop the LDAP server
n change the port number, user ID and password used to access the
repository
n backup the repository
n delete the repository
If you are using an LDAP repository provided by another vendor, please
consult the product documentation for this information.
Chapter Contents
Using an LDAP Repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Managing the LDAP Repository on Windows NT . . . . . . . . . . . . . . . . . . 137
Starting or stopping the LDAP server . . . . . . . . . . . . . . . . . . . . . . . . 137
Resetting the LDAP respository port, user ID, and password. . . . . . . 137
Backing up the LDAP repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Managing the LDAP Repository on UNIX . . . . . . . . . . . . . . . . . . . . . 141
Managing the LDAP Repository on UNIX. . . . . . . . . . . . . . . . . . . . . . . . 141
Starting or stopping the LDAP server . . . . . . . . . . . . . . . . . . . . . . . . 141
Resetting the LDAP repository port, ID, and password . . . . . . . . . . . 141
Backing up the LDAP repository. . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Deleting the LDAP repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Managing the Candle LDAP Repository 135

Using an LDAP Repository
Using an LDAP Repository
Enabling and disabling the LDAP connection

If you have configured PathWAI Secure to use an LDAP repository, key
generation and distribution will fail unless you have a working connection to
the repository.
If you want to bypass the LDAP repository for any reason (for example, for
emergency key generation), you must reset the environment variables
MQSECURE_LDAP_SERVER_ADDRESS and MQSECURE_LDAP_SERVER_PORT
on the local node to none. (See “LDAP Repository” on page 41 for
instructions on resetting the LDAP server address and port number on your
platform.)
If you disable the LDAP repository connection in this manner, you must
remember to reset the variables to re-establish the connection and export the
keys to the repository (see “Exporting keys to an LDAP repository” on page
118).
The PathWAI Secure configuration utility

PathWAI Secure provides a configuration utility for managing the
Candle-provided LDAP repository on Windows NT and UNIX. On UNIX, you
can invoke the utility in either GUI or text mode.
The PathWAI Secure configuration utility allows you to:
n change the port on which the LDAP repository server listens
n change the user ID and password required for accessing the LDAP
repository
n back up the LDAP repository
n delete the LDAP repository
Note: The PathWAI Secure configuration tool does not allow you to back up
or delete the LDAP repository in text mode. If you do not have
X/Windows, you must back up and delete the repository manually.

Managing the LDAP Repository on Windows NT
Starting or stopping the LDAP server

The LDAP server reads from and writes to Candle’s LDAP repository. It is
automatically started when you install or configure the repository. However,
you may need to stop and restart it at other times.
On Windows NT, the LDAP server runs as a service, Business Directory
Service . Use the Manage Candle Services dialog to start or stop the
service.
Follow these steps on the host where the repository is installed:
1. From the Windows NT Start button, select:
Programs > PathWAI Secure for WebSphere MQ > Manage
Candle Services
The Manage Candle Services dialog is displayed:
2. Start or stop the server as follows:
To start the LDAP server:
n Highlight Business Directory Service in the dialog box.
n Click the Go icon or right-click and select Start Service.
To stop the LDAP server:
n Highlight Business Directory Service in the dialog box.
n Click the Stop icon or right-click and select Stop Service.
Resetting the LDAP respository port, user ID, and password

The port on which the LDAP server listens and the user ID and password that
the PathWAI Secure nodes must use to export their users’ public keys to the
LDAP repository are set when the repository is installed and encrypted in the
local database for each PathWAI Secure instance when the instance is
installed.
However, circumstances may arise which require that you reset the port, user
ID, or password. You reset these variables using the PathWAI Secure
configuration utility on the LDAP host.

Important: If you change the user ID and password required to access the
LDAP repository, you must reset it on every instance of PathWAI
Secure that exports keys to the repository. See “Resetting the LDAP
user ID and password” on page 133 for instructions.
To reset the port, ID, or password:
1. Access the configuration utility:
2. Click the LDAP Utilities tab.
3. Click the Unconfigure Local LDAP Service radio button, then click
Apply.
When the LDAP server has been unconfigured, a message appears. Click OK
to dismiss the message.
4. Select the Configure Stand-Alone LDAP tab. If necessary:
– In the Port Number field, specify the new port number.
– In the LDAP User ID field, specify a new user ID.
– In the LDAP Password field, specify the new password.
5. Click Apply to configure the repository with the new ID or password.
A message appears to inform you when the LDAP repository has been
updated. Click Yes to view the configuration file; click No to dismiss the
dialog.
The LDAP server is restarted once the repository is configured.
Backing up the LDAP repository

To back up the LDAP repository:
1. Access the Configuration tool:
2. Click the LDAP Utilities tab.
Click the Backup Local Database radio button.

The configuration tool provides a default location and name for the backup
file. You can:
– accept the default
– type in the fully specified name for the backup file
– use the browse button to navigate to the directory where you want to put
the backup file
3. Click Apply to execute the backup operation.
You will see a message informing you when the backup has been completed
successfully. Click OK to dismiss the message.
Deleting the LDAP repository

To delete the LDAP repository:
1. Access the configuration utility:
2. Select the LDAP Utilities tab.
3. Click the Delete Local Database radio button, then click Apply.
The repository and all associated files are deleted and the LDAP server is
stopped and unconfigured.

FIGURE 8. The Windows LDAP Configuration Utility

Managing the LDAP Repository on UNIX
Starting or stopping the LDAP server

The LDAP server reads from and writes to Candle’s LDAP repository. It is
automatically started when you install or configure the repository. However,
you may need to stop and restart it at other times.
Always use the Candle utility CandleAgent to start and stop the Candle
LDAP server process (kxsserv).
Note: Do not use the kill command to stop kxsserv.
To start or stop the LDAP server process:
ä Execute CandleAgent as follows on the host where the repository is
installed:
CandleAgent start|stop xs
Resetting the LDAP repository port, ID, and password

The port on which the LDAP server listens, and the user ID, and password
that the PathWAI Secure nodes must use to export their users’ public keys to
the LDAP repository are set when the repository is installed and encrypted in
the local database for each PathWAI Secure instance when the instance is
installed.
However, circumstances may arise which require that you reset the port, user
ID, or password. You reset these variables using the PathWAI Secure
configuration utility on the LDAP host in either GUI mode or text mode.
Note: If you change the user ID and password required to access the LDAP
repository, you must reset it on every instance of PathWAI Secure that
exports keys to the repository. See “Resetting the LDAP user ID and
password” on page 133 for instructions.
GUI mode
To reset the LDAP port, user ID, or password in GUI mode:
1. Access the PathWAI Secure Configuration tool by entering the following

MQConfig
The configuration tool appears.
3. Click the Unconfigure Local LDAP Service radio button, then click
Apply.
When the LDAP server has been unconfigured, a message appears. Click OK
to dismiss the message.
4. Select the Configure Stand-Alone LDAP tab. As necessary:
– In the Port Number field, specify the new port number
– In the LDAP User ID field, specify a new user ID if you wish to change it.
– In the LDAP Password field, specify the new password.
5. Click Apply to configure the repository with the new ID or password.
A message appears to inform you when the LDAP repository has been
updated. Click Yes to view the configuration file; click No to dismiss the
dialog.
The LDAP server is restarted once the repository is configured.
Text mode
To reset the ID and password in text mode:
1. Access the configuration utility by entering the following command from the
command line:
MQConfig -l
Port Number(Default is : current_port):
– To change the port number, enter the new port number at the prompt.
– To keep the current default, press Enter.
3. The following prompt appears:

LDAP User ID(Default is : current_ID):

– To change the user ID, enter the new ID at the prompt.
4. The following prompt appears:
LDAP Password(Default is : current_pw):
– To change the password, enter the new password at the prompt.
You will see the following messages:
Configuring LDAP Server...

Configuration complete..
Backing up the LDAP repository

Note: The PathWAI Secure configuration tool does not allow you to back up
the LDAP repository in text mode. If you do not have X/Windows, you
must back up the repository manually.
GUI mode
To back up the LDAP repository manually:
1. Access the PathWAI Secure Configuration tool:
MQConfig
3. Click the Backup Local Database radio button.
The configuration tool provides a default location and name for the backup
file. You can:
– accept the default
– type in the fully specified name for the backup file
– use the browse button to navigate to the directory where you want to put
the backup file
4. Click Apply to execute the backup operation.

You will see a message informing you when the backup has been completed
successfully. Click OK to dismiss the message.
Manual mode
To back up the LDAP database manually:
ä Export the existing database to LDIF format in an export file:
ldapsearch -b "" -h ldap_addr -p ldap_port "cn=*" >
exportfilename
where:
ldapaddr is the host name or IP address of the LDAP host
ldapport is the port number of the LDAP server
exportfilename is the name you want to give to the backup database
Deleting the LDAP repository

Note: The PathWAI Secure configuration tool does not allow you to delete
the LDAP repository in text mode. If you do not have X/Windows, you
must delete the repository manually.
GUI mode
To delete the LDAP repository in GUI mode:
1. Access the PathWAI Secure Configuration tool:
MQConfig
3. Click the Delete Local Database radio button, then click Apply.
The repository and all associated files are deleted and the LDAP server is
stopped and unconfigured.
Manual deletion
To delete the LDAP repository manually:
1. Stop the LDAP server
ldapstop -h ldap_addr -p ldap_port -D cn=user_ID -w
password

where:
ldapaddr is the host name or IP address of the LDAP host
ldapport is the port number of the LDAP server
user_ID is the user ID required to administer the LDAP repository
password is the password for the administrative user ID
2. Change to candle/roma/platform/ldap/bin directory (if necessary):

CD candle/roma/platform/ldap/bin
where:
candle is the directory in which PathWAI Secure is installed
platform the platform you installed for (for example: aix42)
3. Remove the .dbb and NEXTID files:

rm NEXTID
rm *.dbb


Securing WebSphere MQ
5 Messages Using Channel Exits
Overview
This chapter provides instructions for invoking PathWAI Secure’s security
services on a node-to-node or channel-specific basis in a WebSphere MQ
network using channel exits. For information on implementing security on an
application-by-application basis using PathWAI Secure’s APIs, please refer to
the PathWAI Secure for WebSphere MQ Programmer’s Guide.
Chapter contents
Securing Messages Using PathWAI Secure Channel Exits . . . . . . . . . . . . 148
Setting Channel Exit Definition Parameters. . . . . . . . . . . . . . . . . . . . . . . 151
Securing Autodefined Cluster Sender Channels . . . . . . . . . . . . . . . . . . . 155
Securing WebSphere MQ Messages Using Channel Exits 147

Securing Messages Using PathWAI Secure Channel Exits
Overview
PathWAI Secure channel exit programs provide authentication and encryption
of messages traveling over an WebSphere MQ network on a node-to-node or
channel-specific basis. Channel exits can also be used to verify the identity of
communicating nodes (platform mutual authentication) or individual channel
users (channel mutual authentication) before channels are activated.
To invoke PathWAI Secure security services at the channel exit level, an
WebSphere MQ administrator sets channel exit definition parameters which
specify:
n where to locate the appropriate PathWAI Secure channel exit program
n what type of security PathWAI Secure should apply
The WebSphere MQ channel definition parameters specified vary according
to channel type and the security required, as summarized in Table 5 on page
149.
Platform mutual authentication uses the public and private keys of the
administrator IDs associated with the sending and receiving queue managers
to authenticate the platform connection. Before you begin configuring the
channels, the administrator ID public keys involved must have been
exchanged (see ““Managing the Local User Key Databases” on page 131 and
the PathWAI Secure for WebSphere MQ Installation Guide).
Channel mutual authentication uses the public and private keys of the
channel authentication IDs associated with the sending and receiving ends of
the channel to authenticate the channel connection. Before you begin
configuring the channels, the channel authentication ID public keys involved
must have been exchanged. (see “Distributing Public Keys and Certificates”
on page 117 and the PathWAI Secure for WebSphere MQ Installation Guide).
Channel mutual authentication for cluster channels uses the public and
private keys of the cluster authentication IDs associated with the sending and
receiving ends of the channel to authenticate the channel connection. Before
you begin configuring the channels, the cluster authentication ID public keys
involved must have been exchanged. (see “Distributing Public Keys and

Certificates” on page 117 and the PathWAI Secure for WebSphere MQ

Installation Guide).
Note: If you are using third-party keys, you do not need to exchange the
public keys used for platform or channel mutual authentication. At
channel startup, the security exits automatically embed (as available)
the full chain of certificates with each security exchange message.
However, you must have imported a common certificate, such as a
VeriSign root certificate, into each node’s trusted certificate database
for this operation to be successful.
Table 5. Channel Exit Definition Parameters
Encrypt &
Authenticate Authenticate Encrypt Authenticate
Channel Type Connection Message Message Message*
CHLTYPE(SDR) SCYEXIT MSGEXIT SCYEXIT SCYEXIT
MSGDATA(A) MSGEXIT MSGEXIT
MSGDATA(E) MSGDATA(EA)
CHLTYPE(RCVR) SCYEXIT MSGEXIT SCYEXIT SCYEXIT
CHLTYPE(CLUSSDR) SCYEXIT MSGEXIT SCYEXIT SCYEXIT

CHLTYPE(CLUSRCVR) SCYEXIT MSGEXIT SCYEXIT SCYEXIT

CHLTYPE(SRVCONN) SCYEXIT RCVEXIT SCYEXIT SCYEXIT
RCVDATA(A) RCVEXIT RCVEXIT
SENDEXIT RCVDATA(E) RCVDATA(EA)
SENDDATA(A) SENDEXIT SENDEXIT
SENDDATA(E) SENDDATA(EA)
CHLTYPE(CLNTCONN) SCYEXIT RCVEXIT SCYEXIT SCYEXIT
RCVDATA(A) RCVEXIT RCVEXIT
SENDEXIT RCVDATA(E) RCVDATA(EA)
SENDDATA(A) SENDEXIT SENDEXIT
SENDDATA(E) SENDDATA(EA)

Table 5. Channel Exit Definition Parameters
Encrypt &
Authenticate Authenticate Encrypt Authenticate
Channel Type Connection Message Message Message*
CHLTYPE(RQSTR) SCYEXIT MSGEXIT SCYEXIT SCYEXIT
CHLTYPE(SVR) SCYEXIT MSGEXIT SCYEXIT SCYEXIT
*Note: The order of the signing/authentication (A) and encryption/decryption (E) operations is
determined by the order in which they are specified: EA encrypt then sign, AE sign then encrypt.
Logging failures
Any failures of an authentication or encryption operation in the channel exits
result in the message being diverted to the PathWAI Secure problems queue,
SYSTEM.MQSECURE.PROBLEMS. A message is logged to the channel exit
log explaining the diversion and to where, along with an error message
specifying why the operation failed.
Exit chaining
WebSphere MQ for OS/390 does not support chained exits.
If you are already using the MSGEXIT, the only way to specify PathWAI
Secure channel exits is by writing an exit in-house that issues an OS/390
LOAD of the PathWAI Secure load module specific to the functionality
required (MQSSEXIT for message exit, for example). The PathWAI Secure exit
can then be driven through the standard C function prototype applicable to
WebSphere MQ channel exits. The prototype is found in the WebSphere MQ
Intercommunication manual.

Setting Channel Exit Definition Parameters
Specifying the PathWAI Secure channel exit program

The WebSphere MQ MSGEXIT, SENDEXIT, RCVEXIT, and SCYEXIT
parameters tell the channel where to find the appropriate PathWAI Secure
channel exit program.
You specify SCYEXIT, MSGEXIT, RCVEXIT, and SENDEXIT as follows:
OS/390
SCYEXIT(‘SECEXIT’) (for platform mutual authentication)
SCYEXIT(‘CHLEXIT’) (for channel mutual authentication)
SCYEXIT('CLUEXIT') (for channel mutual authentication for cluster
channels)
MSGEXIT(‘MQSSEXIT’)
RCVEXIT(‘RECEXIT’)
SENDEXIT(‘SENDEXIT’)
Windows
For channel type CLNTCONN:
SCYEXIT(‘MQSEXITC(Sec_Exit)’) (for platform mutual authentication)
SCYEXIT(‘MQSEXITC(Chl_Exit)’) (for channel mutual authentication)
RCVEXIT(‘MQSEXITC(Rec_Exit)’)
SENDEXIT(‘MQSEXITC(Send_Exit)’)
For channel types CLUSSDR/CLUSRCVR:
SCYEXIT(‘MQS_EXIT(Sec_Exit)’) (for platform mutual authentication)
SCYEXIT(‘MQS_EXIT(Clu_Exit)’) (for channel mutual authentication for
cluster channels)
MSGEXIT(‘MQS_EXIT(MQS_Exit)’)
RCVEXIT(‘MQS_EXIT(Rec_Exit)’)
SENDEXIT(‘MQS_EXIT(Send_Exit)’)
For all other channel types:
SCYEXIT(‘MQS_EXIT(Sec_Exit)’) (for platform mutual authentication)
SCYEXIT(‘MQS_EXIT(Chl_Exit)’) (for channel mutual authentication)
MSGEXIT(‘MQS_EXIT(MQS_Exit)’)

RCVEXIT(‘MQS_EXIT(Rec_Exit)’)
SENDEXIT(‘MQS_EXIT(Send_Exit)’)
UNIX
For channel type CLNTCONN:
SCYEXIT(’&mqsdirunx/lib/mqsexitc(Sec_Exit)’) (for platform mutual
authentication)
SCYEXIT(’&mqsdirunx/lib/mqsexitc(Chl_Exit)’) (for channel mutual
authentication)
RCVEXIT(’&mqsdirunx/lib/mqsexitc(Rec_Exit)’)
SENDEXIT(’&mqsdirunx/lib/mqsexitc(Send_Exit)’)
For channel types CLUSSDR/CLUSRCVR:
SCYEXIT(’&mqsdirunx/lib/mqs_exit(Sec_Exit)’) (for platform mutual
authentication)
SCYEXIT(’&mqsdirunx/lib/mqs_exit(Clu_Exit)’) (for channel mutual
authentication for cluster channels)
MSGEXIT(’&mqsdirunx/lib/mqs_exit(MQS_Exit)’)
RCVEXIT(’&mqsdirunx/lib/mqs_exit(Rec_Exit)’)
SENDEXIT(’&mqsdirunx/lib/mqs_exit(Send_Exit)’)
where &mqsdirunx is the directory where you installed PathWAI Secure.
For all other channel types:
SCYEXIT(’&mqsdirunx/lib/mqs_exit(Sec_Exit)’) (for platform mutual
authentication)
SCYEXIT(’&mqsdirunx/lib/mqs_exit(Chl_Exit)’) (for channel mutual
authentication)
MSGEXIT(’&mqsdirunx/lib/mqs_exit(MQS_Exit)’)
RCVEXIT(’&mqsdirunx/lib/mqs_exit(Rec_Exit)’)
SENDEXIT(’&mqsdirunx/lib/mqs_exit(Send_Exit)’)
where &mqsdirunx is the directory where you installed PathWAI Secure.
These parameters are case-sensitive.

Specifying security services

The MSGDATA (queue managers) or SENDDATA and RCVDATA (clients)
parameters are used to tell the PathWAI Secure channel exit program which
security services should be performed.
If you
specify A sender A receiver
A signs authenticates
E encrypts decrypts
AE signs then encrypts decrypts then authenticates
EA encrypts then signs authenticates then decrypts
The exit program determines whether the message channel agent (MCA) is
receiving or sending in order to decide what security function needs to be
implemented. For example, if A (signing/authentication) is specified for the
value of the MSGDATA parameter of a sending MCA, the program
determines that the channel is sending and signs the messages. If the channel
is receiving, the program authenticates the message.
The receiver must be configured to invoke the same services as the sender
and the parameters must be specified in the same order on both ends of the
channel.
Combining parameters to specify security type

You specify the type of security to be applied using a combination of channel
definition parameters. When xxxDATA(E) is specified, SCYEXIT must also be
specified so that the sending node has access to the receiving node’s user ID
for encryption purposes.
To specify Use
connection authentication SCYEXIT
message signing MSGEXIT and MSGDATA (A), or

SENDEXIT/RCVEXIT and SENDDATA(A)/RCVDATA(A)

To specify Use
message encryption SCYEXIT, MSGEXIT, and MSGDATA(E), or
SCYEXIT, SENDEXIT/RCVEXIT, and
SENDDATA(E)/RCVDATA(E)
message encryption then SCYEXIT, MSGEXIT, and MSGDATA(AE), or
signing SCYEXIT, SENDEXIT/RCVEXIT, and
SENDDATA(AE)/RCVDATA(AE)
Note The xxxDATA and xxxEXIT parameters must be specified identically

in the definitions for both ends of any channel. If they are not identical
in content, casing, and order, the channel will not initialize.
Example
The following example provides instructions for configuring a sender channel,
HQAIX1.TO.REMNT5, so that whenever it is presented with a message to
send to REMNT5, it signs the message before sending it. The receiver end of
the channel must be configured in the same way.
1. Start the queue manager:
strmqm HQAIX1
2. Start the command processor for the queue manager:
runmqsc HQAIX1
3. Configure the channel as follows:
A. Use the MSGEXIT parameter to tell the channel where to find the
PathWAI Secure channel exit program.
B. Use the MSGDATA parameter to tell the channel exit program to sign all
messages before sending them.
alter channel(HQAIX1.TO.REMNT5) CHLTYPE(SDR) MSGDATA(A)
MSGEXIT(’/users/mfhqaix1/mqsecure/mqs_exit(MQS_Exit)’)
4. Shut down the command processor for the queue manager:
end

Securing Autodefined Cluster Sender Channels
Overview
Special considerations apply when you are securing messages through
channels in an WebSphere MQ cluster using cluster receiver/cluster sender
channel pairs and the cluster sender side of the channel is autodefined.
In this situation, the local queue manager obtains the definition of the cluster
receiver channel from the Cluster Repository and uses it as a template for the
cluster sender definition. The cluster receiver definition channel exit
definitions are used as a basis for the cluster sender channel exit
specifications.
However, the cluster receiver channel exit specifications may be inappropriate
for the platform where the cluster sender is being defined because of the
platform-specific naming convention applicable to the exits. This situation
obtains when a mixture of OS/390 and non-OS/390 (UNIX or Windows)
queue managers are members of a cluster.
For example, if an OS/390 cluster receiver channel definition is used to
autodefine a cluster sender channel on UNIX, the 1–8 character load module
name of the OS/390 channel exit is used as the corresponding exit name in
the cluster sender definition. Since this name format is invalid on UNIX (and
Windows), the OS/390 exit name must be converted to its equivalent,
acceptable name on the target platform.
PathWAI Secure provides a channel autodefine exit (CHADEXIT) that can be
specified as part of the queue manager definition.
Using CHADEXIT, channel exit names are converted as shown in Table 6.
Table 6. Conversion of Channel Exit Names Using CHADEXIT
Exit Type OS/390 Name UNIX Name Windows Name

Security Exit SECEXIT mqs_exit(Sec_Exit) mqs_exit(Sec_Exit)
Security Exit CHLEXIT mqs_exit(Chl_Exit) mqs_exit(Chl_Exit)
Security Exit CLUEXIT mqs_exit(Clu_Exit) mqs_exit(Clu_Exit)
Message Exit MQSSEXIT mqs_exit(MQS_Exit) mqs_exit(MQS_Exit)

UNIX and Windows exits must be installed in the WebSphere MQ

DefaultExitsPath directory to allow specification of the exit library name (entry
point name) without explicit pathing. This takes advantage of the fact that
both UNIX and Windows use the same naming convention in PathWAI
Secure and avoids the necessity of handling different pathing specifications
between UNIX and Windows as well as between OS/390 and these two
environments. Windows library names are handled correctly by the exit
whether in upper or lower case; UNIX library names are shipped as lower case
in PathWAI Secure and any conversion to Windows or UNIX naming format is
to lower case because this is valid in both of these environments.
Activating channel autodefine exits

You activate the channel autodefine exit using ALTER QMGR as shown in the
following examples. You must activate the exit on all queue managers
participating in the cluster.
For example, on UNIX or Windows NT/2000 queue managers:
ALTER QMGR CHADEXIT(’mqs_exit(ChadExit)’)
On OS/390 queue managers:
ALTER QMGR CHADEXIT(CHADEXIT)
Allocation of the shipped PathWAI Secure load library containing the
PathWAI Secure channel exits through the CSQXLIB allocation in the
Channel Initiator address space ensures that the channel auto define exit is
invoked.
Figure 9 on page 157 shows the cluster sender channel definition under a
UNIX queue manager using an OS/390 cluster receiver as the basis.

FIGURE 9. UNIX Cluster Sender Channel Definition Based on OS/390 Cluster

Receiver
DEFINE CHANNEL(TO.OS390) CHLTYPE(CLUSRCVR) TRPTYPE(TCP)

CLUSTER(CANDLE) CONNAME(’CANDLE(1414)’)
SCYEXIT(CHLEXIT)
MSGEXIT(MQSSEXIT) MSGDATA(AEK100)
results in the following cluster sender definition under the sender platform queue manager
after conversion by the PathWAI Secure channel auto define exit:
DEFINE CHANNEL(TO.OS390) CHLTYPE(CLUSSDR) TRPTYPE(TCP)
CLUSTER(CANDLE) CONNAME(’CANDLE(1414)’)
SCYEXIT(’mqs_exit(Chl_Exit)’)
MSGEXIT(’mqs_exit(MQS_Exit)’) MSGDATA(AEK100)


Appendixes
Appendixes 159
A CASP Secure Connector
Overview
This appendix introduces Candle Application Services Pac Secure Connector
and provides instructions for its use. It also presents three scenarios which
illustrate how you can implement CASP Secure Connector.
Note: The functionality of CandleNet eBP is now available in the Candle
Application Services Pac (CASP) toolkit. CASP uses CASP Secure
Connector in the same manner as CandleNet eBP. Throughout this
appendix, any references to CASP are also applicable to CandleNet
eBP.
Appendix contents
About CASP Secure Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Using MQSecure Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Configuring MQSecure Connection Using Secure Side Files . . . . . . . . . . 170
Configuring MQSecure Connection Programmatically . . . . . . . . . . . . . . 173
Usage Scenarios . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
CASP Secure Connector 161

About CASP Secure Connector
What is CASP Secure Connector?

CASP Secure Connector enables you to provide node-to-node or end-to-end
security for CASP message flows by simply configuring PathWAI Secure as an
inline service, instead of calling PathWAI Secure APIs. No in-depth knowledge
of PathWAI Secure and no special programming is required to use CASP
Secure Connector with a CASP client or server application. Applications
which have already been written and compiled can use the security facilities
without any modification (see Figure 10 on page 163).
The security of an interaction between CASP applications utilizing CASP
Secure Connector ensures:
n Privacy—Prevents a message being read while not in memory, for
example, on a queue throughout a CASP flow.
n Single-hop integrity—Prevents a message being tampered with on a single
hop of a CASP flow.
n Single-hop authentication—Allows you to verify that a message on a
single hop of a CASP flow did originate from a trusted source.
In addition, in complex business flows which may span many applications it is
possible to secure only those parts of the flow which are exposed to risk of
attack. This in effect creates a “firewall” and allows you to avoid the overhead
of encrypting every hop of the flow unnecessarily (see Figure 11 on
page 164).
Modes of operation
CASP Secure Connector can operate in either of two modes: unattended or
interactive.
Unattended mode allows for operation in which an application is autostarted
and obtains its security credentials without interaction with a user. In
unattended mode, an application obtains the password associated with the
PathWAI Secure user ID from a secure side file, which is generated using a
command line utility provided by Secure Connector. Values for encryption
operations can also be specified in the secure side file.

Interactive mode requires some programming to achieve PathWAI Secure

integration, but allows applications to use user-determined methods of
obtaining their security credentials and allows for specialized control of the
operations performed by CASP Secure Connector.
FIGURE 10. CASP Secure Connector Operation
Host H01 Host H02
Request to Business Service

SVC01
Clnt01 BE01
Response to Client01
Clnt01.ssf BS01.ssf
BE01.ssf
password password
LDAP
eBP
Client Clnt01
Business Service Svc01
Component BC01
Element BE01
PathWAI PathWAI
Secure PathWAI Secure
Secure
User Key Public key Clnt01 User Key
Database Public key BE01 Database
Message signed with private key Clnt 01 Message authenticated with public key
and encrypted with public key BE01 Clnt01 and decrypted with private key
Message authenticated with public key BE01 Message signed with private key BE01
and decrypted with private key Clnt01. and encrypted with public key Clnt01.

FIGURE 11. Business Flow Using Put Only and Get Only Security
Server 1 kmlxcilsg
Security applied only
on get operations
Server 3
Client
Server 4
kmlxcils
Security applied kmlxcilsp
on both put and Security applied only
get operations Server 4 on put operations
Plain text messages

Secured messages
Interoperation with CASP applications

CASP Secure Connector is compatible with eBP 3.1, CASP 1.0, or above.
CASP Secure Connector can operate with all CandleNet eBP or CASP
applications. However, applications using the CASP Native Connector or File
Transfer can operate only in unattended mode.
While interoperation of CASP applications with native WebSphere MQ
applications that have used the MQSecure APIs to apply security to a message
could be achieved, this is not detailed in this guide.

Using MQSecure Connection
Default operation
To facilitate ease of operation, CASP Secure Connector uses the following
defaults:
n Messages are both signed and encrypted.
n The sender PathWAI Secure user ID defaults to the name of the CASP
business element (for server applications) or the CASP client (for client
applications).
n The destination PathWAI Secure user ID defaults to the name of the client
or business element the message will be delivered to in the next message
hop.
n The password associated with an PathWAI Secure user ID is retrieved
from a secure side file.
n Symmetric keys are reused 1000 times or for 5 minutes, whichever comes
first.
n The default ILS (kmlxcils) performs security operations when receiving
and sending CASP messages. Specialized ILSs are available for
performing send only (kmlxcilsp) and receive only (kmlxcilsg)
security to facilitate the cases where a complex business flow is only
vulnerable to attack on parts of the flow.
You can override the default settings by specifying override values in a side
file or by passing them programmatically in an CASP application.
Note: Messages secured using CASP Secure Connector can only be signed
and encrypted, in that order. They cannot be encrypted and then
signed.
Run-time paths
A CASP application which uses CASP Secure Connector must have both the
CASP directories and the PathWAI Secure bin and dll (Windows) or lib
(UNIX) directories set in its execution and library runtime paths.

On Windows these paths are automatically updated when CASP and

PathWAI Secure are installed.
CASP for UNIX provides a set of shell profiles (roma.sh, roma.ksh, roma.csh)
that set the required PATH and LIBPATHs.
LDAP repository
Candle recommends that if you decide to use an LDAP repository for public
user key distribution, you use the same LDAP repository used by CASP. That
way, the applications are dependent upon a single external service.
To enable PathWAI Secure to use the same repository as CASP, the PathWAI
Secure schema must be imported into the CASP LDAP repository. This is
achieved during PathWAI Secure installation by specifying the LDAP server
host and port of the existing CASP LDAP server. Alternatively, if you have an
existing PathWAI Secure installation, you can use the PathWAI Secure
Configuration Tool’s Seed LDAP tab to specify the appropriate host and port
details.
For more information on using the CASP LDAP repository, see your site
CASP administrator, the PathWAI Secure Installation Guide, and the Roma
BSP™ Directory Services User’s Guide (Version 3.0) or the CandleNet eBP
Administrator™ Directory Services User’s Guide (Version 3.1).
For more information on managing key distribution using an LDAP
repository, see “Exporting keys to an LDAP repository” on page 118 and
“Managing the Candle LDAP Repository” on page 135.
Creating MQSecure user IDs

An MQSecure administrator must create user IDs for eBP applications (clients
and servers) using the MQSecure administrative utility. For more information
on creating user IDs, see “Managing Users and User Keys” on page 91.
By default, the MQSecure user ID of the sender is assumed to be the name of
the eBP business element or client under which the application is running.
The MQSecure user ID of the message destination is assumed to be the name
of the client or business element the message will be delivered to on the next
hop.

However, both sender and destination user IDs may be overridden by

specifying an alternative user ID in the secure side file (see “Configuring
MQSecure Connection Using Secure Side Files” on page 170), or by passing
another user ID programmatically using the structure KXCMQSECINFO (see
“Configuring MQSecure Connection Programmatically” on page 173). This
makes it possible for multiple clients to use a single user ID, and for multiple
servers to share a single user ID.
MQSecure passwords
MQSecure passwords are required to access the private keys used to sign
(sender) and decrypt (receiver) messages. Passwords are specified at the time
new MQSecure user IDs are created.
In order to let applications run unattended, by default, MQSecure Connection
supplies MQSecure passwords to eBP applications through secure side files.
However, they may also be passed programmatically via any method
implemented by an application programmer, using the structure
KXCMQSECINFO (see “Configuring MQSecure Connection
Programmatically” on page 173).
For information on creating, storing, and securing secure side files, see
“Configuring MQSecure Connection Using Secure Side Files” on page 170.
Enabling MQSecure Connection with eBP applications

You must specify use of MQSecure Connection for each eBP client or business
element in the application to or from which you want to send secure
messages.
In the eBP Directory Administrator:
1. In the properties settings for each eBP business element and client, select the
Inline Services tab.
2. Click New.
Type in the name of the appropriate ILS:
kmlxcils Apply security on get and put operations. The recommended

configuration.

kmlxcilsg Apply security only on get operations and put clear text message on
put.
kmlxcilsp Apply security only on put operations and perform no security
checks on get operations.
Figure 12 on page 169 shows the Inline Services tab.

For more information on specifying properties of eBP business elements and
clients, refer to Roma BSP™ Directory Services User’s Guide (Version 3.0) or
CandleNet eBP Administrator™ Directory Services User’s Guide (Version
3.1).

FIGURE 12. Specifying CASP Secure Connector in the Directory Administrator

Configuring MQSecure Connection Using Secure Side Files
Overview
By default, MQSecure Connection obtains the passwords associated with
MQSecure user IDs from a secure side file. This allows applications to apply
security transparently, without need for operator intervention, and enables
applications which have already been written and compiled to use the security
facilities without any modification.
These files may also be used to override all other default settings. They may
contain sender and destination user IDs which can be used to override the
default sender and destination user IDs. This allows multiple clients and
servers to use the same MQSecure IDs and passwords. In addition, these files
can also be used to configure MQSecure Connection to
n accept unencrypted messages
n encrypt only specified ranges of message text, via tags or offset
n specify symmetric key reuse
Candle provides a command-line utility to produce the secure side files.
Passwords may also be obtained by any method determined by an
application developer, and all settings except symmetric key reuse may be
overriden programmatically (see “Configuring MQSecure Connection
Programmatically” on page 173).
Creating secure side files

The command-line utility kmlxcssf is located in mqsecure\bin
(Windows) or mqsecure/platform/bin (UNIX), where mqsecure is the
directory where MQSecure is installed and platform is the platform you
installed on (for example, aix433).
Secure side files are created using the command:
kmlxcssf [-f <filename>] [-p <password>] [-u <userid>]
[-d <destinationid>]
[-r <leftdelimiter> <rightdelimiter> | -o
<offset> <length>]

[-a] [-s | -e]

[-c <count> <lifetime>]
where:
-f Specifies the name that should be given to the secure side file.
Files are named for the business element or client, or the default
file kmlxcuid. The utility adds the fixed extension.ssf.
-p Specifies the password associated with the MQSecure user ID
-u (optional) Indicates the MQSecure user ID associated with the eBP
server or client sending the message. Default is the same as the
name of the eBP business element or client record.
-d (optional) Specifies the override user ID of the client or business
element the message will be delivered to in the next message hop
-r (optional) Indicates use of range encryption using the specified left
and right delimiters to mark the portion the message that is
encrypted.
Note: If the string used as a delimiter includes control characters
in the operating system command syntax, you must quote them in
the manner prescribed in the reference manual for the operating
system.
-o (optional) Indicates use offset-based range encryption using the
specified offset and length of the text to be encrypted.
Note: For messages encrypted using secure side files, only a
single offset/length range may be specified. If you want to specify
multiple ranges, you must configure PathWAI Secure operations
programmatically.
-a (optional) Allows unencrypted messages to be received
-s (optional) Only sign all outgoing messages
-e (optional) Only encrypt all outgoing messages
-c (optional) Indicates number of symmetric key reuses and time to
expiration (in seconds). If no value is set, the number of reuses is
1000 and the maximum interval is 300 seconds.
For example:
kmlxcssf -u bankClnt01 -p SecretClPwd -f bankClnt01

Locating secure side files

Secure side files must be placed either in the directory in which the relevant
eBP application is started or in the directory ssf rooted from your CandleNet
eBP product installation base. That is:
CANDLENETeBP_HOME\ssf
which for a default Windows NT installation would be:
c:\Program Files\Candle\CandleNet
eBP\ssf\<client/element>.ssf.
If values are not passed programmatically, MQSecure Connection first
attempts to open a file named for the eBP client or business element the
application is initialized as (<client/element>.ssf) in the application’s
working directory. If it does not find the file in that directory, it searches the
directory ssf.
If MQSecure does not find a <client/element> named file in this
directory, it looks for the default file kmlxcuid.ssf. If it finds neither, it
issues the error “No password” on the first message flowed.
Setting security on side files

Information in the secure side files is encrypted, but the algorithm used is not
a strong one, so file access permission should also be set to ensure security.
To protect these files, their access permissions should be set so that only the
operating system user ID that the eBP applications are started under has read
access to them.

Configuring MQSecure Connection Programmatically
Overview
To set the values for MQSecure Connection operations programmatically, you
must reference the CandleNet eBP MQSecure Connection header file
kmlxcils.h in your eBP client or server applications and create an
MQSecure Connection data structure, KXCMQSECINFO.
You pass the data structure to PathWAI Secure Connection via an eBP data
buffer, KXCILSOPT, using the C function kxcSetILSDdata or other
language equivalents. You address this buffer at PathWAI Secure Connection
via the “type” and “method” defines.
For more information, refer to the CandleNet™ eBP Programmer’s Guide for
Procedural Languages or the CandleNet™ eBP Programmer’s Guide for
Object-Oriented Languages, as appropriate.
kmlxcils.h
The header file kmlxcils.h is located in mqsecure\samp (Windows) or
mqsecure/samp (UNIX), where mqsecure is the directory where
MQSecure is installed.
KXCMQSECINFO: MQSecure security

This structure specifies the values MQSecure Connection requires to encrypt
and sign outgoing messages or authenticate and decrypt incoming ones. The
new buffer is then passed back to CandleNet eBP to forward.
CandleNet eBP passes this structure to MQSecure Connection when sending
a message. (See Figure 13 on page 178 for sample code.)
Field Type Description
Signature KXCULONG Set to IMQS to show a valid structure

Version KXCULONG Set to "KXCVER_MQSECINFO_CURR",

allowing future updates to be picked up
only on recompilation with a newer
version
Options KXCULONG Set one of, or a bit-wise OR of, the

following options:
KXCMQSECOPT_NONE—No options
specified
KXCMQSECOPT_USERID—Pick up a
replacement user ID from the UserID
field (see below)
KXCMQSECOPT_PASSWORD—Pick
up a replacement password from the
Password field (see below)
KXCMQSECOPT_DESTUSERID—
Pick up a replacement destination user
ID from the DestUserID field (see
below).
KXCMQSECOPT_TYPE—The
application is attempting to set the type
of security it wishes to perform. This
must be used in conjunction with the
security values below.

Security KXCLONG Type of security to be applied to the

next message. Requires that the option
KXCMQSECOPT_TYPE be set.
Set:
KXCMQSECTYP_NONE—No security,
Or set one, or a bit-wise OR, of the
following:
KXCMQSECTYPE_SIGN—Sign
Or / or a bit-wise OR of one of
KXCMQSECTYPE_ENCRYPT—Encrypt
entire message
KXCMQSECTYPE_RANGE_ENCRYPT—
Encrypt ranges specified by
LeftDelim and RightDelim
KXCMQSECTYPE_OFFSET_ENCRYPT—
Encrypt "NumRanges" specified by
"KXCMQSRANGE" structures
pointed to in "pRange"
If this option is not set, the security set
from last message exchange is used.
Default is KXCMQSECTYPE_SIGN OR’d
with KXCMQSECTYPE_ENCRYPT
UserID KXCCHAR[MAX_ENC_LEN] The sender MQSecure user ID to use

for MQSecure calls. Requires that the
option KXCMQSECOPT_USERID be
set.
If this parameter is not passed, the
application will use the user ID obtained
from the side file or default to the client
or business element name on the eBP
context.

Password KXCCHAR[MAX_ENC_LEN] The password associated with the

MQSecure user ID of the sender, used
for MQSecure calls. Requires that the
option KXCMQSECOPT_ PASSWORD
be set.
application must obtain it from the side
file.
DestUserID KXCCHAR[MAX_ENC_LEN] The MQSecure user ID for the

destination, used for MQSecure calls.
Requires that the option
KXCMQSECOPT_DESTUSERID be
set.
connection will use the destination user
ID obtained from the side file or default
to the name of the client or business
element the message will be delivered
to in the next message hop.
LeftDelim KXCCHAR[MAX_ENC_LEN] Tag string marking the beginning of a

selective range of the message to be
encrypted when the Security field
includes the setting
KXCMQSECTYPE_RANGE_ENCRYPT
RightDelim KXCCHAR[MAX_ENC_LEN] Tag string marking the end of a selective

range of the message to be encrypted
when the Security field includes the
setting
KXCMQSECTYPE_RANGE_ENCRYPT
NumRanges int The number of offset range

KXCMQSRANGE structures provided
in the field pRange when the
Security field includes the setting
KXCMQSECTYPE_OFFSET_ENCRYPT

pRange PKXCMQSRANGE Pointer to the array of KXCMQSRANGE

structures sized by field NumRanges
when the Security field includes the
setting
KXCMQSECTYPE_OFFSET_ENCRYPT.
See below for how the selective range is
defined in the KXCMQSRANGE
structure.
KXCMQSRANGE—Range structure
This structure is optionally provided in a array to define a number of ranges of
a message that should selectively be encrypted. For example, when XML
messages are processed, only the value of certain XML fields will want to be
encrypted.
The address of the array of KXCMQSRANGE structures is stored in the
KXCMQSECINFO field pRange and the number of range elements is stored
in NumRanges when the Security field includes the setting
KXCMQSECTYPE_OFFSET_ENCRYPT.
Field Type Description

Offset KXCULONG Start byte of Range to be
encrypted offset in
message data
Length KXCUSHORT Length in bytes of text to
be encrypted

FIGURE 13. Extract From C Example Program Showing Usage of Functions
/****** ***** ***** ***** ***** **** ***** ***** ***** ***** ***** ***/
/* Bui ld th e dat a str uctur e th at pa sses infor matio n fro m */
/* the appl icati on to the MQSe cure ILS. */
/***** ***** ***** ***** ***** **** ***** ***** ***** ***** ***** ****/
KXCMQSE CINFO MyMq sOpts = { KX CMQSE CINFO _DEFA ULT } ;
kxcSe tILSD efaul t (&I LSOpt ions );

ILSOp tions .Type = KXCX IT_T YPE_S ERVIC E; /* ILS Type of MQ Secur e ILS
*/
ILSOp tions .Meth od = KXCX IT_S ERV_M ETHOD _MQS; /* I LS Id “ meth od nu mber”
*/
/* for MQSec ure I LS */

ILSOp tions .Data Buf.p Buffe r = (PKXC VOID) & My MqsOp ts; /* Th e buf fer t o
pass */
ILSOp tions .Data Buf.B ufLen = sizeo f (My MqsOp ts);
ILSOp tions .Data Buf.S tatus = KXCBU FSTAT _USER ;
ILSOp tions .Data Len = sizeo f (My MqsOp ts);

Usage Scenarios
Usage Scenarios
Overview
The following scenarios are based on an hypothetical CandleNet eBP banking
solution. The solution consists of a number of eBP client applications that
receive authenticated and validated requests from a Web application. These
clients then issue requests to a number of eBP server applications, which
perform business functions such as “check balance” and “transfer funds”.
The bank needs to ensure authentication of the requests received by the
server applications as well as ensuring the privacy of the requests and
responses. MQSecure offers this security at minimal cost and with no impact
to the ongoing application development.
Transparent Solution
This solution requires no application modification or development. It allows
for unattended operation: an application is autostarted via CandleNet eBP
application management facilities and obtains its security credentials without
any user interaction.
In this implementation, an MQSecure user ID is created for each eBP client
and business element that is exchanging messages in the secure service.
The following steps outline the setup and operation of this solution.
1. Install CandleNet eBP on each node on which eBP applications will be
hosted, configuring them to use an LDAP server, for example HS010.
2. Create eBP client applications and client records “bankClnt01” and
“bankClnt02”, each of which has full MQSecure Connection security
(kmlxcils) enabled as an inline service.
3. Create eBP server application and business element records “bankSrv01”
and “bankSrv02”, each of which has full MQSecure Connection security
4. These business elements are configured in the eBP Directory
Administrator under the business service “doTransSvc”.

Usage Scenarios
5. Install MQSecure on each node on which secure eBP applications will be

hosted and set up public key distribution to the LDAP server installed in
step 1.
6. Use mqs_adm -g to add the MQSecure user IDs “bankClnt01”,
“bankClnt02”, “bankSrv01”, and “bankSrv02” on their respective host
machines and publish their public keys to the central LDAP repository.
7. Create secure side files named bankClnt01.ssf, bankClnt02.ssf,
bankSrv01.ssf, and bankSrv02.ssf, containing the encrypted
passwords for the MQSecure user IDs “bankClnt01”, “bankClnt02”,
“bankSrv01”, and “bankSrv02”, on the host on which each application
will run.
Locate the side files in the directories in which the eBP clients and server
applications are run, or in the default CANDLE_ROMA_HOME\ssf (Windows)
or CANDLE_ROMA_HOME/ssf (UNIX) directory on the respective hosts.
Now when either of the clients sends a message it is signed with the client’s
private key (obtained by accessing the associated password from the side file
whose name matches that of the client) and encrypted using the public key of
the target server. When the server receives the message, it is decrypted using
the server’s private key (obtained by accessing the password in the associated
side file) and authenticated using the client’s public key.
When the server sends a response to the client, it is signed using the server’s
private key and encrypted using the public key of the target client. When the
client receives the response, it is decrypted using the client’s private key
obtained and authenticated as being sent by a trusted server.
Note that eBP client and server applications will attempt to open and retrieve
their respective MQSecure passwords from the side file named <eBP
client / business element name>.ssf when the application
initializes. However failure to open the file is not reported until the first
attempt to send or receive a message via CandleNet eBP is made. This is
because MQSecure Connection is not aware until that point if the application
is going to pass the password programmatically, as in the interactive solution.
Transparent Solution with single sender and receiver IDs

In this solution only one MQSecure user ID is created for all eBP clients and
only one for all business elements that are exchanging messages. However, all

Usage Scenarios
clients and business elements must have the MQSecure Connection ILS
enabled. The user IDs for both senders and receivers are provided to
MQSecure Connection by the secure side files.
Note that in this solution all client and server applications that are using a
common MQSecure ID must reside on the same machine. This is because
MQSecure user IDs must be unique enterprise-wise: the private key associated
with an ID can only be held in one MQSecure database and that database can
only be accessed locally.
The following steps outline the setup and operation of this solution.
1. Install CandleNet eBP on each node on which eBP applicaitons will be
hosted, configuring them to use an LDAP server, for example HS010.
2. Create eBP client applications and client records “bnkClnt01” and
“bnkClnt02”, each of which has full MQSecure Connection security
3. Create eBP server applications and business element records “bnkSrv01”
and “bnkSrv02”, each of which has the MQSecure Connection ILS
4. These business elements are configured in eBP under the business service
“doBnkTransSvc”.
5. Install MQSecure and set up public key distribution to the existing eBP
LDAP repository (HS010).
6. Create MQSecure user IDs “bankClnts” on the eBP client host (HC01)
and “bankSrvs” on the eBP server host (HS01) and publish their public
keys to the central LDAP repository.
7. Create the clients’ secure side file, kmlxcuid.ssf on HC01 with:
– the password for MQSecure user ID “bankClnts”
– the MQ Secure alternative (override) sender ID, “bankClnts”
– the MQSecure alternative (override) destination ID, “bankSrvs”
For example:
kmlxcssf -u bankClnts -p SecretClPwd -f bankClnts -d
bankSrvs
Locate the side file in the directory in which the eBP clients are run or in the
default Candle home ssf directory.

Usage Scenarios
8. Create the servers’ secure side files bankSrv01.ssf and

bankSrv02.ssf on HS01 with:
– the passwords for the MQSecure user ID “bankSrvs”
– the MQSecure alternative (override) sender ID, “bankSrvs”
– the MQSecure alternative (override) destination IDs “bankSrvs” and
“bankClnts”, respectively
For example:
kmlxcssf -u bankSrvs -p SecretSvrPwd -f bankSrv02 -d
bankClnts
Locate the side file in the directory in which the eBP servers are run or in the
default Candle home ssf directory.
To further protect the files, the access permissions on the files must be set so
that only the operating system user ID that the eBP applications are started
under have read access to them.
When the client and server applications start, they pick up the relevant side
file. When either of the clients sends a message, it is signed with the private
key of the override sender ID “bankClnts” private key and encrypted with the
public of the override destination ID “bankSvrs”.
When the first server receives a message, it decrypts it using the private key of
the servers’ override ID “bankSvrs”.
When the server replies to the client application, it uses the override sender ID
“bankSvrs” and its associated password to sign the message and the public
key of the override destination ID “bankClnts” to encrypt the message.
When a client receives a response message, it decrypts it using the override
ID “bankClnts” private key, and authenticates the signing of the message.
Note that the eBP client and server application's MQSecure Connection will
attempt to open and retrieve the appropriate MQSecure password from the
side file named <eBP client / business element name>.ssf
when the application initializes. Since no file of this name exists, it then looks
for a file named kmlxcuid.ssf.
Failure to open the file is not reported until the first attempt to send or receive
a message via eBP is made. This is because the ILS is not aware until that

Usage Scenarios
point if the application will pass the password via a method other than a
secure side file.
Interactive solution
This solution requires a minimal amount of application development to
achieve MQSecure integration, but allows the banking applications to use an
interactive or other secure method of obtaining their security credentials.
The setup and operation of this scenario is identical to the transparent
solution with the exception that the MQSecure credentials are obtained from
the application code rather than the secure side files.
The following outlines the setup and operation of this solution.
1. Install eBP, if necessary.
2. Install MQSecure and set up public key distribution to the existing
CandleNet eBP LDAP server.
3. Create eBP client application and client records “bankClnt01” and
“bankClnt02”, each of which has MQSecure Connection enabled by
specifying kmfxcils on the Inline Services tab of its properties settings.
4. Create eBP server application and business element records
“bankSrv01” and “bankSrv02” under the business services “getBalSvc”
and “doTransSvc”, respectively. Each business element has MQSecure
Connection enabled by specifying kmfxcils on the Inline Services tab
of its properties settings.
5. The eBP client and server applications reference the MQSecure
Connection header file kmfxcils.h so they can create an MQSecure
Connection data structure, KXCMQSECINFO. This structure is populated
with the password associated with the user ID of the respective client or
server, obtained as determined by the application developer. This
structure also indicates whether message signing and/or encryption should
be performed.
6. The structure is passed to the MQSecure connection via an eBP data
buffer KXCILSOPT using the C function KXCSETILSDATA or other
language equivalents.

Usage Scenarios
7. Create MQSecure user IDs “bankClnt01”, “bankClnt02”, “bankSrv01”,

and “bankSrv02” and publish their public keys to the LDAP repository.
The passwords associated with these user IDs are provided by the
mechanism established in Step 4.
When the eBP client and server applications are started, they must complete
the process established in Step 4 to obtain their security credentials.
Now when either of the clients sends a message it is signed with the client’s
private key and encrypted with the public key of the target service.
When a server receives a message, it decrypts the message using the server’s
private key, then determines which client issued the message and uses the
appropriate public key to authenticate its signing.
Advanced solution for partially exposed environment

In complex business flows which span many applications it is desireable to
avoid the unnecessary overhead of encrypting every hop of the flow by
securing only those parts of the flow which are exposed to risk of attack. The
following scenario describes such a scenario in a B2B CandleNet eBP service
architecture (see Figure 14 on page 185).
The company providing the service wants to secure and authenticate
customers’ service requests as they arrive over the B2B network. However,
the company wants to optimize the processing of validated requests by
internal applications. Since the internal systems are not vulnerable to attack,
the company has decided not to apply security to the internal message flows.
The clients and any server applications located in the message flow which are
vulnerable to attack are configured with kmlxcils to apply signing and
encryption on message sent and decryption and validation on messages
received.
Server2, which is located at the boundary where requests are be received
from the vulnerable messaging transport and sent on in the safe messaging
transport, is configured in the normal way with a MQSecure user ID and
secure side file. However, the eBP inline service configured is kmlxcilsg.
This ILS is active only on eBP getRequest() / getResponse() operations. Thus,
decryption occurs on Server2’s getRequest(), but the ongoing message sent
by the application’s putResponse() is not be encrypted or signed.

Usage Scenarios
Server5, which is located at the boundary where requests will be received on

the safe messaging transport and sent on in the vulnerable messaging
transport is also configured in the normal way with a MQSecure user ID and
side file. However, the eBP in-line service configured is kmlxcilsp.
This specialized ILS is activated only on eBP putRequest() / putResponse()
operations. Thus encryption occurs on the Server5’s putResponse(), but the
incoming message received and processed by the application’s getRequest() is
not be decrypted.
FIGURE 14. Securing a Partially-exposed Environment
kmlxcilsg These servers act as a

Security applied only firewall. All parts of the flow
on get operations behind them are trusted.
kmlxcils
Security applied on both
get and put operations Server2
getRequest() putResponse()
Server4
putResponse() Server3
Server1
getRequest()
Server5
putResponse() getRequest()
putRequest()
Client
getResponse()
No security overhead
kmlxcils kmlxcilsp on processing of internal
Security applied on both Security applied only messages on safe
get and put operations on put operations transport
Secure
Clear text
messages

Usage Scenarios
Scenario 1: Transparent Solution
eBP MQSecure Connection Scenario 1

Host “H01”
Sign with private key “bankClnt01”

Encrypt with public key “bankSrv02” Business Service “doTransSvc”
Decrypt with private key “bankSrv01” Host “Hs010”
bankClnt01
bankSrv01 bankSrv01.ssf
>password
bankClnt01.ssf Decrypt with private
>password key “bankClnt01”
kmlxcils
MQSecure DB Sign with private key “bankSrv01”

Private Key “Clnt01” Encrypt with public key “bankSrv02”
Decrypt with private key “bankSrv02”

Sign with private key
Host “H02” “bankSrv02” Encrypt with
public key “bankClnt01” kmlxcils
Sign with private key “bankClnt02” bankSrv02.ssf
Encrypt with public key “bankSrv02” >password
bankSrv02
Sign with private key “BE02”
bankClnt02 Encrypt with public key “bankClnt01”
bankClnt02.ssf Decrypt with private LDAP

>password key “bankClnt02” MQSecure DB
Public Key “bankClnt01” Private Key “bankSrv01”
Public Key “bankClnt02” Private Key “bankSrv02”
MQSecure DB
Private Key “Clnt02” Public Key “bankSrv01”
Public Key “bankSrv02”

Utilities
B
Overview
This appendix documents the utility programs supplied with PathWAI Secure.
Appendix Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
Administrative Utilities for Distributed Systems . . . . . . . . . . . . . . . . . . . . 189
Administrative Utility for OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
Public Key Monitor for Distributed Systems . . . . . . . . . . . . . . . . . . . . . . 204
Public Key Monitor for OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
Validation Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Database Conversion Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211
Utilities 187
Introduction
Introduction
Overview
PathWAI Secure supplies utilities that support key administration for both
distributed platforms and OS/390. It also provides utilities that monitor special
WebSphere MQ queues to import public keys from remote systems and
programs that can be used to validate or test your PathWAI Secure
configuration.
n mqs_adm (server), mqs_admc (client), and KMFADM (OS/390)—
Provide administrative functions such as registration and revocation of
user IDs and keys, and creation and distribution of keys.
n mqs_read and KMFREAD—Public key monitor function
n mqdirect and mqdirecc—Programs using PathWAI Secure direct APIs
that can be used to test configuration and to troubleshoot problems
n mqs_op (server), mqs_opc (client), and MQS@OP (OS/390)—
Programs using PathWAI Secure integrated APIs that can be used to test
configuration and to troubleshoot problems

Administrative Utilities for Distributed Systems
Description
All of the PathWAI Secure administrative functions on UNIX and Windows
systems are conducted using mqs_adm (for servers) or mqs_admc (for
clients).
The administrative functions supported are:
n registration of user IDs and generation or importation of user
public/private key pairs, certificates, and certificate revocation lists
n distribution of keys (import and export) and certificates
n revocation of PathWAI Secure-generated and keys
n resynchronization of local and LDAP user key databases
n re-encryption of user key database
mqs_adm and mqs_admc are command line utilities. Their functions are
invoked using the parameters documented in Table 7 on page 190. You can
also enter the parameters for all the functions you want to execute at one time
from the command line without waiting for prompts. This allows system
administrators who need to perform multiple configuration tasks to collect all
the administrative commands in a single file and execute them with one
keystroke. (Refer to “Command syntax” on page 199 for the syntax for
entering commands without prompts.)
Parameters
Note: If you want mqs_adm or mqs_admc to translate imported or exported
user records to or from a special code page, you must set the
MQSECURE_CCSID environment variable to the appropriate local
code page prior to invoking mqs_adm or mqs_admc. On Windows
NT, use the set command or the System/Environment panel in the
control panel settings. On Windows, use the set command prior to
invoking mqs_adm or mqs_admc, or add the set command to
autoexec.bat. On UNIX, use setenv (C-shell) or export (Korn-Shell).
Utilities 189
Table 7. Parameters for mqs_adm and mqs_admc
Parameters Function Description

-a -f export Used by the local PathWAI Secure administrator, this is
administrator’s key the only method to export the administrator’s public
to file key. The message is not signed. This is useful in the
initial setup of PathWAI Secure on two peer nodes,
when the administrators on the two nodes don’t know
each other’s public keys. No signature verification is
possible.
mqs_adm -a -f filename or mqs_admc -a -f
filename
-b force an action Used with -s or -g. Allows the administrator to force
without the reset of a database or the creation of a duplicate
confirmation user ID without having to respond to a confirmation
prompt prompt
mqs_adm -g -b or mqs_adm -s -b
-d revoke user For PathWAI Secure-generated keys only: Used by the
administrator to revoke a user ID and all associated
information in the user key database and the LDAP
repository, if any.
A list of user IDs is presented from which to delete.
When done entering user IDs and passwords, the
administrator enters /X to end this function. The user
ID is not actually deleted and will still be visible in any
user ID list, flagged as (R).
mqs_adm -d or mqs_admc -d
-d -t delete user Used by the administrator to delete a user record and
all associated information from the user key database
and the LDAP repository, if any.
A list of user IDs is presented from which to delete.
When done entering user IDs and passwords, the
administrator enters /X to end this function. The user
ID is actually deleted and can be reinstated.
mqs_adm -d -t or mqs_admc -d -t

Table 7. Parameters for mqs_adm and mqs_admc (continued)

-e -c -f export users’ Used by the administrator to export selected
certificates to a certificates in a signed PKCS#7 format message.
PKCS#7 file This command is typically used if the certificates
cannot be distributed through a central shared
repository—that is, in a business-to-business situation
where there is no shared LDAP repository or at sites
where an LDAP repository is not configured.
mqs_adm -e -c -f PKCS#7filename or
mqs_admc -e -c -f PKCS#7filename
-e -c -f -t export trusted Global Administrator only. Used to export certificates
public key from the GA’s trusted database in a signed PKCS#7
certificates to a message format.
PKCS#7 file Typically used to export certificates used to establish
the verification chain for message-embedded public
keys.
mqs_adm -e -f PKCS#7filename -t or
mqs_admc -e -f PKCS#7filename -t
-e -c -r (-t) export all certificates Global Administrator only. Used by the Global
to LDAP repository Administrator to export verification certificates to the
LDAP repository. If -t is used, all trusted certificates are
exported.
mqs_adm -e -c -r or mqs_admc -e -c
-r
Utilities 191

-e -f export users’ public Used by the administrator to export a file (signed
keys to a file message) of user IDs and their public keys. The
administrator is presented with a list of users to select
for export.
This file is normally written to a diskette, so that it may
be physically carried to another system. If a revoked
user ID is selected, this effectively revokes that user ID
when it is imported on the target system. Until then,
the previous public key is still available on the target
system.
mqs_adm -e -f filename or
mqs_admc -e -f filename


-e -m -q export users’ public Used by the administrator to export one or more user
keys to queue IDs and their public keys to a target system using
manager signed MQ messages. The administrator is presented
with a list of users from which to select. These
messages are read by the mqs_read program on the
target system.
This function is not available on PathWAI Secure
clients and should not be used for exporting
administrators’ keys. The public key of the exporting
administrator must be available to the target system for
verification of the exported keys before user keys can
be imported on the target system.
The queue manager specified in the -m parameter can
be either the remote queue manager (the target
system) or a local queue manager. If a remote queue
manager is specified, no queue name will be specified,
as this defaults to SYSTEM.MQSECURE.COMMANDS .
The message is put to a local default queue manager.
This means that you must configure:
1. a transmit queue with the same name as the
remote queue manager
2. a sending channel which uses the transmit queue
If the queue manager specified in the -m parameter is
a local queue manager, the -q parameter must be the
name of the local definition of a remote queue, which
points to SYSTEM.MQSECURE.COMMANDS on the
target system. For example, if you specify a local
queue manager, using the mqs_adm -e -m qmgr
-q queue command, you must have defined a local
definition of a remote queue. If you specify a remote
queue manager using the mqs_adm -e -m qmgr
command, you must have defined a local transmit
queue with the same name of the remote queue
manager on the target system.
If a revoked user ID is exported, the user ID is revoked
on the target system. Until then, the previous public
key is still available on the target system.
Utilities 193

-e -r export public keys Used to export selected local public keys to the LDAP
to the LDAP repository.
repository Typically used only by the Global Administrator to
export PathWAI Secure-generated administrators’
public keys, it may also be used by local administrators
to export keys generated, imported, or revoked while
connection to the LDAP repository was not available.
mqs_adm -e -r or mqs_admc -e -r
-e -y -f export private key Used to export a private key/public key certificate pair
and public key to a PKCS#12 file. The administrator is prompted to
certificate to a provide a password for encrypting the private key; if
password-encrypted no password is provided, a random one is generated
PKCS#12 file and used for encryption.
Typically used only by a Global Administrator to
distribute administrators’ imported key pairs.
mqs_adm -e -y -f PKCS#12filename or
mqs_admc -e -y -f PKCS#12filename
-g create user key pair Requests that PathWAI Secure create and store a
public/private key pair and export the public key to an
LDAP repository, if configured. After it is invoked, the
administrator is asked for the user ID and password to
be associated with the keys. If the user ID already exists
in the user key database (and is not revoked), the
administrator is asked if new keys should be generated
for this user.
mqs_adm -g or mqs_admc -g


-g -f import user key pair Used to register a PathWAI Secure user by importing a
PKCS#12 file, storing the private key/public key
certificate pair in the local databases, and exporting the
public key certificate to an LDAP repository, if
configured.
The administrator is asked to supply the password
used to encrypt the private key. This password must
have been securely communicated to the administrator
before the file containing the keys is imported.
A PathWAI Secure user ID is created based on the
Distinguished Name of the certificate holder and the
administrator is asked to provide the password to be
associated with the user ID.
mqs_adm -g -f pkcs#12filename or
mqs_admc -g -f pkcs#12filename
-i -c -f import certificates Used by an administrator to import a PCKS#7 file
containing certificates needed to verify imported keys.
The certificates are stored in the local nontrusted
certificate database, even if they carry a trusted flag.
mqs_adm -i -c -f pkcs#7filename or
mqs_admc -i -c -f pkcs#7filename
-i -c -f -t import trusted Used by an administrator to import public a PCKS#7
certificates containing certificates needed to verify imported keys.
The certificates are stored in the local trusted certificate
database.
mqs_adm -i -c -f -t pkcs#7filename
or mqs_admc -i -c -f -t
pkcs#7filename
Utilities 195

-i -f import public keys Used by the administrator to import public keys
previously exported to a file on another PathWAI
Secure node into the local user key database.
The public key of the administrator of the exporting
node must be available (either in the local user key
database or the LDAP repository, if any) to verify the
imported public key.
mqs_adm -i -f filename or mqs_admc
-i -f filename
-i -r refresh all “foreign” Used by local administrators to resynchronize “foreign”
public keys user public keys stored locally with updated keys in the
previously imported LDAP repository. Also imports certificate revocation
from LDAP lists so that both users with PathWAI Secure-generated
repository keys and those with third-party generated keys who
have been revoked are captured.
mqs_adm -i -r or mqs_admc -i -r
-k regenerate user key Used to both regenerate an encryption key and to
database encryption re-encrypt the database
key and re-encrypt
database
mqs_adm -k or mqs_admc -k
-l override default Used with -s (generate new administrator key) or -g
length (modulus (generate new user key) to specify length (modulus
size) of asymmetric size) of asymmetric keys. Any modulus size between
key 768 and 2048 bits can be used, but the value should
be divisible by 8.
This switch cannot be used when importing third party
keys in a PKCS#12 file (-f).
mqs_adm -g -l 1024 or mqs_admc -g -l
1024
-p change users’ Used by administrators or users to change their
passwords passwords


mqs_adm -p or mqs_admc -p
-s initialize Used by the administrator to set up the administrative
administrator’s key environment for an PathWAI Secure node by:
and create or reset n emptying the existing user key database, if any
user key database n setting the administrator’s user ID and password
using PathWAI
n generating the administrator’s public/private key
Secure-generated
keys pair and storing it in the user key database
(MQSS.USR)
If the user key database is not empty, PathWAI Secure
asks if it should initialize the user key database anyway.
If the node is configured to use an LDAP repository,
the administrator is prompted for the LDAP user ID
and password to be used for exporting public keys.
PathWAI Secure prompts for the administrator ID and
password to be associated with the keys.
All subsequent mqs_adm sessions are validated
against the user ID and password supplied now. The
administrator becomes the certification authority (CA)
for this node and the administrator’s public key must
be distributed to all communicating PathWAI Secure
nodes
mqs_adm -s or mqs_admc -s
Utilities 197

-s -f initialize Used by the administrator to set up the administrative
administrator’s key environment for PathWAI Secure by:
and create or reset n emptying the existing user key database, if any
user key database n setting the administrator’s user ID and password
using imported keys
n importing a PKCS#12 file containing the
administrator’s public/private key pair, storing the
keys in the user key database (MQSS.USR), and
the public key certificate in the certificate database.
This command also imports certificate revocation lists
(CRLs).
The administrator is prompted to supply the password
used to encrypted the private key. This password must
have been securely communicated to the administrator
before the file is imported.
The PathWAI Secure user ID is created based on the
Distinguished Name of the subject of the certificate,
and the administrator is asked to supply the PathWAI
Secure password to be associated with this ID.
If the node is configured to use an LDAP repository,
the administrator is prompted for the LDAP user ID
and password to be used for exporting public keys.
The public key certificate is automatically exported to
the LDAP repository.
All subsequent mqs_adm sessions are validated
against the user ID and password supplied now. The
administrator becomes the certification authority (CA)
for this node.
mqs_adm -s -f pkcs#12filename or
mqs_admc -s -f pkcs#12filename
-s -r set/reset user ID and Used by an administrator to initialize the user ID and
password required password for exporting keys to the LDAP repository, or
for LDAP repository to change the user ID and password
public key updates


-u list registered users Used by the administrator to obtain a list of user IDs for
whom public (and, possibly, private) keys are known
in the local PathWAI Secure user key database
mqs_adm -u or mqs_admc -u
-u -c list nontrusted Used by the administrator to obtain a list of certificates
certificates known in the local PathWAI Secure nontrusted
certificate database
mqs_adm -u -c or mqs_admc -u -c
-u -c -t list trusted Used by the administrator to obtain a list of certificates
certificates in the local PathWAI Secure trusted certificate database
mqs_adm -u -c -t or mqs_admc -u -c
-t
Command syntax
You can enter mqs_adm and mqs_admc parameters without waiting for the
prompts. The parameters and parameter switches shown in brackets ([ ]) are
optional. However, if one of the following parameters is specified, they must
all be specified.
For example, if you specify the system administrator ID and password on the
command line for the key generation function, you must enter all the required
parameters (user ID and password) on the command line.
mqs_adm(c) [adminID adminPwd] -a -f filename
mqs_adm(c) [adminID adminPwd] -d [userid]
mqs_adm(c) [adminID adminPwd] -d [userid] -t
mqs_adm(c) [adminID adminPwd] -e [userid] -f filename
mqs_adm(c) [adminID adminPwd] -e [userid] -c -f filename
mqs_adm(c) [adminID adminPwd] -e [userid] -m qmgr
[-q qname]
mqs_adm(c) [adminID adminPwd] -e [userid] -r
Utilities 199
mqs_adm(c) [adminID adminPwd] -e [userid] -c -f filename

-t
mqs_adm(c) [adminID adminPwd] -e [“”] -c -r -t
mqs_adm(c) [adminID adminPwd] -e -y -f filename
[-h pkcs12password -p password]
mqs_adm(c) [adminID adminPwd] -g [userid -p password -b]
{-l modulusLen}
mqs_adm(c) [adminID adminPwd] -g [“”] -f filename[-h
pkcs12password -p password -b]
mqs_adm(c) [adminID adminPwd] -i -f filename
mqs_adm(c) [adminID adminPwd] -i -c -f filename [-t]
mqs_adm(c) [adminID adminPwd] -i -r
mqs_adm(c) [adminID adminPwd] -k
mqs_adm(c) [adminID/userID adminPwd/userPwd] -p
[password]
mqs_adm(c) [adminID adminPwd] -s [-v ldapID -w ldapPwd
-b] {-l modulusLen }
mqs_adm(c) [“” adminPwd] -s -f filename
[-h pkcs12password [-v ldapID -w ldapPwd] ]
mqs_adm(c) [adminID adminPwd] -s -r [-v ldapID -w
ldapPwd]
mqs_adm(c) [adminID adminPwd] -u
mqs_adm(c) [adminID adminPwd] -u -c [-t]
Notes:
n -q qname is an optional parameter of -e -m qmgr function, with or
without the command line enhancement.
n -l modulusLen is an optional parameter for the key generation and
database initialization functions, with or without the command line
enhancement.
n Only one user ID can be specified on a command line.

n -b is an optional parameter for the key generation and database

initialization functions. It bypasses the confirmation step of regenerating a
new user key to replace the old key, or resetting the user key database if it
exists.
n -t is an optional parameter for exporting and importing certificates. Only
the Global Administrator’s administrative utility supports the use of this
parameter with the export command (mqs_adm -e -c -f ). Local
administrators can use the parameter with the import command.
However, if the certificates have not been previously exported by the
Global Administration with the trust flag set, the certificates will not be
placed in the local trusted certificate database.
Figure 15 shows a sample command file.
FIGURE 15. Sample Command File cmdline.bat
mqs_adm WPWNTBADM WNTBADM -s -v cn=manager -w secret -b -l

mqs_adm WPWNTBADM WNTBADM -s -r -V cn=manager -W secret
mqs_adm WPWNTBADM WNTBADM -g WPWNTBTS1 -p WNTBTS1 -l 1024
mqs_adm WPWNTBADM WNTBADM -d WPWNTBTS1
mqs_adm WPWNTBADM WNTBADM -g WPWNTBTS1 -p WNTBTS1 -l 1024
mqs_adm WPWNTBADM WNTBADM -a -f \MQSWORK\WPWNTB.ADM
mqs_adm WPWNTBADM WNTBADM -e WPWNTBTS1 -f \MQSWORK\WNTBTS1
mqs_adm WPWNTBADM WNTBADM -i -f \MQSWORK\V2HPXA.ADM
mqs_adm WPWNTBADM WNTBADM -k
mqs_adm WPWNTBADM WNTBADM -p WNTBADM
mqs_adm WPWNTBADM WNTBADM -u
Utilities 201
Administrative Utility for OS/390
Description
KMFADM is the REXX equivalent of mqs_adm and mqs_admc on
distributed platforms. It is used to perform the following administrative
functions:
n registration of user IDs and generation or importation of user
public/private key pairs, certificates, and certificate revocation lists
n distribution (import and export) of keys and certificates
n revocation of PathWAI Secure-generated and keys
n resynchronization of local and LDAP user key databases
n re-encryption of user key database
Invoking KMFADM functions

KMFADM is invoked from ISPF option 6.
Administrative command menus are accessed from the KMFADM main menu
(see Figure 16 on page 203). Online help for each menu is available by
pressing PF1 or PF13.
The first time a user ID uses KMFADM, KMFADM prompts for &hilevdsn,
&cleds, &mqsauthds, and &mqloadds dataset names (see below). These
names should be available from the worksheet filled out at installation.
If you are re-installing PathWAI Secure in a different dataset than the previous
install, you must reset the ISPF PROFILE. This is done by deleting the
members MQSSPROF and MQSXPROF from the &tsouid.ispf.ispprof
dataset.
Where is
&apfdsn. APF-authorized dataset name
&cleds. C language environment dataset
&hilevdsn. High-level dataset name

Where is
&mqauthds. WebSphere MQ authorization dataset
&mqloadds. WebSphere MQ load dataset
&mqnlsds. WebSphere MQ national language support dataset
&rexxdsn. Rexx executable PDS
&tsouid the TSO user ID
FIGURE 16. KMFADM Main Menu
Utilities 203
Public Key Monitor for Distributed Systems
Public Key Monitor for Distributed Systems
Description
The mqs_read utility acts as the processor of the
SYSTEM.MQSECURE.COMMAND queue, which receives signed messages
containing public keys sent by other systems via a queue manager (see
“Exporting keys via a queue manager” on page 120). This program is
triggered through normal MQSeries triggering on distributed systems.
When the program gets a signed message from the command queue, it inserts
(or updates) the public key into the user key database. Aside from the
mqs_adm function to import keys, this is the only program that can update
or add keys to the user key database.

Public Key Monitor for OS/390
Description
The KMFREAD utility is the REXX equivalent of mqs_read on the
distributed platforms. KMFREAD acts as the processor of the
SYSTEM.MQSECURE.COMMAND queue, which receives signed messages
that contain public keys sent by other systems via a queue manager. It uses
variables established using KMFADM.
Note: The MQSeries administrator should ensure that the
SYSTEM.MQSECURE.COMMANDS queue is sufficiently secured.
This is especially important in client/server configurations, where each
PathWAI Secure client can also be an PathWAI Secure administrator.
Aside from the KMFADM function to import keys, this is the only program
that can update or add keys to the user key database.
Invoking KMFREAD
This utility can be invoked from either ISPF or native TSO. After the program
gets the message from the command queue, it inserts (or updates) the public
key into the user key database. KMFREAD is located at:
’&hilevdsn.TMFEXECF(KMFREAD)’
or
’&hilevdsn.TMFEXECV(KMFREAD)’
Make the following changes before using KMFREAD:
DD Names The ISPLLIB or STEPLIB DD Name statements must be

modified in your TSO user log-on procedure before this utility
can be used. If the ISPLLIB is updated, KMFREAD will run
only from ISPF. If STEPLIB is updated, KMFREAD will run
from both ISPF and native TSO.
LE370 Load Lib The PP.LE370.VnRnMn.SCEERUN C language environment
dataset. The user system dataset qualifiers for C/370 libraries
may need to be changed to two different high-level qualifiers if
the installation has both C/370 and PL/I.
Utilities 205
IBM MQSeries The high-level qualifier of the WebSphere MQ target library

datasets:
APF Authorized Load Lib *.SCSQAUTH
Utilities Load Lib *.SCSQLOAD
NLS Load Lib *.SCSQANLE
The KMFREAD syntax is:

KMFREAD QMGR(xqmgr) USERS(xusers) <SUFFIX(xsuffix)>
LOADLIB(xloadlib)
where:
xqmgr Queue Manager Name of the

SYSTEM.MQSECURE.COMMANDS queue to examine for
user public key updates
xusers Fully-qualified dataset name of the user key database cluster
name
suffix An optional alphanumeric character that distinguishes the user
key database server from any other servers that may be
active. If not provided, a default suffix will be used.
xloadlib Fully-qualified dataset name of the PathWAI Secure Load
library (&hilevdsn.TMFLOAD)
See also“KMFREAD return codes” on page 234.

Validation Programs
Validation Programs
Overview
Candle provides a set of validation programs that can be used to exercise the
direct and integrated API functions. They are intended as services aids,
typically used when working with Candle support personnel or when verifying
installation.
The mqdirect (servers) and mqdirecc (clients) programs use direct API
functions. The mqs_op (server), mqs_opc (client), or MQS@OP (on
OS/390 systems) programs use the integrated API functions.
Table 17 on page 209 shows a sample JCL for running the MQDIRECT and
MQDIRECC validation programs on OS/390.
MQDIRECT and MQDIRECC
Syntax
mqdirect {-s|e|r|g|w|x|y|z}
mqdirecc {-f filename}
[-c count]
{-q qname}
[-m qmgrname]
{-l msglen}
[-t trailers]
Parameters
-s Sign the message and put in the queue

-e Encrypt the message and put in the queue
-r Encrypt parts of the message and put in the queue
-g Get a message from the queue
-w Encrypt then sign the message and put in the queue. You
must specify -g -t 2 to retrieve messages placed in the
queue using this parameter.
Utilities 207
Validation Programs
-x Encrypt parts of the message then sign and put in the

queue. You must specify -g -t 2 to retrieve messages placed
in the queue using this parameter.
-y Sign then encrypt the message and put in the queue. You
-z Sign then encrypt parts of the message and put in the
-f filename Filename of the message. This parameter is not used on
OS/390 systems. You are prompted for a member name.
-c count Optional repetition count value
-q qname Message queue name
-m qmgrname Optional queue manager name
-l msglen Size of the message buffer to allocate (mandatory with -g
parameter)
-t Number of trailers to analyze (optional with -g parameter).
Specify -t 2 for invocations which specify the -g parameter
to get a message that was originally placed on the queue
using -w, -x, -y, or -z.
Return codes
See “PathWAI Secure Messages and Return Codes” on page 222.

Validation Programs
FIGURE 17. Sample JCL for Validation Programs
//*
//* THIS STEP EXECUTES THE MQDIRECT SAMPLE PROGRAM
//*
//MQINDIR EXEC PGM=MQDIRECT,
// PARM=(’userid password destid -w -M QMGR -q TEST.Q
-F DD:INDD’)
//STEPLIB DD DISP=SHR,DSN=MQSECURE.TMFLOAD
// DD DISP=SHR,DSN=MQSERIES.TLIB.SCSQAUTH
// DD DISP=SHR,DSN=MQSERIES.TLIB.SCSQANLE
//MQSSUSRx DD DUMMY
//SYSOUT DD SYSOUT=*
//SYSIN DD DUMMY
//SYSPRINT DD SYSOUT=*
//SYSMDUMP DD SYSOUT=*
//INDD DD DISP=SHR,DSN=MQSECURE.MESSAGE(MED)
Where userid and password are the PathWAI Secure user ID and password of the sender, and
destid is the PathWAI Secure ID of the receiver for which the message is encrypted.
MQS_OP, MQS_OPC, MQS@OP
Syntax
mqs_op {-s|e|r|g}
mqs_opc {-f filename}
[-c count]
{-q qname}
[-m qmgrname]
{-l msglen}
[-t trailer]
Utilities 209
Validation Programs
Parameters
-s Sign the message and put in the queue

-e Encrypt the message and put in the queue
-r Encrypt parts of the message and put in the queue
-g Get a message from the queue
-w Encrypt then sign the message and put in the queue. You
-x Encrypt parts of the message then sign and put in the
-y Sign then encrypt the message and put in the queue. You
-z Sign then encrypt parts of the message and put in the
-f filename Filename of the message. This parameter is not used on
OS/390 systems. You will be prompted for a member name.
-c count Optional repetition count value
-q qname Message queue name
-m qmgrname Optional queue manager name
-l msglen Size of the message buffer to allocate (mandatory with -g
parameter)
-t Number of trailers to analyze (optional with -g parameter).
Specify -t 2 for invocations which specify the -g parameter
to get a message that was originally placed on the queue
using -w, -x, -y, or -z.
Return Codes
None.

Database Conversion Program
Description
kmfconv converts a PathWAI Secure user key database from Version 210
format to Version 300 format. This is necessary because in Version 300 the
database records have become longer. You cannot use a Version 210
database with PathWAI Secure Version 300 unless it has been converted.
If you migrated to Version 300 from an earlier version, you converted your
databases when you installed PathWAI Secure on each node. However, you
may have backed up databases in Version 210 format. You must convert
these databases before you can use them.
Windows and UNIX

To convert a database:
1. Ensure that the database to be converted has the name MQSS.USR and is
located in the MQSSDIR directory on Windows or /var/mqsecure on
UNIX.
2. Shut down all PathWAI Secure applications.
3. From a command prompt, issue:
dbdown
4. Issue:
kmfconv [admin_id] [admin_pwd]
where admin_id is the user ID of the administrator of the database and
admin_pwd is the associated password.
OS/390
On OS/390, kmfconv is shipped as &hilev.TMFSAMP(KMFCONV).
To convert a database :
1. Modify the JCL according to instructions in the JCL.
2. Submit the JCL.
Utilities 211
Note: To use the new database, ensure that its name is pointed to by the
USERS DD in MFSSRVR and specified in KMFADM. (You may want
to rename the old database prior to running the job and ensure that
the new database has the same name as the database it replaces.)

Troubleshooting
C
Overview
This appendix provides advice for troubleshooting problems frequently
encountered by PathWAI Secure users.
Appendix contents
PathWAI Secure–LDAP Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
PathWAI Secure Hardware Crypto Interface . . . . . . . . . . . . . . . . . . . . . . 215
Transmission Failures in OS/390 Client Connections. . . . . . . . . . . . . . . . 219
UNIX Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Troubleshooting 213
PathWAI Secure–LDAP Connection
PathWAI Secure–LDAP Connection
Initialization error 1
This error occurs when PathWAI Secure cannot read the two LDAP system
variables:
MQSECURE_LDAP_SERVER_ADDRESS
MQSECURE_LDAP_SERVER_PORT
Consult “LDAP Repository” on page 41 for platform-specific instructions on
setting these system variables.
LDAP _open error

This error can occur for any of the following reasons:
n The LDAP repository server is not running.
Refer to “Starting or stopping the LDAP server” on page 137 for
instructions on starting the LDAP server on Windows NT, or “Starting or
stopping the LDAP server” on page 141 for instructions on starting the
LDAP server on UNIX.
n PathWAI Secure is unable to read the LDAP Update User ID and/or LDAP
Update Password variables.
These system variables are set by the PathWAI Secure administration
utility (mqs_adm -s -r ) or from the KMFADM LDAP maintenance panel.
They must match the rootdn and rootpw values specified when the
LDAP repository was originally installed and configured at your site.
Consult your LDAP administrator for your site's LDAP rootdn and
rootpw values. If you are using the LDAP repository provided by
Candle, refer to “Managing the LDAP Repository on Windows NT” on
page 137 for instructions on setting the LDAP user ID and password
variables. If you are using an LDAP provided by another vendor, consult
the appropriate documentation.

PathWAI Secure Hardware Crypto Interface
Overview
By design, PathWAI Secure reverts to using software if it finds during
initialization that the hardware is not available, not configured correctly, or
malfunctioning. (The hardware fault detection capabilities available to the
software are limited.) If you experience a problem with PathWAI Secure that
you believe is related to hardware support, the most expedient way to
circumvent it is by disabling hardware encryption using the PathWAI Secure
configuration tool (UNIX and Windows) or removing the setting of the
environment variable MQSECURE_HARDWARE_ENABLED, or setting it to
NULL (OS/390, UNIX, and Windows). (Refer to “Hardware Encryption” on
page 45 for instructions on enabling and disabling hardware encryption.)
PathWAI Secure will then revert to using software for all cryptographic
operations.
If you are using Windows/NT/2K with a 4758 crypto co-processor installed,
configuring PathWAI Secure back to using software after having configured for
hardware may cause errors in other applications that use CCA. Check the
setting for the PATH environment variable at the system level. The directories
containing the support libraries for the 4758 must come before the PathWAI
Secure libraries. The order of these libraries on your system path depends on
the order of installation of PathWAI Secure and the 4758 support code.
Reorder the libraries so the PathWAI Secure libraries appear after the IBM
4758 libraries.
Messages
The following messages indicate problems with hardware encryption:
CCA_Install: CCA Service not available
CCPOpen: CCA load failed, Errno: 2 A file or directory in
the path name does not exist.
CCA_Install: CCA RTE library missing
Troubleshooting 215
Troubleshooting
PathWAI Secure issues these messages when the environment variable
MQSECURE_HARDWARE_ENABLED has been set to either ADAPTER1 or
S390 and initialization of the hardware device has failed. This error can occur
for any of the following reasons:
n Hardware device not installed or installation incorrect or incomplete.
– Windows and UNIX : Review the installation process for the hardware
cryptographic coprocessor and verify that all the necessary steps
completed successfully. Verify that the adapter is installed on the
platform from which you are trying to access it.
– OS/390 : Review the microcode settings from the Hardware
Management Console (HMC) to verify that the adapter has been
properly configured. You should consult with your IBM representative
for this step.
– OS/390 : OS/390 Integrated Cryptographic Service Facility (ICSF)
system procedure is not started or not properly installed. Review the
ICSF installation procedure to verify that it was successfully
completed. You may need to manually start the ICSF procedure if
your installation has not configured it to start automatically. Review
your system log to determine if a hardware problem with the crypto
coprocessor prevented ICSF from initializing. Use the ISPF interface
to ICSF to verify that the hardware is available and functioning.
– OS/390 : Verify that your RACF administrator has granted permission
to the following CCA Services required by PathWAI Secure:
Service Name Function

CSFCKM Multiple Clear Key Import
CSFDEC Decipher callable service
CSFDSG Digital signature generate callable service
CSFDSV Digital signature verify callable service
CSFENC Encipher callable service
CSFOWH One-way hash generate callable service

Service Name Function

CSFPKD PKA decrypt callable service
CSFPKE PKA encrypt callable service
CSFPKI PKA key import callable service
CSFRNG Random number generate callable service
– OS/390 : Both the Channel Initiator started task and the PathWAI
Secure administrator must be authorized to use these services. All the
listed services must be authorized, even if you do not anticipate using
them all.
– OS/390 : When application-to-application security is used and
hardware is enabled, all applications using the PathWAI Secure direct
and indirect APIs will use the facility. Therefore, any job or started task
which uses the APIs must:
1. Have RACF authorization to use the services listed above, and
2. Be able to LOAD PathWAI Secure load library members
KMFQC390 and KMFQM390. To facilitate the LOAD, these two
members must reside in at least one of the following:
– a load library which is allocated to the job via JOBLIB or
STEPLIB DD statements,
– the link library (defined during system generation by the
LNKLSTxx member of SYS1.PARMLIB), or
– the system's link pack area (defined during system
generation).
n A problem with the hardware device prevents PathWAI Secure from using
it
Run hardware diagnostics on the coprocessor, if available. Use the
administrative utility provided by the device's manufacturer or another
application to verify functionality.
Caution: Crypto hardware devices are designed to be tamper-resistant. If
an attempt is made to penetrate the device's secure shell, or if its batteries
Troubleshooting 217
are removed, the device’s keys will be zeroized, rendering it permanently

unusable.
n The libraries for the Common Cryptographic Architecture (CCA) are not
installed, or the rights mask prevents access to the libraries
UNIX : Check the rights in the directory /usr/lib for the following CCA
libraries using the command:
ls -l
The PathWAI Secure group should have both read+execute enabled at
the all or group level.
libcsufcall.a
libcsufsapi.a
libcsufsecy.a
libds30.a
libscc.a
n The configuration of the roles for the cryptographic interface software do
not enable access to all the functions required by PathWAI Secure.
Review the step in Chapter 2,” Installation Preparation”, in the PathWAI™
Secure for WebSphere MQ Installation Guide that describes the set of
4758 Access Control Points that must be enabled to use the crypto
processor. A subset is not supported.

Transmission Failures in OS/390 Client Connections
Transmission Failures in OS/390 Client Connections
Restrictions on message length (WebSphere MQ Version 5.2)

Under certain circumstances, performing cryptographic operations and
adding control information to message transmission segments in Send
channel exits results in messages failing to be transmitted through a channel.
The problem occurs because longer messages are broken up into transmission
segments whose length depends on the underlying transport protocol. Under
TCP/IP, the maximum transmission segment length is 32K. Messages longer
than this are broken up into multiple segments. The Send–Receive channel
exit pair, the only exits available for message processing on client connections
(CLNTCONN/SVRCONN pair), cannot increase the size of segments returned
to the message channel agent beyond this limit, unless the version of
WebSphere MQ being used has the appropriate level of support and the
underlying Send channel exit deploys the required processing supported by
these WebSphere MQ levels.
The PathWAI Secure Send channel exit takes advantage of the support
provided in WebSphere MQ Version 5.2 and later which allows space to be
reserved for adding control information such as that occupied by security
trailers and additional storage required by symmetric key encryption involving
block ciphers.
WebSphere MQ Version 5.2 for OS/390 is an exception. Client connection
MQGET operations through SVRCONN channels using Send channel exits
secured by PathWAI Secure are still restricted until IBM provides the support
in that environment. MQPUT operations through the SVRCONN channels in
this environment are supported, since the required level of support is only
required in the Send channel exit.
Troubleshooting 219
UNIX Problems
UNIX Problems
rc(1866) from SetDefaultContext

If WebSphere MQ (user mqm) does not have write access to the .cdx, .dbf,
and .fpt files in /var/mqsecure, the channel exit will fail to start with the
following messages in the log:
rc(1866) from SetDefaultContext
DoInit failed with rc=1131 (Invalid Cert-C context).
Channel initiation aborted.
Ensure mqm has write access to the .cdx, .dbf, and .fpt files in
/var/mqsecure by issuing the following commands:
chmod g+w /var/mqsecure/*.cdx
chmod g+w /var/mqsecure/*.dbf
chmod g+w /var/mqsecure/*.fpt
First PathWAI Secure process hangs

If dbsrv is not prestarted, first PathWAI Secure process to start will hang until
dbsrv is stopped.
Stop dbsrv by entering the command:
dbdown
Then, start the program dbsrv before starting any other PathWAI Secure
processes. This can be done by issuing the command:
dbsrv
Unexpected results using channel exits with MQSeries Version 5.2

If the new channel performance feature known as pipelining is specified as
anything but PipeLineLength=1 (the default) in the qm.ini file, unexpected
results may occur in channels secured by PathWAI Secure channel exits.
Ensure that the parameter PipeLineLength is set to 1 in the qm.ini file of
any Queue Manager managing channels secured by PathWAI Secure channel
exits, until further notice.

Messages and Return Codes
D
Overview
This appendix contains PathWAI Secure messages and return codes. For
convenience, it also contains the RSA BSAFE return codes. As an PathWAI
Secure user, you may also see WebSphere MQ return codes. Please refer to
the appropriate WebSphere MQ documentation for the definitions of these
return codes.
Any failures of an authentication or encryption operation in the channel exits
result in the message being diverted to the PathWAI Secure problems queue,
SYSTEM.MQSECURE.PROBLEMS. A message is logged to the channel exit
log explaining the diversion and to where, along with an error message
specifying why the operation failed.
Errors returned as a result of the failure of authentication and encryption
operations in application-to-application operations must be handled by the
applications. The PathWAI Secure APIs return an error code that can be
converted to an actual message. The application should interpret the error
code and log the message.
Appendix Contents
PathWAI Secure Messages and Return Codes . . . . . . . . . . . . . . . . . . . . . 222
BSAFE Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236
Messages and Return Codes 221

PathWAI Secure Messages and Return Codes
Server Messages
MFS0000I Server address space terminated normally.

MFS0000I PathWAI Secure server address space being restarted.
MFS0001E No parameter list was supplied to KMFSRVR.
MFS0001I ESQA area successfully found/created. Address=xxxxxxxx.
MFS0001W Cache dataspace could not be extended.
MFS0001W Code page dataspace could not be extended.
MFS0002E Bad parameter supplied to KMFSRVR.
MFS0002I PathWAI Secure dataspaces successfully allocated.
MFS0003E KMFSRVR not loaded from APF-authorized library.
MFS0003I Cache dataspace structures initialized.
MFS0004E ESTAE could not be established.
MFS0004I Cross-memory environment established.
MFS0005E IEANTRT service failed to retrieve name/token pair.
MFS0005I Cache dataspace loaded from the user key database.
MFS0006E DSTORAGE macro failed to obtain ESQA area.
MFS0006I Resource Manager routine established.
MFS0007E IEANTCR service failed to create Name/Token pair.
MFS0007I PathWAI Secure server address space now non-swappable.
MFS0008E DSPSERV macro failed to obtain create dataspace.
MFS0008I Operator console communications established.
MFS0009E ALESERV macro failed to add cache dataspace ALET.
MFS0009I PathWAI Secure server address space initialization complete.
MFS0010E IEANTRT service failed during termination.
MFS0010I Abend occurred after server POSTed - check dump dataset.

MFS0011E ALESERV DELETE failed during termination.

MFS0011I XXXXXXXXXXXXXXX command issued by operator.
MFS0011I XXXXXXXXXXXXXXX command processing complete.
MFS0011I XXXXXXXXXXXXXXX command is not recognized.
MFS0012E DSPSERV DELETE failed during termination.
MFS0012I Server address termination started.
MFS0013E Server already active for user key database.
MFS0013I Resource Manager routine removed successfully.
MFS0014E ALESERV EXTRACT failed trying to find server STOKEN.
MFS0014I Entry Table destroyed and disconnected from Linkage Table.
MFS0015E Server address space abended.
MFS0015I Cache dataspace ALET deleted from server PASN-AL.
MFS0016E MVS operating system level is pre-SP4.2.2.
MFS0016I Cache dataspace deleted successfully.
MFS0017E VSAM error during GENCB of the user key database ACB.
MFS0017I PathWAI Secure server address space terminated by MVS
STOP command.
MFS0018E VSAM error during GENCB of the user key database RPL.
MFS0018I Code Page dataspace structures initialized.
MFS0019E VSAM error during OPEN of user key database.
MFS0019I Code Page dataspace ALET deleted from server PASN-AL.
MFS0020E VSAM error during GET of record from the user key database.
MFS0020I Cache dataspace allocated successfully.
MFS0021E VSAM error during CLOSE of the user key database.
MFS0021I Code Page dataspace allocated successfully.
MFS0022E Failure detected in SRVPCRTN processing.
MFS0022I CSQAMLST not found - default conversion will be used.
MFS0023E RESMGR ADD failed to establish a resource manager.

MFS0023I Code Page dataspace deleted successfully.

MFS0024E No function code parameter supplied to KMFSRVR.
MFS0024I Conversion between pages nnnnn and nnnnn not supported.
MFS0025E No administrator-id parameter supplied to KMFSRVR.
MFS0024I Conversion between pages nnnnn and nnnnn added.
MFS0026E No reason code area parameter supplied to KMFSRVR.
MFS0027E Name/Token area ESQA length insufficient.
MFS0028E ESQA area too short to accommodate resource manager.
MFS0029E Bad eye catcher detected at ESQA area address.
MFS0030E OPEN of server address space log file failed.
MFS0031E STORAGE macro failed to obtain storage for log DCB.
MFS0032E QEDIT failed while setting CIB limit.
MFS0033E QEDIT failed deleting CIB.
MFS0034E MVS LOAD failure - see reason code.
MFS0035E Unable to obtain storage for trace area.
MFS0036E Unable to dump trace to MQSSSNAP - Trace left in virtual.
MFS0037E MVS DELETE failure - see reason code.
MFS0038E Code Page LOAD POST completion failure.
MFS0038I Code Page dataspace extended successfully.
MFS0039E Code Page POST abend ECB failure.
MFS9999E Unknown return code detected.
PathWAI Secure return codes
0 SUCCESS
Operation was successful.
512–550 See “Crypto_C return codes” on page 236.

1025 NO_MEMORY
No memory available.
1026 VRFY_INVALID_SENDER
Sending user ID is invalid or unknown.
1027 VRFY_MSG_MODIFIED
Message has been modified.
1028 USERID_NO_MATCH
Retyped user ID different.
1029 INVALID_PASSWORD
Password is invalid and/or incorrect.
1030 OUT_BUF_SHORT
Output buffer is too short.
1031 INVALID_TRAILER
Trailer is invalid.
1032 INVALID_TR_VERSION
Invalid trailer version.
1033 TRAILER_APPL
Application trailer detected.
1034 TRAILER_NODE
Node trailer detected.
1035 NO_RANGES
No encryption ranges found.
1036 INVALID_RANGE_PTR
Encryption range array is invalid.
1037 INVALID_RANGE
Encryption range found outside message.
1038 INVALID_REQUEST
Invalid PathWAI Secure indirect API request.
1039 INVALID_CHARSET
Invalid character set.
1040 USERID_BLANK
user ID is blank.

1041 PASSWORD_BLANK
Password is blank.
1042 PASSWORD_NO_MATCH
Retyped password is different.
1043 OVERLONG_INPUT
Input buffer too long.
1044 CANCELLED
Request cancelled by user.
1045 INVALID_UPDATE_REQ
Update request not Valid.
1046 TOO_MANY_CLIENTS
Too many clients open at the same time.
1047 INVALID_CLIENT
Invalid client handle detected.
1048 INVALID_UINFO
Buffer invalid for import users.
1049 USERID_IS_REVOKED
user ID has been revoked.
1050 NO_USERS_EXPORTED
No users available for export.
1051 NO_EXPORT_ADMIN_KEY
Export of the administrator key is invalid.
1052 NO_EXPORT_FOREIGN_KEY
Export of foreign user keys is invalid.
1053 PRIVATE_KEY_OUT_OF_SYNCH
Private keys are out of synchronization.
1054 CONV_TABLES_NOTFOUND
Unable to find code page conversion tables.
1055 NO_SCYEXIT
SCYEXIT not defined.
1056 CONV_TABLES_INTERNAL_ERROR
Internal error doing code page conversion.

1057 CONV_TABLES_OPEN_FAILED
Unable to open a conversion table file.
1058 CONV_TABLES_READ_FAILED
Incorrect length read for a conversion table file.
1059 CONV_TABLES_MQSSDIR_NOTFOUND
Conversion table processing unable to find MQSSDIR.
1060 CONV_TABLES_NO_LOCAL_CCSID
Local CCSID not set.
1061 SECURITY_SEQUENCE_MISMATCH
Security exit processing sequence error.
1062 RANDOM_NUMBER_MISMATCH
Mismatch in security exit random numbers.
1063 GENERATE_RANDOM_NUMBER_BAD
Random number generation failure.
1064 BAD_SECURITY_PHASE_NUMBER
Security Message sequence number not 1–4.
1065 SECURITY_EXCHANGE_INCOMPLETE
All phases of security exchange not completed.
1066 ADMIN_ID_ALREADY_DEFINED
Administrator ID has already been defined—invalid request.
1067 OUTOFSYNC_EXITDATA
Exitdata parameters are out of sync.
1068 NULL_NUMTRAILERS
The number of trailers is not specified for PathWAI Secure
Get.
1069 INVALID_NUMTRAILERS
The number of trailers is specified incorrectly for PathWAI
Secure Get.
1070 NULL_SALT_ADDRESS
The salt pointer is null
1071 KMFPUTENV_INVALID_INPUT
Input to internal function KMFPutEnv is invalid.
1072 PUPRKEY_TOKEN_FAILED
CCA_PuPrKeyToken function failed.

1073 PUBLIC_KKEY_TOKEN_FAILED
CCA_PublicKeyToken function failed.
1074 PKA_ENCRYPT_FAILED
CCA_PKAEncrypt failed.
1075 PKA_DECRYPT_FAILED
CCA_PKADecrypt failed.
1076 CSNBOWH_FAILED
CSNBOWH one-way hash failed.
1077 CSNDDSV_FAILED
CSNDDSV digital signature verify failed.
1078 CSNDDSG_FAILED
CSNDDSG digital signture generate failed.
1079 CSNDPKI_FAILED
CSNDPKI PKA key import failed.
1080 CSNBRNG_FAILED
CSNBRNG generate random number failed.
1081 CSNDPKB_FAILED
CSNDPKB build key token failed.
1082 INVALID_INPUT_PARAMETER
Invalid input parameters.
1084 LDAP_WRITE_USER_FAILED
Write of public key to LDAP repository failed.
1085 LDAP_DELETE_USER_FAILED
Delete of public key from LDAP repository failed.
1086 USER_ID_ALREADY_DEFINED
User ID already defined to LDAP from another platform.
1087 LDAP_OPEN_FAILURE
Inactive LDAP server address and/or port specified.
1088 LDAP_UNKNOWN_ATTRIBUTE
Requested attribute not defined to LDAP.
1089 LDAP_VERIFY_FAILED
Unable to authenticate LDAP entry.

1090 CSNBCKM_FAILED
CCA function CSNBCKM failed.
1091 CSNBDEC_FAILED
CCA function CSNBDEC (decipher) failed.
1092 TDES_KEY_INVALID
Invalid TDES key.
1093 TDES_BUFFER_INVALID
Invalid TDES buffer.
1094 CSNBENC_FAILED
CCA function CSNBENC failed.
1095 CCPOPEN_BAD_CRYPTOCP
Invalid call to CCPOPEN, bad cryptoCP.
1096 CCPOPEN_ERROR_REASON
Error in CCPOpen, reason code stored.
1097 CCPOPEN_HARDWARE_NOT_SET
Hardware support not requested.
1098 DECRYPT_RESTRICTED
Decryption failed, algorithm restricted.
1099 LDAP_CONNECTION_NOT_REQUIRED
Product not configured to connect to LDAP repository.
1100 THREAD_STORAGE_NOT_ACQUIRED
Thread specific storage could not be acquired.
1101 THREAD_STORAGE_NOT_AVAILABLE
Existing thread storage could not be found.
1102/ LDAP_CONNECTION_NOT_DEFINED
LDAP environmental variable(s) not defined.
1103 CH_AUTH_REMOTE_SUFFIX_MISSING
Signed message received from ID missing channel
authentication ID suffix.
1104 CH_AUTH_REMOTE_ID_INVALID_CHL_NAME
Signed message received from ID without channel name.
1105 CH_AUTH_REMOTE_SUFFIX_INVALID
Signed message received from ID without standard suffix

1106 CH_AUTH_SUFFIX_MISMATCH
Signed message received from remote ID with suffix matching
local ID.
1107/ SEC_EXIT_UNKNOWN_EXITREASON
Unknown value encountered for ExitReason.
1108 GET_MQSDATA_PTR_FAILED
GetMQSDataPtr call failed.
1109 HARDWARE_NOT_SUPPORTED
Cryptographic hardware not supported on this platform.
1110 FILENAME_TOO_LONG
File name too long.
1111 TDES_PAD_ERROR
Triple-DES software pad byte count error
1112 SIGNING_ALGORITHM_UNKNOWN
Environment variable MQSECURE_SIGNING_ALGORITHM
setting not recognized.
1113 CLUSTER_AUTH_CHANNEL_NAME_MISMATCH
Clustering authentication user ID channel name invalid.
1114 CLUSTER_AUTH_INPUT_PARM_MISSING
Clustering authentication input parameter missing
1115 CLUSTER_AUTH_FIRST_QUALIFIER_MISSING
Clustering authentication user ID first qualifier missing
1116 CLUSTER_AUTH_FIRST_QUALIFIER_INVALID
Clustering authentication user ID first qualifier invalid
1117 CLUSTER_AUTH_CHANNEL_NAME_MISSING
Clustering authentication user ID channel name missing
1118 CLUSTER_AUTH_THIRD_QUALIFIER_MISSING
Clustering authentication user ID third qualifier missing
1119 CLUSTER_AUTH_THIRD_QUALIFIER_INVALID
Clustering authentication user ID third qualifier invalid
1120 THREAD_STORAGE_NOT_ALLOCATED
Thread-level storage has not been allocated
1121 SYMMETRIC_ALGORITHM_UNSUPPORTED
Symmetric encryption algorithm not supported.

1122 USERID_DELETE_FAILED
Deletion of user ID from database failed.
1123 JNI_GETBYTEARRAY_BAD
JNI GetByteArrayElements() returned NULL.
1124 JNI_GETSTRINGUTF_BAD
JNI GetStringUTFChars() returned NULL.
1125 JNI_NEWBYTEARRAY_BAD
JNI NewByteArray() returned NULL.
1126 JNI_NEWSTRINGUTF_BAD
NI NewStringUTF() returned NULL.
1127 CHANNEL_SECURITY_SETTING_MISMATCH
Channel definition PUTAUT(CTX) or PUTAUT(ALTMCA)
required.
1128 CHANNEL_SECURITY_SETTING_INVALID
MQSECURE_CHANNEL_SECURITY variable setting not
recognized.
1129 MCA_USER_IDENTIFIER_TOO_SHORT
PathWAI Secure User ID too long for MCA User Identifier>
1130 MQMD_USER_IDENTIFIER_TOO_SHORT
PathWAI Secure User ID too long for Message Descriptor User
Identifier.
1131 INVALID_CONTEXT
Unable to establish certificate context.
1132 AVA_NOT_FOUND
Certificate field matching the attribute–value assertion
specified for PathWAI Secure user ID not found.
1133 MQSECURE_ID_MAPPING_ATTRIBUTE_UNKNOWN
Environment.variable setting not recognized.
1134 OVERLAPPING_RANGES
Overlapping encryption ranges specified.
1135 RANGES_NOT_ASCENDING
Encryption ranges not specified in ascending order by offset.
1136 NO_BASE_CERTIFICATE
Neither PathWAI Secure ID nor Subject Name supplied.

1137 CONFLICTING_CHAIN_PARMS
Both PathWAI Secure ID and Subject Name supplied.
1138 MAPPING_RECORD_NOT_FOUND
Certificate mapping database record not found.
1139 MAPPING_INDEX_RECORD_NOT_FOUND
Certificate mapping database index record not found.
1140 CERTIFICATE_NOT_FOUND
Certificate not found in certificate database.
1141 USER_CERTIFICATE_REQUIRED
User specified that certificate is always required for message
embedding, but the certificate was unavailable.
1142 INVALID_CERT_TABLE
Invalid certificate table
1143 EMBED_CERTS_NOT_VERIFIED
Could not verify embedded certificate(s).
1144 PKCS12FILE_OPEN_PROBLEM
Problem encountered opening PKCS#12 file for input.
1145 ADMIN_NOT_CERTIFIED
Administrator must have certificate to export to PKCS#7 file.
1146 NO_DELETE_PKI_USER
CRLs must be updated/imported to revoke users imported
from third-party certificate authority.
1147 TRUST_POINT_NOT_FOUND
Certificate verification chain could not be built to requested
trust point.
1148 OCSP_NO_STATU
Internal OCSP error
1149 OCSP_CERT_REVOKED
OCSP Responder reports certificate is revoked.
1150 OCSP_CERT_NOT_REVOKED
OCSP Responder reports certificate is not revoked.
1151 OCSP_CERT_REVOCATION_UNKNOWN
OCSP Responder reports certificate status unknown.

1152 OCSP_ENVIRONMENT_ERROR 115OCSP

Error returned by KMFGetEnv().
1153 OCSP_CACHE_HI
OCSP Cache Error: Certificate found in cache.
1154 OCSP_CACHE_MISS
OCSP Cache Error: Certificate not found in cache.
1155 OCSP_CACHE_ERROR
OCSP Cache Error. Certificate lookup error
1156 MESSAGE_BUFFER_POINTER_NULL
Pointer to message buffer is null.
1157 NO_CLUSTERS
Cluster-type trailer missing cluster control structures
1158 SECURITY_TRAILER_BUFFER_POINTER_NULL
Pointer to security trailer buffer is null.
1159 CLUSTER_BUFFER_POINTER_NULL
Pointer to cluster buffer is null.
1160 BLOBS_BUFFER_POINTER_NULL
Pointer to blobs buffer is null
1161 RANGE_BUFFER_POINTER_NULL
Pointer to range buffer is null.
1162 CERT_TABLE_BUFFER_POINTER_NULL
Pointer to certificate table buffer is null.
1163 CERT_BUFFER_POINTER_NULL
Pointer to certificate buffer is null.
1164 1164 OCSP_HTTP_ASCEBERR
OCSP ASCII/EBCDIC conversion error in CertC.
1537 USER_NOT_FOUND
User ID not found.
1538 INVALID_KEYSIZE
User key size is invalid.
1539 INVALID_RECSIZE
User key database record size is invalid.

1540 BUFFER_TOO_LONG
User key buffer too long.
1541 DUPLICATE_KEY
Duplicate keys detected.
1542 TOO_MANY_RECORDS
Too many user key database records.
1543 END_OF_FILE
End of user key database detected.
1544 DBSRV_DOWN
User key database server is down.
1545 UPDATE_NOT_CACHED
User key database cache not updated.
1546 IMPORT_ADMIN_NOT_FOUND
Import administrator not in the user key database.
1547 DB_ALREADY_CONVERTED
Input database already converted
1548 DB_EMPTY
Input database is empty
2000 MQSeries error code
KMFREAD return codes
0 Routine successful.
8 Unknown execution environment.
12 Queue manager name missing.
14 PathWAI Secure load library name missing.
16 PathWAI Secure load library error.
18 PathWAI Secure user key database cluster name missing.
20 PathWAI Secure user key database cluster name error.
22 User key suffix too long or not valid.
60 TSO allocate failure encountered for the user key database
cluster.

62 TSO free failure encountered for user key database clsuter.

70 TSO allocate failure encountered for user key database suffix
dummy DD Name.
72 TSO free failure encountered for user key database suffix
dummy DD Name.
80 TSO allocate failure encountered for message log.
82 TSO free failure encountered for message log.
84 TSO delete failure encountered for message log.
86 TSO Execio Diskr failure encountered for message log.
Other As defined by MQSeries or PathWAI Secure.

BSAFE Return Codes
BSAFE Return Codes
Crypto_C return codes
Symbolic Description
512 BE_ALGORITHM_ALREADY SET The value of the algorithm object has
already been set by a call to
B_SetAlgorithmInfo, or by an algorithm
parameter generation.
513 BE_ALGORITHM_INFO Invalid format for the algorithm
information in the algorithm object
514 BE_ALGORITHM_NOT_INITIALIZED The algorithm object has not been
initialized by a call to the Init procedure.
515 BE_ALGORITHM_NOT_SET The algorithm object has not been set by
a call to B_SetAlgorithmInfo.
516 BE_ALGORITHM_OBJ Invalid algorithm object
517 BE_ALG_OPERATION_UNKNOWN Unknown operation for an algorithm or
algorithm info type
518 BE_ALLOC Insuffucient memory
519 BE_CANCEL The operation was cancelled by the
surrender function.
520 BE_DATA Generic data error
521 BE_EXPONENT_EVEN Invalid even value for the public exponent
in key-pair generation.
522 BE_EXPONENT_LEN Invalid exponent length for public
exponent in key-pair generation
523 BE_HARDWARE Cryptographic hardware error.
524 BE_INPUT_DATA Invalid encoding format for input data
525 BE_INPUT_LEN Invalid total length for input data
526 BE_KEY_ALREADY_SET The value of the key object has already
been set by a call to B_SetKeyInfo, or by
a key generation.

BSAFE Return Codes
527 BE_KEY_INFO Invalid format for the key information in
the key object.
528 BE_KEY_LEN Invalid key length.
529 BE_KEY_NOT_SET The key object has not been set by a call
to B_SetKeyInfo, or by a key generation.
530 BE_KEY_OBJ Invalid key object
531 BE_KEY_OPERATION_UNKNOWN Unknown operation for a key info type
532 BE_MEMORY_OBJECT Invalid internal memory object
533 BE_MODULUS_LEN Unsupported modulus length for a key or
for algorithm parameters
534 BE_NOT_INITIALIZED Algorithm is improperly initialized.
535 BE_NOT_SUPPORTED The algorithm chooser does not support
the type of key information in the key
object for the specified algorithm.
536 BE_OUTPUT_LEN The maximum size or the output buffer is
too small to receive the output.
537 BE_OVER_32K The data block exceeds 32,767 bytes.
538 BE_RANDOM_NOT_INITIALIZED The random algorithm has not been
initialized by a call to B_RandomInit.
539 BE_RANDOM_OBJ Invalid algorithm object for the random
algorithm.
540 BE_SIGNATURE The signature does not verify.
541 BE_WRONG_ALGORITHM_INFO The required algorithm information is not
in the algorithm object.
542 BE_WRONG_KEY_INFO The required key information is not in the
key object.
543 BE_INPUT_COUNT Update called an invalid number of times
for input of data.
544 BE_OUTPUT_COUNT Update called an invalid number of times
for output of data.

BSAFE Return Codes
545 BE_METHOD_NOT_IN_CHOOSER The algorithm chooser doesn’t contain
the algorithm method for the algorithm
specified by the previous call to
B_SetAlgorithmInfo.
546 BE_KEY_WEAK The key data supplied would generate a
known weak key.
547 BE_EXPONENT_ONE. The value of the public exponent cannot
be 1
548 BE_BAD_POINTER Invalid pointer.
549 BE_BAD_PASSPHRASE Invalid password.
550 BE_AM_DOMESTIC_ONLY An attempt was made to call a function
that is not available in the export version
of Crypto-C.
551 BE_BAD_SEEDING Bad seeding was passed to an
AI_X931Random object.
Cert-C return codes
1792 E_ALLOC Out of memory General

1793 E_BER_ENCODING Certificate extension error: the
extension is poorly encoded, or
the same extension type appears
more than once in an extensions
object
1794 E_CANCEL Operation was cancelled by the
surrender function
1795 E_DATA Generic data error
1796 E_INDEX Index out of bounds

BSAFE Return Codes
1797 E_INPUT_DATA Invalid encoding format for input

data
1798 E_INPUT_LEN Invalid total length for input data
1799 E_INVALID_PARAMETER Invalid function parameter
1800 E_NOT_FOUND No matching entry found
1801 E_NOT_SUPPORTED Operation not supported
1802 E_OUTPUT_LEN Output buffer is too small
1803 E_OVER_32K Data block exceeds 32767 bytes
1804 E_VALIDITY Validity period start later than

end
1805 E_ATTRIBUTE_TAG Attribute tag is invalid
1806 E_ATTRIBUTE_TYPE Attribute type is invalid
1807 E_ATTRIBUTE_TYPE_LEN Attribute type length is invalid
1808 E_ATTRIBUTE_TYPE_NOT_FOUND Attribute not found
1809 E_ATTRIBUTE_VALUE Attribute value is invalid
1810 E_ATTRIBUTE_VALUE_LEN Attribute value length is invalid
1811 E_ATTRIBUTE_VALUE_INDEX Index out of bounds
1812 E_ATTRIBUTES_ENCODING Invalid encoding format for

attributes
1813 E_ATTRIBUTES_OBJ Invalid attributes object
1814 E_NAME_OBJt Invalid name objec
1815 E_NAME_ENCODING Invalid encoded format for name
1816 E_COMPUTE_ASN_SIGNATURE Error computing digital signature
1817 E_COMPUTE_DIGEST Error computing digest
1818 E_DER_UNKNOWN Encoded data missing

BSAFE Return Codes
1819 E_KEY_TYPE_NOT_SUPPORTED Key info type not supported
1820 E_INNER_DER_UNKNOWN Invalid encoded format for

certificate request
1821 E_ISSUER_NAME Invalid encoded format for issuer

name
1822 E_PRIVATE_KEY Private key is null or does not

match public key
1823 E_PUBLIC_KEY Public key is null
1824 E_SIGN_MACRO_OBJECT [UNUSED]
1825 E_SIGN_VALUE_UNKNOWN Encoded data to be signed is

missing
1826 E_SIGNATURE_ALG_NOT_SUPPORTED Signature algorithm not

supported
1827 E_SIGNATURE_ALG_UNKNOWN Signature algorithm identifier is

missing
1828 E_SUBJECT_NAME Invalid encoded format for

subject name
1829 E_VERIFY_ASN_SIGNATURE Error verifying digital signature
1830 E_CERT_FIELDS CertFields parameter is null
1831 E_CERT_OBJ Certificate object is invalid
1832 E_CERT_SERIAL [UNUSED]
1833 E_CERT_VERSION Certificate version is incorrect
1834 E_CERT_EXTENSIONS Invalid encoded format for

extensions
1835 E_CERT_REQUEST_FIELDS Certificate request fields

parameter is null

BSAFE Return Codes
1835 E_PKCS10_FIELDS Fields are invalid
1836 E_CERT_REQUEST_OBJ Certificate request object is

invalid
1836 E_PKCS10_OBJ Object is invalid
1837 E_CERT_REQUEST_VERSION Certificate request version is

incorrect
1837 E_PKCS10_VERSION Version is incorrect
1838 E_INVALID_SIGNATURE Error verifying digital signature
1839 E_CERT_REQUEST_ENCODING Invalid encoded format for

certificate request
1839 E_PKCS10_ENCODING Encoding is incorrect
1840 E_CRL_ENTRIES_OBJ CRL entries object is invalid
1841 E_CRL_ENTRY_EXTENSIONS Invalid encoded format for

extensions
1842 E_CRL_EXTENSIONS Invalid encoded format for

extensions
1843 E_CRL_FIELDS CrlFields parameter is null
1844 E_CRL_OBJ CRL object is invalid
1845 E_CRL_VERSION CRL version is incorrect
1846 E_LIST_OBJ List object is invalid
1847 E_EXTENSION_ALREADY_EXISTS Extensions object already

contains given extension
1848 E_EXTENSION_TYPE_NOT_ALLOWED Extension type not allowed this

type of object
1849 E_EXTENSIONS_OBJ Invalid extensions object
1850 E_INVALID_CRITICALITY Encoded as non-critical but

registered as critical

BSAFE Return Codes
1851 E_MULTIPLE_VALUES_NOT_ALLOWED Extension is single-valued
1852 E_UNKNOWN_CRITICAL_EXTENSION No handler for critical extension
1853 E_VALUE_INDEX Extension value index out of

bounds
1854 E_APPL_CTX Invalid application context
1855 E_DEFAULT_STANDARD_EXTENSION Tried to unregister a default

standard extension
1856 E_EXTENSIONS_OBJ_TYPE Invalid extensions object type
1857 E_INVALID_HANDLER Handler is missing required

function pointers
1858 E_OVERRIDE_HANDLER_NOT_ALLOWED Handler may not be overridden
1859 E_OVERRIDE_CRITICAL_NOT_ALLOWED Registered criticality may not be

changed
1860 E_NO_SERVICE Service provider not found
1861 E_DUPLICATE_SERVICE Duplicate service provider not

allowed
1862 E_IO Generic i/o service provider error
1863 E_EOS End of i/o stream Service

Provider
1864 E_LOG Generic log service provider error
1865 E_SURRENDER Generic surrender service

provider error
1866 E_DB Generic database service

provider error
1867 E_CRYPTO Generic crypto service provider

error

BSAFE Return Codes
1872 E_PATH_NOT_FOUND Valid cert path not found
1873 E_NOT_VALIDATED Validation process failed
1874 E_PATH_ALG_NOT_SUPPORTED Path algorithm not supported
1875 E_PATH_PROVIDER Path provider specific warning
1888 E_DIGEST_ALG_NOT_SUPPORTED Message digest algorithms not

supported
1889 E_DIGEST_NOT_MATCHED Digest does not match
1890 E_ENCRYPT_ALG_NOT_SUPPORTED Message encryption algorithms

not supported
1891 E_CMSF_OPTION CMS option not supported
1892 E_MESSAGE_TYPE_NOT_VALID Message type not valid
1893 E_VERSION_NOT_SUPPORTED Version of message not

supported
1894 E_KEY_ENCRYPTION_ALG_NOT_SUPPOR Recipient key encryption

TED algorithms not supported
1904 E_LDAP_ERROR Generic LDAP error. LDAP

return codes provide more
information
1905 E_LDAP_NO_SUCH_OBJECT LDAP operation failed, returned

LDAP_NO_SUCH_OBJECT
1906 E_LDAP_UNBIND LDAP unbind failed
1907 E_LDAP_ATTRLIST Problem building base DN or

search filter for LDAP search
1908 E_LDAP_ATTR_NOTFOUND DN or search filter component

not found in subject name
1920 E_PKI_MSG_INVALID Message BER/DER is malformed
1921 E_PKI_MSG_OBJ PKI message object is invalid

BSAFE Return Codes
1922 E_PKI_MSG_TYPE PKI message object is not the

correct type
1923 E_PKI_SIGNER_COUNT Number of expected verified

signers incorrect
1924 E_PKI_MISSING_POP Required Proof-of-Possession

missing
1925 E_PKI_NONCE_MISMATCH Sender and recipient nonce

mismatch
1926 E_PKI_INVALID_CONFIGURATION Configuration information

specified incorrectly
1927 E_PKI_TRANSACTION_ID_MISMATCH Sender and recipient transaction

ID mismatch
1928 E_PKI_UNEXPECTED_DATA Data unanticipated by provider
1929 E_PKI_INCORRECT_MSGTYPE Incorrect message type
1930 E_PKI_TRANSPORT Data transport i/o error
1936 E_URL_ENCODING Data incorrectly URL-encoded
1937 E_TIMEOUT Timeout occurred during

operation
1938 E_OS_PLATFORM Platform-specific error (library

binding, etc.)
1939 E_BUSY Requested service busy
1940 E_NOT_AUTHORIZED Not authorized or identified to

use service
1941 E_SERVER_FAILURE Server internal error handling

request
1952 E_INSERT Cannot insert cert/CRL/key
1953 E_RETRIEVE Cannot retrieve cert/CRL/key

BSAFE Return Codes
1954 E_DELETE Cannot delete cert/CRL/key
1955 E_PROVIDER CSP-related error (can’t acquire

context, etc.)
1956 E_KEY Invalid key, key specs, etc.
1957 E_CANT_ASSOCIATE_CERT_WITH_KEY Cannot associate cert with

private key
1958 E_HMAC_FAILED HMAC validation failed
1959 E_PROV_DLL_NOT_FOUND Provider DLL not found
1984 E_PKCS11DB_LIBRARY_ERROR PKCS #11 library error
1985 E_PKCS11DB_CRYPTOKIFUNCTIONS Cryptoki function list not

obtained or provided
1986 E_PKCS11DB_INIT_LIBRARY PKCS #11 library could not be

initialized
1987 E_PKCS11DB_LIBRARY_VERSIONl PKCS #11 library is back-leve
1988 E_PKCS11DB_OPEN_SESSION Could not open session to the

token
1989 E_PKCS11DB_NO_TOKENS_PRESENT No tokens found in any slot
1990 E_PKCS11DB_TOKEN_NOT_FOUND Unable to find token with given

label
1991 E_PKCS11DB_BAD_PIN PIN is incorrect, expired, or

locked
1992 E_PKCS11DB_LOGIN_FAILED Unable to login PKCS #11

session
1993 E_PKCS11DB_LIBRARY_NOT_FOUND PKCS #11 library not found
2016 E_OID_MISMATCH OIDs do not match

BSAFE Return Codes

Guide to Candle
E Customer Support
Introduction
Candle Corporation is committed to producing top-quality software products
and services. To assist you with making effective use of our products in your
business environment, Candle is also committed to providing easy-to-use,
responsive customer support.
Precision, speed, availability, predictability—these terms describe our
products and Customer Support services.
Included in this Guide to Candle Customer Support is information about the
following:
Base Maintenance Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
– Telephone Support
– eSupport
– Description of Severity Levels
– Service-level objectives
– Recording and monitoring calls for quality purposes
– Customer Support Escalations
– Above and Beyond
Enhanced Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
– Assigned Support Center Representative (ASCR)
– Maintenance Assessment Services (MAS)
– Multi-Services Manager (MSM)
Customer Support Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . 254
– Link to Worldwide Support Telephone and E-mail information
Guide to Candle Customer Support 247

Base Maintenance Plan
Overview
Candle offers a comprehensive Base Maintenance Plan to ensure that you
realize the greatest value possible from your Candle software investments. We
have more than 200 technicians providing support worldwide, committed to
being responsive and to providing expedient resolutions to support requests.
Technicians are available worldwide at all times during the local business day.
In the event of an after-hours or weekend emergency, our computerized call
management and forwarding system will ensure that a technician responds to
Severity One situations within one hour. For customers outside of North
America, after-hours and weekend support is provided in English language
only by Candle Customer Support technicians located in the United States.
Telephone support
Candle provides consistently reliable levels of service—thanks to our
worldwide support network of dedicated experts trained for specific products
and operating systems. You will always work with a professional who truly
understands your problem.
We use an online interactive problem management system to log and track all
customer-reported support requests. We give your support request immediate
attention by routing the issue to the appropriate technical resource, regardless
of geographic location.
Level 0 Support is where your call to Candle Customer Support is first
handled. Your support request is recorded in our problem management
system, then transferred to the appropriate Level 1 support team. We
provide Level 0 manual interaction with our customers because we
support more than 170 products. We feel our customers would prefer
personal interaction to a complex VRU or IVR selection menu.
Level 1 Support is the service provided for initial support requests. Our
Level 1 team offers problem determination assistance, problem analysis,
problem resolutions, installation assistance, and preventative and
corrective service information. They also provide product usage
assistance.

Level 2 Support is engaged if Level 1 cannot provide a resolution to

your problem. Our Level 2 technicians are equipped to analyze and
reproduce errors or to determine that an error is not reproducible.
Problems that cannot be resolved by Level 2 are escalated to Candle’s
Level 3 R&D support team.
Level 3 Support is engaged if a problem is identified in Candle product
code. At Level 3, efforts are made to provide error correction,
circumvention or notification that a correction or circumvention is not
available. Level 3 support provides available maintenance modifications
and maintenance delivery to correct appropriate documentation or
product code errors.
eSupport
In order to facilitate the support process, Candle also provides eSupport, an
electronic full-service information and customer support facility, via the World
Wide Web at www.candle.com/support/. eSupport allows you to open a new
service request and update existing service requests, as well as update
information in your customer profile. New and updated service requests are
queued to a support technician for immediate action. And we can respond to
your request electronically or by telephone—it is your choice.
eSupport also contains a continually expanding knowledge base that
customers can tap into at any time for self-service access to product and
maintenance information.
The Candle Web Site and eSupport can be accessed 24 hours a day, 7 days
a week by using your authorized Candle user ID and password.
Description of Candle severity levels

Responses to customer-reported product issues and usage questions are
prioritized within Candle according to Severity Code assignment. Customers
set their own Severity Levels when contacting a support center. This ensures
that we respond according to your individual business requirements.
Severity 1 A crisis affects your ability to conduct business, and no procedural
Crisis workaround exists. The system or application may be down.
Severity 2 A high-impact problem indicates significant business effect to you.
High The program is usable but severely limited.

Severity 3 A moderate-impact problem involves partial, non-critical

Moderate functionality loss or a reasonable workaround to the problem. A
“fix” may be provided in a future release.
Severity 4 A low-impact problem is a “how-to” or an advisory question.
Low
Severity 5 This is a request for software or documentation enhancement. Our
Enhancement business units review all requests for possible incorporation into a
Request future release of the product.
Candle has established the following service-level objectives:
Severity 1 Severity 2 Severity 3 Severity 4 Severity 5

Call Status Goal Goal Goal Goal Goal
First Call Time to 90% within one minute
Answer
Level 1 Response 90% within 90% within one hour
(Normal Business Hours) 5 minutes
Level 2 Response Warm 90% within 90% within eight hours
(Normal Business Hours) Transfer two hours
Scheduled Hourly or Daily or as Weekly or as agreed Notification is
follow-up as agreed agreed made when an
(status update) enhancement is
incorporated
into a generally
available
product.
Notification is made when a fix is incorporated into a generally
available product.
The above information is for guideline purposes only. Candle does not guarantee or warrant the above service levels. This
information is valid as of October 1999 and is subject to change without prior notice.

Recording and Monitoring Calls for Quality Purposes

Candle is committed to customer satisfaction. To ensure that our customers
receive high levels of service, quality and professionalism, we’ll monitor and
possibly record incoming and outgoing Customer Support calls. The
information gleaned from these calls will help us serve you better. If you prefer
that your telephone call with Candle Customer Support in North America not
be monitored or recorded, please advise the representative when you call us
at (800) 328-1811 or (310) 535-3636.
Customer Support Escalations

Candle Customer Support is committed to achieving high satisfaction ratings
from our customers. However, we realize that you may occasionally have
support issues that need to be escalated to Candle management. In those
instances, we offer the following simple escalation procedure:
If you experience dissatisfaction with Candle Customer Support at any time,
please escalate your concern by calling the Candle support location closest to
you. Ask to speak to a Customer Support manager. During standard business
hours, a Customer Support manager will be available to talk with you or will
return your call. If you elect to hold for a manager, you will be connected with
someone as soon as possible. If you wish a return call, please tell the Candle
representative coordinating your call when you will be available. After
contacting you, the Customer Support manager will develop an action plan to
resolve your issue. All escalations or complaints received about support issues
are logged and tracked to ensure responsiveness and closure.
Above and Beyond

What differentiates Candle’s support services from our competitors? We go
the extra mile by offering the following as part of our Base Maintenance Plan:
n Unlimited multi-language defect, installation and operations support
n eSupport using the World Wide Web
n Regularly scheduled product updates and maintenance provided at no
additional charge
n Over 200 specialized technicians providing expert support for your
Candle products

Enhanced Support Services
Overview
Our Base Maintenance Plan provides a high level of software support in a
packaged offering. However, in addition to this plan, we have additional
fee-based support services to meet unique customer needs.
The following are some examples of our added-value support services:
n Assigned Support Center Representative Services (ASCR)
– An assigned focal point for managing support escalation needs
– Proactive notification of available software fixes
– Proactive notification of product version updates
– Weekly conference calls with your ASCR to review active problem
records
– Monthly performance reviews of Candle Customer Support service
levels
– Optional on-site visits (extra charges may apply)
n Maintenance Assessment Service (MAS)
– On-site assessment services
– Advice about product maintenance and implementation
– Training your staff to develop efficient and focused procedures to
reduce overall cost of ownership of your Candle software products
– Analysis of your Candle product environment: versions, updates,
code correction history, incident history and product configurations
– Reviews to ensure that purchased Candle products and solutions are
used effectively
n Multi-Services Manager (MSM)
Multi-Services Manager provides highly valued services to customers
requiring on-site full time expertise to complement their technical
resources.
– Dedicated on-site Candle resource (6 months or one year) at your site
to help ensure maximum use and effectiveness of your Candle
products

– Liaison for all Candle product support activities, coordination and

assistance with implementation of all product updates and
maintenance releases
– Works with your staff to understand business needs and systems
requirements
– Possesses technical and systems management skills to enhance your
staff’s knowledge and expertise
– Other projects as defined in Statement of Work for MSM services

Customer Support Contact Information
Customer Support Contact Information
Link to Worldwide Support Telephone and E-mail information

To contact Customer Support, the current list of telephone numbers and
e-mail addresses can be found on the Candle Web site,
www.candle.com/support/.
Select Support Contacts from the list on the left of the page.

Glossary
G
A digital envelope A ”package”
composed of a message encrypted by a
authentication The act of verifying symmetric key and the symmetric key
information such as identity, ownership, itself, encrypted using the receiver’s
or authorization. public key.
digital signature The encryption of a
message digest with a private key. Used
C for verifying the identify of the sender
certificate See digital certificate of the message.
channel exit A program that performs Data Encryption Standard (DES) A
additional processing at a defined place block cipher developed by IBM and the
in the processing carried out by the U.S. government in the 1970s as an
message channel agent (MCA). official standard.
Certificate Authority An internal DES see Data Encryption Standard

entity or trusted third party (such as digest Commonly used to refer to the
VeriCert) that issues, signs, revokes, and output of a hash function. For example,
manages digital certificates. See also a message digest refers to the hash of a
digital certificate, trust point, root message.
certificate.
E
D
encryption The transformation of
digital certificate See also root plain text into an apparently less
certificate, trusted certificate readable form through a mathematical
Glossary 255
process. The encrypted text may be read M
by anyone who has the key that decrypts
the ciphertext. MCA See message channel agent
end-to-end security Secures a message channel agent (MCA) A

message from the source application to program that controls the sending and
the target application, regardless of the receiving of messages.
number of physical machines it hops message digest The result of
across in transit. applying a hash function to a message.
H N
hash function A function that takes a node-to-node security Secures a
variable sized input and has a fixed size message as it travels across a single
output. physical channel connection from a
source machine to a target machine.
K
key In traditional cryptography, a key is O
the system or pattern used to encode or OCSP See online certificate status
decode text. In digital cryptography, a protocol
key is a variable value applied using an
algorithm to a string or block of text or online certificate status protocol
other data to encrypt or decrypt it. See (OCSP) A protocol for sending
also private key, public key, secret requests for certificate status to an online
key. server, or responder.
key management The tasks involved

in the creation, distribution,
authentication, and storage of keys. P
key pair The public key and private password-based encryption (PBE)
key issued to a particular user ID. All private keys must be encrypted
PBE See password-based
encryption.
256 PathWAI Secure for WebSphere MQAdministrator’s Guide, Version 300

PKCS See public key cryptography S
standards.
secret key See symmetric key.
private key The secret member of a
key pair. It is used for signing and symmetric key An
decryption. encryption/decryption key shared by
both sender and receiver. Also known as
public key The member of a key pair a secret key.
that is made available to all
communicating users. It is used for
encryption and authentication.
T
public key cryptography
Cryptography based on methods trusted certificate In MQSecure, a
involving a public key and a private key. certificate designated as “trusted” by the
site for the purpose of authenticating
Public key cryptography standards users.
(PKCS) A set of standard protocols for
exchanging information securely on the trust point An assigned level of trust.
Internet using a public key infrastructure The trust point may itself be part of some
(PKI). other verification chain.
certificate path/chain, cross certificates,

R
root certificate A self-signed
certificate. The subject and the issuer are
the same, and the issuer is a trusted
party for whose signature no verification
is needed.
RSA algorithm A public-key
cryptographic system. RSA stands for
Rivest, Shamir, and Adleman, the
developers of the RSA public-key system
and the founders of RSA Security.
Glossary 257
Index
Symbols resetting default 54
&cleds, 202 setting
&hilevdsn 202 OS/390 56
&mqloadds 202 UNIX 55
Windows 54
&mqsauthds 202
asymmetric keys
&tsiud.ispf.ispprof dataset 202
default modulus 54, 95
.dbb 145
description of 26
specifying length (mqs_adm) 196
Numerics attribute–value assertions 60
4758 Cryptographic Coprocessor 45 authentication 24
4958 crytographic accelerator 45 of channel IDs 100
of cluster IDs 100
A PathWAI Secure-generated keys 96
activing channel autodefine exits 156 third-party keys 96
administrative utilities 92–93 autodefine exits 155–156
administrator’s keys autodefine exits (CHADEXIT),
initializing 197, 198 activating 156
administrators autodefined cluster sender channels 155
about 98 AVAs see attribute–value assertions
deleting 128
registering 110–113 B
revoking 128 backing up LDAP repository
administrators’ keys on UNIX 143
exporting to a file 190 Windows NT 138
Adobe portable document format 13 backing up user key database 131
Advanced Encryption Standard (AES) 25 BSAFE return codes 236
AES (RijnDael) algorithm 25 Business Directory Service 137
APIs
and range encryption 33 C
when to use 33, 34
CandleAgent 141
application-to-application security 33
CandleNet eBP MQSecure Connection, see
ASCR
CASP Secure Connector
assigned support center
CASP Secure Connector 162–185
representative 252
usage scenarios 179–185
assigned support center representative
certificate embedding 78
ASCR 252
asymmetric key length configuring on OS/390 83
Index 259
D
configuring on UNIX (GUI mode) 81 configuration options 37–??, 38, ??–90

configuring on UNIX (text mode) 82 configuration tool 39
configuring on Windows 80 configuration utility, about 136
certificate revocation checking configuring an LDAP connection
configuring OS/390 43
OS/390 66 UNIX (GUI) 42
UNIX (text mode) 65 UNIX( text mode) 43
certificate revocation list checking Windows 41
configuring configuring hardware encryption ??–48
UNIX (GUI mode) 64
OS/390 48
Windows 64
UNIX (GUI) 46
disabling 64
certificate revocation lists UNIX (text mode) 47
description 27 Windows 45
certificate revocation lists (CRLs) 96 converting channel exit names 155
certificate subject name 60 converting databases 211
certificates 123, 194 creating new keys 114
description 27 creating new users 114
certificatesembedding in messages 78 creating user key database 132
CHADEXIT, using 155 creating user key pairs 114, 194, 195
chain of verification, See verification chain CRLs, see certificate revocation lists
changing symmetric encryption algorithm cryptographic approach 25
on OS/390 51 CSQXLIB 156
changing user password 196 customer service
channel authentication IDs 100, 148 telephone support 248
channel autodefine exit (CHADEXIT) 155 customer support
base maintenance plan 248
description of 155
channel autodefine exits (CHADEXIT) contact information 254
activating 156 enhanced support services 252
channel definition parameters 148 eSupport 249
channel exit names, conversion of 155 severity levels 249
channel exits
definition parameters 149 D
overview 148 databases
securing messages with 148–157 certificate 95
specifying security type 153 local user key 95
Channel Initiator address space 156 DD Names 205
channel mutual authentication 148 definition parameters
cluster authentication IDs 100, 148 for channel exits 149
cluster channels 148 deleting administrators 128
cluster sender channels, securing 155–156 deleting the LDAP repository
CMOS Cryptographic Coprocessor 45 on Windows NT 139
COMMON_NAME (cn) attribute 60 UNIX 144

E
deleting users 128, 190 T 74

DES encryption 25 MQSECURE_OCSP_RESPONSE_CERT
digital certificates, see certificates 27 74
digital envelopes 28, 29 MQSECURE_OCSP_REVOCATION_CH
digital signature 31 ECKING 74
disabling 4758 Cryptographic Coprocessor MQSECURE_OCSP_TRANSPORT_DEST
on Windows 45 INATIONS 74
Distinguished Name 60 MQSECURE_OCSP_TRANSPORT_PRO
XIES 74
E MQSECURE_RSA_MODULUS_SIZE 56,
58
eBP Directory Administrator 167
MQSECURE_SIGNING_ALGORITHM 5
embedding certificates 78
8, 59
enabling 4758 Cryptographic Coprocessor
MQSECURE_SYM_ENCRYPT 51, 52 ,
on Windows 45
62, 73, 77, 83
encryption 32
environmental variables
encryption algorithms 25
MQSECURE_OCSP_SCOPE 74
choosing 50 eSupport
configuring on OS/390 53 customer support 249
configuring on UNIX (GUI) 51 example of channel exit 154
configuring on UNIX (text mode) 52 exit chaining 150
configuring on Windows 51 exporting administrators’ public key 190
constraints on use 50 exporting certificates
descriptions 49 to PKCS#12 file 123, 194
strength of 50 exporting private keys
encryption key to PKCS#12 file 123, 194
regenerating 196 exporting public key certificates
encryption options 38 to a PKCS#7 file 191
environment variables exporting public keys
MQSECURE_CCID 189 administrators’ 190
MQSECURE_CRL_CHECKING 65, 66 to a file 119, 192
MQSECURE_HARDWARE_ENABLED 4 to a queue manager 120
7, 48 to LDAP repository 118, 193, 194
MQSECURE_ID_MAPPING_ATTRIBUTE to PKCS#12 123, 194
63 to queue manager 193
MQSECURE_LDAP_SERVER_ADDRESS exporting to PKCS#12 file 123, 194
42, 44 exporting trusted certificates
MQSECURE_LDAP_SERVER_PORT 43, to a PKCS#7 file 191
44
MQSECURE_MULTIPRIME_KEYS 77
MQSECURE_OCSP_CACHE_RETENTIO
F
N 74 failures, logging of 150
MQSECURE_OCSP_REQUESTOR_CER following 179
Index 261
G
G integrity, message 31
generating administrator’s keys 197, 198 ISPF PROFILE 202
Global Administrator
about 98 K
registering 104–109 key management 91–133
using PathWAI Secure-generated key option 38
keys 105 key pairs
using third-party keys 106 creating 194, 195
KMFADM
H description 202
hardware encryption invoking 202
configuring KMFADM functions
OS/390 48 Change Password 103
UNIX (GUI) 46 Export Local Public Keys 119
UNIX (text mode) 47 Export user to file 120
Windows 45 Export user to q-mgr 121
devices 45
Import users 126
hardware encryption, configuring ??–48
List Users 101 , 102
hashing algorithm
Re-encrypt user key database 132
configuring on OS/390 59
Refresh All Public Keys 132
hashing algorithms
configuring on UNIX (GUI) 57 Reset user key database 132
configuring on UNIX (text mode) 58 Revoke Users 129 , 130
configuring on Windows 57 Set/Reset LDAP Repository 133
MD5 57 kmfconv 211
SHA-1 57 KMFREAD 121, 205
description 205
invoking 205
I KMFREAD return codes 234
IBM MQSeries 206 kmlxcils 167
ID mapping kmlxcils.h 173
about 60
kmlxcilsg 168
configuring
kmlxcilsp 168
OS/390 62
UNIX (GUI) 61 KXCILSOPT 173
UNIX (text mode) 62 KXCLONG 175
Windows 61 KXCMQSECINFO 173
IDs KXCMQSRANGE 176
channel authentication 100 range structure 177
cluster authentication 100 kxcSetILSDdata 173
importing public keys 124, 195, 196 KXCULONG 173, 174, 177
initializing administrator’s keys 197, 198 KXCUSHORT 177
integrated function calls 34 kxsserv 141
integrity 24

L
L M
LDAP connection, configuring maintenance assessment service
OS/390 43 MAS 252
UNIX (GUI) 42 Manage Candle Services dialog 137
UNIX (text mode) 43 managing keys 91–133
Windows 41 managing the LDAP repository 135–145
LDAP repository MAS
backing up (UNIX) 143 maintenance assessment service 252
backing up (Windows NT) 138 KXCCHAR 175, 176
deleting (UNIX) 144 MD5 hashing algorithm 57
deleting (Windows NT) 139 message digest 31
managing 135–145 message encryption 32
LDAP repository host name message integrity, ensuring 31
resetting on MQSecure node (OS/390) 39 MFSSRVR 39
resetting on MQSecure UNIX node (text modulus size 54, 95
mode) 43 configuring on OS/390 56
LDAP repository password configuring on UNIX 55
resetting on host (UNIX) 141–143 configuring on Windows 54
resetting on host (Windows NT) 137 -l parameter 54
resetting on MQSecure node 133, 198 overriding default 54
LDAP repository port number modulus–exponent format 54
resetting on host (UNIX) 141–143 MQConfig 42, 46, 51, 57, 61, 64, 71, 76,
resetting on host (Windows NT) 137 81, 86
resetting on MQSecure node (OS/390) 39 MQConfig -l 52, 58, 62, 65, 72, 76, 82, 87
resetting on MQSecure UNIX node (text MQConfig -l command 43
mode) 43
mqdirecc 207
LDAP repository user ID
mqdirecc return codes 224–245
resetting on host (UNIX) 141–143
mqdirect 207
resetting on host (Windows NT) 137
mqdirect return codes 224–245
resetting on MQSecure node 133, 198
mqs_adm
LDAP server
-d 129, 130, 190
about 141
-e -f 120
starting (UNIX) 141
-e -r 119
starting (Windows NT) 137
-g 114, 194, 195
stopping (UNIX) 141
-i 126
stopping (Windows NT) 137
-k 132
LDAP user ID 133
-p 103
LE370 Load Lib 205
-s 132
list users command 101 , 102
-s -r 133
listing registered users 101, 199
-u 102
mqs_adm parameters 189
mqs_admc
Index 263
N
-d 129, 130, 190 KING 74

-e -f 120 MQSECURE_OCSP_SCOPE 74
-e -r 105, 107, 110, 112, 115, 119 MQSECURE_OCSP_TRANSPORT_DESTI
-g 114, 194, 195 NATIONS 74
-i 126 MQSECURE_OCSP_TRANSPORT_PROXI
-k 132 ES 74
-p 103 MQSECURE_RSA_MODULUS_SIZE 54,
-s 132 58
-u 102 MQSECURE_SIGNING_ALGORITHM 58
mqs_admc parameters 189 MQSECURE_SYM_ENCRYPT 51, 52, 62,
mqs_op 209 73, 77, 83
mqs_opc 209 MQSREAD 125
mqs_read 204 MQSS.USR 128
MQSCONF 39 MQSSPROF 202
MQSecure Connection MQSXPROF 202
data structure, KXCMQSECINFO 173 MSGDATA 89, 153
defaults 165 MSGEXIT 151
header file kmlxcils.h 173 MSM
interoperation with eBP applications 164 multi-services manager 252
modes of operation 162 multi-services manager
run-time paths 165 MSM 252
secure side files for 172 MVS administrative utility 202
specifying use of ILS 167
using eBP LDAP 166 N
MQSecure passwords 167 NEXTID 145
MQSECURE_CCID environment node-to-node security 33, 148
variable 189 nontrusted certificate database 95
MQSECURE_CRL_CHECKING 65, 66
MQSECURE_HARDWARE_ENABLED 47, O
48 OCSP responder
MQSECURE_LDAP_SERVER_ADDRESS description 27
42, 44 specifying location of 68
MQSECURE_LDAP_SERVER_PORT 43, OCSP-based certificate revocation checking
44 cache retention time 68
MQSECURE_MULTIPRIME_KEYS 77 enabling 68–74
MQSECURE_OCSP_CACHE_RETENTION OS/390 74
74 UNIX (GUI mode) 71
MQSECURE_OCSP_REQUESTOR_CERT UNIX (text mode) 72
74 Windows 70
MQSECURE_OCSP_RESPONSE_CERT 7 how it works 67
4 overview 67
MQSECURE_OCSP_REVOCATION_CHEC requestor signature 69

P
responder signature 69 importing 124 , 195 , 196

scope 69 monitor utility for MVS systems 205
online certificate revocation checking 67– public/private key pairs
74 description 26
configuring
OS/390 74 Q
UNIX (GUI mode) 71
queue authorization
UNIX (text mode) 72
configuring on OS/390 87
Windows 70
configuring on UNIX (GUI mode) 86
overview, PathWAI Secure 24
configuring on UNIX (text mode) 87
configuring on Windows 85
P
partial encryption, See range encryption 33
passwords
R
MQSecure 167 range encryption 33
passwords, valid 102 RC2 algorithm 25
PathWAI Secure ILS 162–185 RC2 symmetric encryption algorithm
changing on OS/390 51
PathWAI Secure overview 24
RC4 algorithm 25
PKXCMQSRANGE 177
RC5 algorithm 25
platform mutual authentication 24, 148
RCVDATA 153
printing problems 14
RCVEXIT 151
privacy 24
reconfiguring MQSecure
privacy, ensuring 32
on OS/390 39
private keys
re-encrypting user key database 132, 196
exporting to PKCS#12 file 123, 194
refreshing user key database 132
problems queue 150
regenerating user key database encryption
public key certificates
key 196
exporting to a PKCS#7 file 191
registered users, listing 101, 199
public key cryptography 26–32
public key distribution registering administrators 110–113
using LDAP repository 41 registering users 114
public key monitor repudiation 24
for distributed systems 204 resetting LDAP repository host name
public key monitor utility on MQSecure node (OS/390) 39
KMFREAD 205 on MQSecure UNIX node (text mode) 43
public keys resetting LDAP repository password
creating 114 on UNIX host 141
exporting administrators’ 190 on Windows NT host 137
exporting to a file 119, 192 resetting LDAP repository port number
exporting to LDAP repository 118, 193, on MQSecure node (OS/390) 39
194 on Windows NT host 137
exporting to PKCS#12 file 123, 194 resetting LDAP repository user ID
exporting to queue manager 120, 193 on MQSecure node 133, 198
Index 265
S
on UNIX host 141 special code pages, using 189

on Windows NT host 137 specifying security type 153
resetting LDAP respository port number starting the LDAP server
on UNIX host 141–143 UNIX 141
resetting user key database 132 Windows NT 137
restrictions 15–16 stopping the LDAP server
on message length 219 UNIX 141
return codes Windows NT 137
BSAFE 236 subject name seecertificate subject name
KMFREAD 234 symmetric encryption algorithm
mqdirect, mqdirecc 224–245 changing on OS/390 51
reusing symmetric keys 88–90 symmetric keys
revocation description of 26
third-party keys 96 reusing 88–90
revoking administrators 128 SYSTEM.MQSECURE.COMMANDS
revoking users 128, 190 queue 121, 204, 205
RijnDael (AES) algorithm 25 SYSTEM.MQSECURE.PROBLEMS 150
RSA BSAFE return codes 236
RSA key length 54 T
RSA Modulus Size field 54 telephone support
RSA RC2 encryption 25 customer service 248
third-party keys
S revoking 96
translating user records 189
SCYEXIT 151
triple DES encryption algorithm 25
secure side files 172
changing on OS/390 51
creating 170
triple prime key generation
location of 172
configuring
security on 172 OS/390 77
securing autodefined cluster sender UNIX (GUI mode) 76
channels 155–156 UNIX (text mode) 76
securing messages Windows 75
through APIs 33 overview 75
through channel exits 33 Triple-DES algorithm 25
SENDDATA 153 trusted certificate database 95
SENDEXIT 151 trusted certificates
service functions 207 exporting to a PKCS#7 file 191
mqs_op 209
mqs_opc 209 U
set length of asymmetric key 196
updating user password 196
severity levels
usage scenarios, CASP Secure
customer support 249
Connector 179–185
SHA-1 hashing algorithm 57 user IDs

V
for eBP applications 166 W

restrictions on 99 WebSphere MQ MQGET 33
valid 99 WebSphere MQ MQPUT 33
user key database
backing up 131
converting 211
creating 132
deleting 128
managing 131–133
re-encrypting 132, 196
refreshing 132
regenerating encryption key 196
resetting 132
user key pairs, creating 114, 194, 195
user password
changing 196
updating 196
user registration 114
user verification 96
users
creating new 114
deleting 128, 190
listing registered 101, 199
registering 114
revoking 128
utilities
configuration 136
KMFADM 202
kmfconv 211
mqs_adm 189
mqs_admc 189
mqs_read 204
MVS public key monitor 205
utilities, administrative 92–93
V
verification
PathWAI Secure-generated keys 96
third party-keys 96
verification chain
Index 267
W

GC32 9342 00

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

GC32 9342 00

Caricato da

Copyright:

Formati disponibili

Administrator’s Guide

PathWAI™ Secure for WebSphere MQ

2 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

Chapter 1. Introducing PathWAI Secure for WebSphere MQ . . . . . . . . . . . 23

Chapter 2. Configuring Key and Encryption Options . . . . . . . . . . . . . . . . . 37

Chapter 3. Managing Users and User Keys. . . . . . . . . . . . . . . . . . . . . . . . . 91

Registering a Global Administrator . . . . . . . . . . . . . . . . . . . . . . . . . 104

Chapter 4. Managing the Candle LDAP Repository . . . . . . . . . . . . . . . . . 135

Chapter 5. Securing WebSphere MQ Messages Using Channel Exits . . . . 147

Appendix A. CASP Secure Connector . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

Appendix B. Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

4 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

Appendix C. Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

Appendix D. Messages and Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 221

Appendix E. Guide to Candle Customer Support . . . . . . . . . . . . . . . . . . . . 247

6 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

FIGURE 1. Symmetric and Asymmetric Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

8 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

Table 1. Cryptographic Algorithms by Strength . . . . . . . . . . . . . . . . . . . . . . . . 50

10 PathWAI™ Secure for WebSphere MQ Administrator’s Guide, Version 300

Who should read this book?

How this book is organized

Where to find more information

12 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

We would like to hear from you

Ordering additional product documentation

Printing this book

14 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

16 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

PathWAI Secure Version 300 introduces

New product names

Third-party key pairs and certificates

CRL and OCSP certificate revocation checking

18 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

Message-embedded digital certificates

Automatic key exchange for mutual authentication

Triple-prime key generation

Offset-based range encryption

Symmetric key reuse

20 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

Key caching for enhanced performance

CASP Secure Connector enhancements

Introducing PathWAI Secure for WebSphere MQ 23

What is PathWAI Secure?

What does PathWAI Secure do?

Why secure messages?

What security services does PathWAI Secure provide?

24 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

n Signing/authentication—Confirms senders’ identity and the integrity of

How are PathWAI Secure services invoked?

What type of encryption does PathWAI Secure use?

What type of key management does PathWAI Secure provide?

Introducing PathWAI Secure for WebSphere MQ 25

What is Public Key Cryptography?

Public/private keys pairs

FIGURE 1. Symmetric and Asymmetric Keys

Symmetric (Secret) Keys

n Sender and receiver use same key to

n Users issued public/private key pair Private

26 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300

Introducing PathWAI Secure for WebSphere MQ 27

FIGURE 2. Encrypting and Decrypting a Message with Public/Private Keys

28 PathWAI Secure for WebSphere MQ Administrator’s Guide, Version 300