tivoli secureway policy director -...

Tivoli® SecureWay® Policy DirectorPolicy Director for MQSeries AdministrationGuide3.7.1

Policy Director for MQSeries Administration Reference (May 2001)

Copyright Notice:

Copyright Notice

Licensed materials—property of IBM.

© Copyright IBM Corp. 2001. All rights reserved. May only be used pursuant to a Tivoli Systems Software License Agreement or Addendum for Tivoli Products to IBMCustomer or License Agreement. No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any computerlanguage, in any form or by any means, electronic, mechanical, magnetic, optical, chemical, manual, or otherwise, without prior written permission of Tivoli Systems.Tivoli Systems grants you limited permission to make hardcopy or other reproductions of any machine-readable documentation for your own use, provided that each suchreproduction shall carry the Tivoli Systems copyright notice. No other rights under copyright are granted without prior written permission of Tivoli Systems. Thedocument is not intended for production and is furnished “as is” without warranty of any kind. All warranties on this document are hereby disclaimed includingthe warranties of merchantability and fitness for a particular purpose.

Note to U.S. Government Users—Documentation related to restricted rights—Use, duplication or disclosure is subject to restrictions set forth in GSA ADP ScheduleContract with IBM Corporation.

Trademarks

The following product names are trademarks of Tivoli Systems Inc. or International Business Machines Corp. in the United States, other countries, or both: AIX, IBM,IBMLink, MQSeries, SecureWay, Tivoli, Manage. Anything. Anywhere., The Power To Manage. Anything. Anywhere., Tivoli Ready, Tivoli Certified, Planet Tivoli, TivoliEnterprise.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks or registered trademarks of Microsoft Corporation.

UNIX is a registered trademark in the United States and other countries licensed exclusively through The Open Group.

Java and all Java-based trademarks or logos are trademarks of Sun Microsystems, Inc.

Other company, product, and service names mentioned in this document may be trademarks or servicemarks of others.

Notices

References in this publication to Tivoli Systems or IBM products, programs, or services do not imply that they will be available in all countries in which Tivoli Systemsor IBM operates. Any reference to these products, programs, or services is not intended to imply that only Tivoli Systems or IBM products, programs, or services can beused. Subject to Tivoli System’s or IBM’s valid intellectual property or other legally protectable right, any functionally equivalent product, program, or service can be usedinstead of the referenced product, program, or service. The evaluation and verification of operation in conjunction with other products, except those expressly designatedby Tivoli Systems or IBM, are the responsibility of the user.

Tivoli Systems or IBM may have patents or pending patent applications covering subject matter in this document. The furnishing of this document does not give you anylicense to these patents. You can send license inquiries, in writing, to the IBM Director of Licensing, IBM Corporation, North Castle Drive, Armonk, New York10504-1785, U.S.A.

Contents

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vWho Should Read This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

Prerequisite and Related Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v

What This Guide Contains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Conventions Used in This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi

Platform-specific Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Accessing Publications Online . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Ordering Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Providing Feedback about Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Contacting Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii

Chapter 1. Understanding PD/MQ. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1PD/MQ Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

PD/MQ Components and Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

LDAP Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Policy Director . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Public Key Infrastructure (PKI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2. PD/MQ Migration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Migration of PD/MQ on a Solaris 7 Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Migration of PD/MQ on an AIX 4.3.3 Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Migration of PD/MQ on a Windows NT Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 3. PD/MQ Installation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9PD/MQ Installation Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Installation of PD/MQ on a Solaris 7 Platform. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Installation of PD/MQ on an AIX 4.3.3 Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Installation of PD/MQ on a Windows NT Platform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

Chapter 4. PD/MQ Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13Configuring the PD/MQ Protected Object Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Relocate the MQSeries Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Configuring PD/MQ to Connect to the Policy Director Authorization Service . . . . . . . . . . . . . . . . . . 14

Chapter 5. Administering PD/MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15Defining MQSeries resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Adding MQSeries Objects to Policy Director . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

iiiPD/MQ Administration Guide

Attaching PD/MQ Configuration Information to Policy Director Protected Objects . . . . . . . . . . 16

Defining PKI Identities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

iKeyman Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Creating a Key Database File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Receiving a CA Certificate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

Creating a Certificate Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Receiving Your Certificate from the CA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Importing Application or End-user Certificates for Encryption . . . . . . . . . . . . . . . . . . . . . . . . . 26

Mapping PKI Identities to Policy Director Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Creating the secPKIMap Object Class in LDAP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Adding secPKIMap Objects to Existing secMap Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Defining and Attaching Policy Templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Specifying Authorization for PD/MQ Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Specifying the PD/MQ Protected Object Policy (POP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

ACL Evaluation and Queue Name Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Creating a PD/MQ Login Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

A PD/MQ Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 6. MQSeries Considerations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37PD/MQ Interaction with MQSeries Authorization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Resetting PD/MQ after applying service fixes to MQSeries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

PD/MQ and Maximum Message Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Unsupported MQSeries Configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Chapter 7. PD/MQ Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39The PD/MQ Error Handling Queue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

pdmqdlh dlqutil Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Chapter 8. Auditing PD/MQ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

iv 3.7.1

Preface

Welcome to the Tivoli SecureWay Policy Director for MQSeries: Administration Reference3.7.1. Policy Director for MQSeries (PD/MQ) protects MQSeries messages. PD/MQ is anextension of Tivoli’s industry leading Policy Director product. PD/MQ allows MQSeriesapplications to send data with confidentiality and integrity using keys associated with thesending and receiving users. The Policy Director Authorization Service provides accesscontrol to MQSeries based services, restricting which users can and cannot get access tomessages on queues. PD/MQ enables you to have the following benefits:

¶ Defines and enforces centralized authorization policies (including data protection) forMQSeries resources (queues and messages on those queues) using the Policy Directorinfrastructure, which already provides:

v A common, scalable and reliable policy repository

v An extendable resource namespace and extendable permission sets

v A common console for managing policy

¶ Provides protection for MQSeries data as it flows across the network and as it sits in thequeue, using PKI technology.

¶ Provides the above protection transparently to existing MQSeries applications. MQSeriesapplications need not change in order to be protected by PD/MQ.

IBM® MQSeries® provides the following items:

¶ Simple, multi-platform API

¶ Assured message delivery

¶ Time independent processing

¶ Partner applications have independent state

¶ Application parallelism

PD/MQ protection can be used in conjunction with MQSeries built-in security (for examplethe Object Authority Manager and the Message Channel exits).

Who Should Read This GuideThe target audience for this module is System Administrators who are familiar withMQSeries.

Prerequisite and Related Documents¶ Tivoli SecureWay Policy Director for MQSeries: Release Notes 3.7.1

Provides information about:

v System requirements

v Installation notes

v Defects, limitations, and workarounds

v Documentation additions

v Documentation corrections

vPD/MQ Administration Guide

¶ Tivoli SecureWay Policy Director Base: Installation Guide 3.7.1

¶ Tivoli SecureWay Policy Director Base: Administration Guide 3.7.1

¶ Tivoli SecureWay Policy Director Base: Developer Reference 3.7.1

¶ MQSeries Planning Guide Version 5.1

¶ MQSeries System Administration Manual Version 5.1

What This Guide ContainsThe Tivoli SecureWay Policy Director for MQSeries: Administration Reference 3.7.1 containsthe following sections:

¶ Chapter 1, “Understanding PD/MQ” on page 1

Lists PD/MQ functions and describes key components and dependencies.

¶ Chapter 2, “PD/MQ Installation” on page 9

Describes the installation of Policy Director for MQSeries and its components andprerequisites: Policy Directory RunTime Executable (PDRTE) Version 3.7.1, SecureWayDirectory Client Version 3.2, and MQSeries Server Version 5.1.

¶ Chapter 3, “PD/MQ Configuration” on page 13

Describes the configuration of PD/MQ.

¶ Chapter 4, “Administering PD/MQ” on page 15

Describes the details of deploying Policy Director for MQSeries in a typical MQSeriesenvironment. It provides scenarios of a MQSeries setup and illustrates Policy Directorfor MQSeries configuration for such a deployment.

¶ Chapter 5, “MQSeries Considerations” on page 37

Discusses interoperational considerations for MQSeries and PD/MQ.

¶ Chapter 6, “PD/MQ Error Handling” on page 39

Describes how the PD/MQ error queue works.

¶ Chapter 7, “Auditing PD/MQ” on page 41

Describes the Policy Director audit function support for PD/MQ.

Conventions Used in This GuideThe guide uses several typeface conventions for special terms and actions. Theseconventions have the following meaning:

Bold Commands, keywords, file names, authorization roles, Web addresses, orother information that you must use literally appear like this, in bold.Names of windows, dialogs, and other controls also appear like this, inbold.

Italics Variables and values that you must provide appear like this, in italics. Wordsand phrases that are emphasized also appear like this, in italics.

Monospace Code examples, output, and system messages appear like this, in amonospace font.

vi 3.7.1

This guide uses the UNIX™ convention for specifying environment variables and fordirectory notation. When using the Windows NT® command line, replace $variable with%variable% for environment variables and replace each forward slash (/) with a backslash(\) in directory paths.

Note: When using the bash shell on a Windows NT system, you can use the UNIXconventions.

Platform-specific InformationThe following table identifies the supported platform versions known at the time ofpublication. For more detailed and up-to-date information, see Tivoli SecureWay PolicyDirector for MQSeries: Release Notes 3.7.1.

Platform Supported Versions

Solaris Sun SPARC series running Solaris, Version 7

Windows NT IBM-compatible PCs 486 or higher running Microsoft Windows NT,Versions 4.0, Service Packs 5 and 6.

AIX® IBM RS/6000 series running AIX, Version 4.3.3

Accessing Publications OnlineThe Tivoli Customer Support Web site (http://www.tivoli.com/support/) offers a guide tosupport services (the Customer Support Handbook); frequently asked questions (FAQs); andtechnical information, including release notes, user’s guides, redbooks, and white papers.You can access Tivoli publications online at http://www.tivoli.com/support/documents/.The documentation for some products is available in PDF and HTML formats. Translateddocuments are also available for some products.

To access most of the documentation, you need an ID and a password. To obtain an ID foruse on the support Web site, go to http://www.tivoli.com/support/getting/.

Resellers should refer to http://www.tivoli.com/support/smb/index.html for moreinformation about obtaining Tivoli technical documentation and support.

Business Partners should refer to “Ordering Publications” for more information aboutobtaining Tivoli technical documentation.

Ordering PublicationsOrder Tivoli publications online athttp://www.tivoli.com/support/Prodman/html/pub_order.html or by calling one of thefollowing telephone numbers:

¶ U.S. customers: (800) 879-2755

¶ Canadian customers: (800) 426-4968

viiPD/MQ Administration Guide

Providing Feedback about PublicationsWe are very interested in hearing about your experience with Tivoli products anddocumentation, and we welcome your suggestions for improvements. If you have commentsor suggestions about our products and documentation, contact us in one of the followingways:

¶ Send e-mail to [email protected].

¶ Fill out our customer feedback survey at http://www.tivoli.com/support/survey/.

Tivoli does not want to receive confidential or proprietary information from you. Please notethat any information or material sent to Tivoli will be deemed NOT to be confidential. Bysending Tivoli any information or material, you grant Tivoli an unrestricted, irrevocablelicense to use, reproduce, display, perform, modify, transmit and distribute those materials orinformation, and you also agree that Tivoli is free to use any ideas, concepts, know-how ortechniques that you send us for any purpose. However, we will not release your name orotherwise publicize the fact that you submitted material or other information to us unless: (a)we obtain your permission to use your name; or (b) we first notify you that the materials orother information you submit to a particular part of this site will be published or otherwiseused with your name on it; or (c) we are required to do so by law.

Contacting Customer SupportYou can contact Tivoli Customer Support in one of the following ways:

¶ Submit a problem management record (PMR) electronically from our Web site athttp://www.tivoli.com/support/reporting/. For information about obtaining supportthrough the Tivoli Customer Support Web site, go tohttp://www.tivoli.com/support/getting/.

¶ Submit a PMR electronically through the IBMLink™ system. For information aboutIBMLink registration and access, refer to the IBM Web page athttp://www.ibmlink.ibm.com.

¶ Send e-mail to [email protected].

¶ Customers in the U.S. can call 1-800-TIVOLI8 (1-800-848-6548).

¶ Customers outside the U.S. should refer to the Tivoli Customer Support Web site athttp://www.tivoli.com/support/locations.html for customer support telephone numbers.

When you contact Tivoli Customer Support, be prepared to provide the customer number foryour company so that support personnel can assist you more readily.

viii 3.7.1

Understanding PD/MQ

Policy Director for MQSeries (PD/MQ) operates in conjunction with Tivoli’s Policy Directorproduct. With PD/MQ you can:

¶ Secure sensitive or high value messages processed by IBM MQSeries

¶ Control which users have access to specific queues

¶ Detect and remove rogue or unauthorized messages before they are processed by areceiving application

¶ Generate detailed auditing records showing which messages were expressly authorizedand encrypted

¶ Verify that messages were not modified while in transit from queue to queue

¶ Centrally define authorization policies (including quality of data protection) forMQSeries resources (queues and messages on those queues) using a common consolefor heterogeneous servers across their enterprise

¶ Protect your data as it flows across the network and as it sits in a queue

¶ Secure existing off-the-shelf and customer-written applications for IBM MQSeries

PD/MQ furnishes MQSeries applications with the following functionality:

¶ A centralized authorization service defining access control policies for MQSeries queuesand messages on these queues.

¶ Confidentiality, in the form of encryption, and integrity, in the form of checks againstmessage modification, so that senders and receivers of MQSeries messages can exchangeMQSeries messages with complete security. PD/MQ provides these services while themessage is in transit as well as when the messages are stored in the queues.

¶ Integrates PKI technology into MQSeries. PD/MQ identifies MQSeries users withidentities that are operating system and network independent.

¶ Provides message-level security transparently. MQSeries applications do not have to bemodified to be protected by PD/MQ.

This chapter contains the following sections:

¶ “PD/MQ Compatibility” on page 2

¶ “PD/MQ Components and Dependencies” on page 2

1

1PD/MQ Administration Guide

1.U

nd

erstand

ing

PD

/MQ

PD/MQ CompatibilityPD/MQ depends on several technology components to provide a security infrastructure.PD/MQ does not require you to license any additional Tivoli products to use this solution.PD/MQ is, however, compatible with the following Tivoli products:

¶ Tivoli SecureWay Policy Director Version 3.7.1

¶ Tivoli SecureWay PKI

¶ Tivoli Data Exchange

PD/MQ Components and DependenciesThe key piece of PD/MQ is a set of multi-threaded, shared libraries that execute in theprocess space of a MQSeries application. The PD/MQ libraries intercept MQSeries APIcalls, thus enabling MQSeries applications to be secured without any changes.

Figure 1 shows a block diagram of the core PD/MQ components and the securityinfrastructure components (in shaded areas). The diagram shows two LDAP directories, but asingle LDAP can be used by both Policy Director and the PKI services.

Figure 1. PD/MQ Environment

2 3.7.1

Note: The infrastructure components most likely do not reside in the same system asPD/MQ and MQSeries; however, their services need to be accessible by the PD/MQproduct.

The objectives for this section are as follows:

¶ Provide some background on the role played by each of the infrastructure components

¶ Refer to documents providing complete installation information for the infrastructurecomponents

¶ Highlight some of the steps associated with each installation and the one-time setup andconfiguration of the infrastructure and environment components

LDAP DirectoryThe Tivoli Policy Director can be configured to use an LDAP server as its user registry. Inthis case, the LDAP directory server needs to be installed and configured prior to the PolicyDirector installation. Policy Director currently supports the IBM SecureWay, Peer Logic, andNetscape directory servers.

The IBM SecureWay Directory can be installed on a Solaris, an AIX, or a Windows NTsystem. Install the SecureWay Directory on a machine designated to be your official datarepository. The IBM SecureWay Directory is included in the Tivoli SecureWay PolicyDirector CDs that are part of the PD/MQ package

The complete installation instructions are available in the following manuals:

¶ IBM SecureWay Directory for the Solaris Operating Environment Software Installationand Configuration Version 3.2

¶ IBM SecureWay Directory Installation and Configuration for Windows NT Version 3.2

Refer to the installation manual appropriate to your platform.

Policy DirectorTivoli Policy Director is the centralized authorization policy management system used byPD/MQ and other applications. PD/MQ relies on Policy Director for the following services:

¶ Enterprise user registry for Policy Director users

¶ Centralized system to define authorization and data protection policy for access toMQSeries resources (queues)

PD/MQ uses the Tivoli Policy Director AZN API (PDauthADK) to obtain data protectionand authorization policy from the Policy Director Authorization Servers (PDACLD), or theMaster Policy Server (PDMGR).

Policy Director can reside on either a Solaris, an AIX, a Windows NT, or an HP/UX system.

Install the Policy Director package on the machines chosen for this purpose. Refer to thecomplete installation instructions for the platform chosen for the Tivoli Policy DirectorVersion 3.7.1 product.

The following manuals provide the required information:

¶ Tivoli SecureWay Policy Director Base Installation Guide for Windows NT


1.U

nd

erstand

ing

PD

/MQ

¶ Tivoli SecureWay Policy Director Base Installation Guide for Solaris

¶ Tivoli SecureWay Policy Director Base Installation Guide for AIX

¶ Tivoli SecureWay Policy Director Base Installation Guide for HP/UX

¶ Tivoli SecureWay Policy Director Base Administration Guide

PD/MQ depends on the following components of Policy Director: Policy Director RunTimeEnvironment (PDRTE), PDMGR, PDAcld, and the Console. PDRTE must be installed oneach machine that will be running PD/MQ. The others can be elsewhere.

Public Key Infrastructure (PKI)PKI runtime services are provided by the GSKIT component of PD/MQ. GSKIT allows theuser to request certifications, store certifications, and apply keys to provide data integrityand data security.

The GSKIT user will need to specify a Certification Authority (CA). The CA issues andrevokes certifications. GSKIT supports the following CAs:

¶ Tivoli PKI 3.7

¶ Entrust Web Connector 5.0

¶ iPlanet CMS 4.2

4 3.7.1

PD/MQ Migration

This chapter describes the migration of PD/MQ components. PD/MQ is being delivered onthree platforms: AIX 4.3.3, Solaris Version 7 and Windows NT 4.0 SP5. This chapterconsists of the following sections:

¶ ″Migration of PD/MQ on a Solaris 7 Platform″

¶ ″Migration of PD/MQ on an AIX 4.3.3 Platform″

¶ ″Migration of PD/MQ on a Windows NT Platform″

Migration of PD/MQ on a Solaris 7 Platform1. Stop the MQSeries server.

2. Log in as root.

3. Run the following command to unconfigure PD/MQ:

mvlib -unconfig

4. Run the following commands to remove the GSKIT component and PD/MQ:

$ pkgrm gsk4bas

$ pkgrm PDMQrte

The directory /opt/pdmq/lib remains on your system. Do not delete it. This directory contains n

5. The directory /opt/pdmq/log also remains on your system. You might want to keep thisdirectory since it contains audit files.

6. Follow the instructions in “Installation of PD/MQ on a Solaris 7 Platform” on page 10 toinstall the new version of PD/MQ.

7. Run the following command to configure PD/MQ:

mvlib -config

8. Start the MQSeries server.

2


2.P

D/M

QM

igratio

n

Migration of PD/MQ on an AIX 4.3.3 Platform1. Stop the MQSeries server.

2. Log in as root.


mvlib -unconfig

4. Start System Management Interface Tool. The System Management menu displays.

5. Select Software Installation and Maintenance.

6. Select Software Maintenance and Utilities.

7. Select Remove Installed Software.

8. Click List to display the list of software that can be removed.

9. Select PDMQ.rte and click OK.

10. For Preview Only, select NO and click OK.

11. In the dialog box that displays the message, ″!Continuing may delete information youmay want to keep. This is your last chance to stop before continuing,″ click OK.

12. When the uninstallation is complete, click Done.

13. The directory /opt/pdmq/lib remains on your system. Do not delete it. This directorycontains necessary configuration files.

14. The directory /opt/pdmq/log also remains on your system. This directory contains auditfiles.

15. Follow the instructions in “Installation of PD/MQ on an AIX 4.3.3 Platform” onpage 11 to install the new version of PD/MQ.


mvlib -config


Migration of PD/MQ on a Windows NT Platform1. Log in as Administrator.

2. Stop the MQSeries server.


mvlib -unconfig

4. Uninstall PD/MQ using Add/Remove Programs which can be found under the ControlPanel.

5. The directory <install path>\Tivoli\PDMQ\lib remains on your system. Do not delete it.This directory contains necessary configuration files.

6. The directory <install path >\Tivoli\PDMQ\log also remains on your system. Thisdirectory contains audit files.

6 3.7.1

7. Follow the instructions in the “Installation of PD/MQ on a Windows NT Platform” onpage 12 to install the new version of PD/MQ.


mvlib -config



2.P

D/M

QM

igratio

n

8 3.7.1

PD/MQ Installation

This chapter describes the installation and configuration of PD/MQ components in detail.PD/MQ is being delivered on three platforms: AIX 4.3.3, Solaris Version 7 and WindowsNT 4.0 SP5. This section describes the installation and configuration instructions for thesethree platforms.

This chapter consists of the following sections:

¶ “PD/MQ Installation Prerequisites” on page 9

¶ “Installation of PD/MQ on a Solaris 7 Platform” on page 10

¶ “Installation of PD/MQ on an AIX 4.3.3 Platform” on page 11

¶ “Installation of PD/MQ on a Windows NT Platform” on page 12

PD/MQ Installation PrerequisitesBefore installing PD/MQ the following software must be installed and configured in yourenvironment; PD/MQ can not install if these dependencies are not met.

¶ Prerequisites for the PD/MQ environment:

v IBM SecureWay LDAP Client— This client can be found on the Tivoli SecureWayPolicy Director Base for Windows 3.7.1 CD (for Windows platforms), the TivoliSecureWay Policy Director Base for Sun Solaris 3.7.1 CD, or the Tivoli SecureWayPolicy Director Base for AIX 3.7.1 CD. To install the LDAP client from theWindows CD, use Windows Explorer or My Computer to find the \SecureWay_Directory \ldap32_us directory on the CD, and double-click setup.exe. Toinstall the LDAP client from the Sun Solaris CD, insert the Policy Director Base forSun Solaris CD into the CD-ROM drive, mount it to /cdrom, and run the followingcommand:$ pkgadd –d/cdrom/SecureWay_Directory/Idap32_us IBMldapc. Toinstall the LDAP client from the AIX CD, perform the following steps:

1. Insert the Policy Director Base for AIX 3.7.1 CD into the CD drive.

2. Mount it to /cdrom.

3. Start System Management Interface Tool (SMIT). The System Managementmenu appears.


5. Select Install and Update Software.

6. Select Install and Update Software from Latest Available Software.

3


3.P

D/M

QIn

stallation

7. Enter the directory from which you are installing the software. For example, ifthe CD is mounted on /cdrom, enter the following path:/cdrom/SecureWay_Directory/ldap32_us

8. Click OK.

9. Click List to display the list of software that can be installed.

10. Select ldap.client and click OK.

11. Accept the defaults for all other data fields and click OK.

12. In the dialog box that displays the message, ″!Continuing may deleteinformation you may want to keep. This is your last chance to stop beforecontinuing,″ click OK.

13. When the installation is completed, click DONE.

v Policy Director(PD) 3.7.1 Master Policy Server (PDMgrd)

v Policy Director (PD) 3.7.1 Authorization Server (PDAcld)

v CA— PD/MQ includes Asynchronous Cryptographic Message Enablement (ACME),which is part of the GSKIT component of PD/MQ. ACME is used by PD/MQ tosign, verify, encrypt, and decrypt MQSeries messages. It supports the following:

– Tivoli PKI 3.7

– Entrust Web Connector 5.0

– iPlanet CMS 4.2

v Policy Directory User Registry—Policy Director maintains its users and groups onan LDAP-based user registry. Install and configure an LDAP server for PolicyDirector usage (schema loading) prior to Policy Director installation.

v Management Console

¶ Prerequisites for each machine that will run PD/MQ:

v Policy Director 3.7.1 PDRTE must be installed on each client machine.

v MQSeries 5.1 server

v For NT platforms only, Java Runtime must be in the path in order to use interactivelogon. The one shipped with the LDAP client can be used. If you wish to use theJava Runtime that is shipped with LDAP, set the following path in your environment:

\Program Files\IBM\LDAP\jre\bin

Installation of PD/MQ on a Solaris 7 PlatformAs mentioned in the previous chapter, PD/MQ requires that infrastructure components areinstalled and operational for its proper functioning.

The following steps detail the installation of PD/MQ on a Solaris 7 platform:


2. Log in as root.

3. Remove the GSKIT component previously installed by Policy Director. Issue thefollowing command:

10 3.7.1

$ pkgrm gsk4bas

You might receive a message indicating that applications are still using this package. Themessage asks if you wish to continue. Type Y.

4. Insert the PD/MQ CD into CD-ROM drive, mount it to /cdrom, and run the followingcommands:

$ pkgadd –d /cdrom/Solaris/pdmq gsk4bas

$pkgadd –d /cdrom/Solaris/pdmq PDMQrte

5. In the menu displayed, select Install PD/MQ. The system creates the following directorytree:/opt/PDMQ/bin/doc/lib/nls/msg/C

/log

Installation of PD/MQ on an AIX 4.3.3 PlatformAs mentioned in the previous chapter, PD/MQ requires that infrastructure components areinstalled and operational for its proper functioning.

The following steps detail the installation of PD/MQ on AIX 4.3.3:


2. Log in as root, insert the PD/MQ CD into the CD-ROM drive, and mount it to /cdrom.

3. Start SMIT.. The System Management menu appears.


5. Select Install and Update Software.

6. Select Install and Update Software from Latest Available Software.

7. Enter the directory from which you are installing the software. For example, if the CDis mounted on /cdrom, enter the following path:

/cdrom/AIX/pdmq

8. Click OK.

9. Click List to display a list of software that can be installed.

10. Select PD/MQ and GSKIT.

11. Click OK.

12. Accept the default settings for everything else and click OK.

13. In the dialog box that displays the message, ″!Continuing may delete information youmay want to keep. This is your last chance to stop before continuing,″,″ click OK.

14. When the installation is complete, click DONE.

15. The following directory tree has been created:


3.P

D/M

QIn

stallation

/opt/PDMQ/bin/doc/lib/nls/msg/C

/log

Installation of PD/MQ on a Windows NT PlatformThe following steps detail the installation of PD/MQ on a Windows NT platform:

1. Log in as Administrator.


3. Insert the PD/MQ CD into the CD-ROM drive, change directory to \WinNT\pdmq, andrun setup. Follow the instructions on screen. The setup creates the following directorytree:<install path>\Tivoli\PDMQ\bin\doc\lib\nls\log

12 3.7.1

PD/MQ Configuration

The configuration of PD/MQ consists of several steps involving Policy Director, PKI andPD/MQ. PD/MQ includes some utilities to ease the configuration procedure. Theconfiguration needs to be done in the order specified.

Configuring the PD/MQ Protected Object SpaceThis portion of the configuration should be run only once, from the first machine installedwith PD/MQ. These commands must be run as root (for Solaris or AIX) or Administrator(for Windows NT).

Use the pdmqcfg command to create the /PDMQ/Queue object space in the Policy Directorprotected object space. PD/MQ uses D (Dequeue) and E (Enqueue) permissions. Thesepermissions will also be created by pdmqcfg under an action group called PDMQ. Thepdmqcfg utility is required to be run from only the first machine on which you areconfiguring PD/MQ.

The command syntax for pdmqcfg is:pdmqcfg -config -admin sec_master -pwd <sec_master password>[-pkisystem ACME] [-pkiencqop STRONG|MEDIUM|WEAK|DEFAULT] [-pkisigqop MD2|MD5|SHA1|DEFAULT] \[-quereres local|remote] [-help]-config: creates PD/MQ configuration data in Policy Director-unconfig: removes PD/MQ configuration data from Policy Director-admin: pdadmin id (required)-pwd: pdadmin password (required)-pkisystem: which underlying PKI system PD/MQ uses, default is ACME, and currently PD/MQsupports only ACME (optional)-pkiencqop: specifies data privacy algorithm, STRONG/MEDIUM/WEAK, default is STRONG(optional)-pkisigqop: specifies data integrity algorithm, MD2/MD5/SHA1, default is MD2(optional)-quereres: local/remote, default is local (optional)-help: prints help information

Relocate the MQSeries LibraryThe command mvlib relocates the shared library installed by MQSeries and replaces it withthe one included with PD/MQ. This command must be run prior to restarting MQSeries, andalso after applying any service packs or PTFs to MQSeries. The format of the command is:mvlib -config|-unconfig

-config relocates the MQSeries shared library-unconfig restores the MQSeries shared library

4


4.P

D/M

QC

on

figu

ration

Configuring PD/MQ to Connect to the Policy Director AuthorizationService

Perform the following steps to initialize the PD/MQ configuration files:

1. In the lib directory, copy the file pdmqazn.conf.in to pdmqazn.conf. Thepdmqazn.conf.in file is a template for the file actually used by PD/MQ(pdmqazn.conf).

2. Edit pdmqazn.conf, and update the following sections:

¶ In the [ldap] section, change the value of host to the hostname of the LDAP serverused by Policy Director as its user registry.

¶ In the [azn-entitlements-services] section, uncomment the line that specifies theentitlements service. Be sure you uncomment the line specific to the operatingsystem you are running on.

3. In the lib directory, copy the file pdmq.conf.in to pdmq.conf. The pdmq.conf.in file isa template for the file (pdmq.conf) actually used by PD/MQ.

As root (Solaris or AIX) or Administrator (Windows NT), run the following command in thePD/MQ library directory:svrsslcfg pdmqazn.conf –config –d <kdb–dir> –n pdmq –s local –A <sec–master–name>\

–P <pw> –S <server_password>

where

<kdb-dir>path to the lib directory for PDMQ

<sec-master-name>name used by Policy Director Master Server, which usually defaults to sec_master

<pw> password for sec_master_name above

<server_password>password used to access LDAP on behalf of PD/MQ

This command creates a key database and stash file for PD/MQ. Using the appropriateadministrative commands, ensure that all users have read access to the database and stashfile.

Use the command pdmqsniff to retrieve info from the Policy Director configuration andmake it available for PD/MQ. Run pdmqsniff to create a pdmqcfg.bin file in the libsubdirectory.

14 3.7.1

Administering PD/MQ

This chapter describes the details of deploying PD/MQ in a typical MQSeries environment.It provides scenarios of a MQSeries setup and illustrates PD/MQ configuration for such adeployment.

The approach in getting PD/MQ operational for MQSeries environments is as follows:

1. Define MQSeries resources for all applications for the secure domain.

2. Define PKI identities for all applications using MQSeries in the secure domain.

3. Define PKI identities for all users using these applications.

4. Provide Policy Director user registry mappings for all PD/MQ users and groups.

5. Define and attach Policy Templates in the form of Protected Object Policy (POP) andAccess Control Lists (ACLs) for all PD/MQ defined resources.

Defining MQSeries resourcesThe first and foremost task to get PD/MQ operational is for MQSeries administrators toconfigure and actively deploy the MQSeries environment for the secure domain beingprotected under PD/MQ. This includes defining MQSeries objects like queue managers;local, remote, model, and transmission queues; channels; and tasks that set up listeners andtest MQSeries sample programs between servers.

In PD/MQ installations where MQSeries is already deployed, this is already done prior toinstalling PD/MQ. Refer to the MQSeries Planning Guide and the MQSeries SystemAdministration manuals Version 5.1 for assistance in defining the MQSeries objects.

After all MQSeries resources are defined and operational, the next step is to populate theseresources in the Policy Director protected object namespace. The objects that appear in thishierarchical namespace represent the actual protected resources. Policy Director attachesaccess control templates on these resources.

Adding MQSeries Objects to Policy Director

Note: Before running mq2pd, verify that pdmqcfg has been run on the first machine withPD/MQ installed.

Run the mq2pd command line utility (packaged with PD/MQ) against every queue managerin your secure MQSeries environment. This command retrieves the queue information for agiven queue manager and puts the data into the Policy Director protected object space.

mq2pd requires that the local OS user have MQSeries administrative permission, and thatthe MQSeries command server is running. You can start the command server as follows:

5


5.A

dm

inisterin

gP

D/M

Q

strmqcsv <Queue Manager Name>

The syntax for mq2pd is:mq2pd -config|-unconfig -admin <pdadmin> -pwd <pdadmin-pwd> -qm <Queue Manager Name>

mq2pd -config pulls all the queues for a particular queue manager into the Policy Directorprotected object space.

Attaching PD/MQ Configuration Information to Policy DirectorProtected Objects

Use the pdadmin command in the Policy Director Management Console to addPD/MQ-specific configuration data as attributes of Protected Objects.

Configuration Information for /PDMQ/Queue/<QueueManager>The Error-handling-Q attribute is required for each queue manager. There is no default forit, so you must set a value for this attribute. Error-handling-Q is the queue name of thePD/MQ error handling queue (see “PD/MQ Error Handling” on page 39 for information onthe error handling queue). You must use MQSeries commands (such as MQSC) or theMQSeries Explorer to create this queue. PD/MQ does not create this queue automatically.

The pdadmin commands to set these parameters are as follows (in each case, replace<QueueManager> with your actual queue manager name:pdadmin -a sec_master -p <sec_master password> -- this logs you onto Policy Directorpdadmin> object modify /PDMQ/Queue/<QueueManager> set attribute Error-handling-Q <queue nameof PDMQ error handling queue>

Note: Neither the pdadmin command nor the Policy Director Management Consolevalidates the name or value of the Error-handling-Q attribute, so be certain to enterit correctly.

Configuration Information for /PDMQ/Queue/<QueueManager>/<Queue>For each queue, you need set only the following information if you want to send messagesin privacy (encrypted) and want to specify an algorithm strength other than the default:Q-recipients = <DN of recipient>Q-enc-strength = STRONG/MEDIUM/WEAKQ-sig-algorithm = MD2/MD5/SHA1

If you are only signing the message, Q-recipients and Q-enc-strength need not bespecified.

The pdadmin commands to set these parameters are as follows (in each case, replace<QueueManager> and <Queue> with the actual queue manager and queue names):pdadmin -a sec_master -p <sec_master password> -- this logs you onto Policy Directorpdadmin object modify /PDMQ/Queue/<QueueManager>/<Queue> set attributeQ-recipients "CN=xxx;O=abc;C=us " --- distinguished name (DN) of recipient1pdadmin> object modify /PDMQ/Queue/<QueueManager>/<Queue> set attributeQ-recipients "cn=yyy" --- DN of recipient2pdadmin> object modify /PDMQ/Queue/<QueueManager>/<Queue> set attributeQ-enc-strength <STRONG/MEDIUM/WEAK>pdadmin> object modify /PDMQ/Queue/<QueueManager>/<Queue> set attributeQ-sig-algorithm <MD2/MD5/SHA1>

When specifying DNs in certificates, use the following format: - Component names (such asC, CN, O, OU) must be specifed in upper case, and each component must be separated by asemicolon (;).

16 3.7.1

You can add multiple recipients by repeating the pdadmin command that sets theQ-recipients attribute.

Note: Neither the pdadmin command nor the Policy Director Management Consolevalidates the name or value of the Q-recipients attribute, so be certain to enter itcorrectly.

Defining PKI IdentitiesThese steps involve providing each PD/MQ protected application with a profile as well asassociating each PD/MQ user of these applications with a PKI identity. For each PD/MQuser, the PKI administrator must perform the following steps:

1. Create a Policy Director identity via the Management Console or with the pdadmincommand.

2. Create a PKI identity using iKeyman.

3. Map the PKI identity to a Policy Director identity.

4. Create a PD/MQ login context.

iKeyman OperationsTo use PD/MQ, you must create a public/private key pair and a certificate. Additionally, youmust have the certificate of the CA that issues the user or application certificate importedinto the client key database file and marked as a trusted root.

To create a certificate that is signed by a CA:

1. Create a certificate request using gsk4ikm.

2. Submit the certificate request to the CA. This may be done via e-mail, or an onlinesubmission from the CA’s web page.

3. Receive the response from the CA to an accessible location on the file system of yourserver.

4. Receive the certificate into your key database file.

If you are obtaining a signed client certificate from a CA that is not in the default list oftrusted CAs, you will need to obtain the CA’s certificate, receive it into your key databaseand mark it as trusted. You must do this before receiving your signed client certificate intothe key database file.

Note: Certificates used by PD/MQ must have the key usage fields in the certificate setappropriately by the CA. For certificates used for integrity, the key usage field mustbe set to nonRepudiation and digitalSignature. For data privacy, the key usage fieldmust also include the dataEncipherment setting.

The gsk4ikm utility also has the ability to import public-private key pairs and certificatesthat were previously generated (using a PKCS #12 format).

Creating a Key Database File1. Type gsk4ikm to start the Java utility. For Solaris the path is /opt/ibm/gsk4/bin, for AIX

the path is /usr/opt/ibm/gskit/bin, and for NT the path is \program files\ibm\gsk4\bin.


5.A

dm

inisterin

gP

D/M

Q

2. Click Key Database File.

3. Click New (or Open if the key database already exists).

4. Specify key database file name and location, and click OK. See Figure 2.

Note: A key database is a file that the client or server uses to store one or more keypairs and certificates. If you are creating a key database file for an end-user, yousimply specify a password for the key database file, and click OK. See .

If you are creating a key database file for a non-interactive application, you must store thepassword into a stash file. PD/MQ uses the stash file to open the key database file (insteadof prompting the user for a password). To enable stash file support for this key database,check the box labeled Stash the password to a file? See Figure 3.

Change the key database password frequently. If you specify an expiration date, you need tokeep track of when you need to change the password. If the password expires before youchange it, the key database is not usable until the password is changed.

Figure 2. Create a Key Database File

Figure 3. Enable Stash File Support

18 3.7.1

CAUTION:Possession of a stash file and the associated key database are sufficient to impersonatethe application associated with the public-private key pair and certificate stored in thekey database.

Receiving a CA CertificateUsually, you will receive a CA certificate via e-mail, download it from a web site, or bepointed to a file that contains the CA certificate.

1. Under Key Database Content, click Signer Certificates. Click Add. See Figure 4.

2. Select the data type of the CA certificate you wish to add, either Base 64 encodedASCII data or Binary DER data. Base 64 encoded ASCII data is also known as PEMencoding. Your PKI administrator will tell you which data type to use. Specify the filename and location of the CA certificate. See Figure 5 on page 20.

3. Click OK. You will be prompted to enter a label for the certificate. See Figure 6 onpage 20. The label identifies the CA certificate in the Key Database file.

4. Select ″OK″. You will now see the certificate you requested in the list of SignerCertificates. See Figure 7 on page 20.

5. To mark the certificate as a trusted root (i.e. a CA), click the View/Edit button. Selectthe check box labeled Set the certificate as a trusted root. See Figure 8 on page 21

Figure 4. Add a CA Certificate


5.A

dm

inisterin

gP

D/M

Q

Figure 5. Specify CA Certificate Type

Figure 6. Enter CA Certificate Label

Figure 7. Display Requested Certificate in List

20 3.7.1

Creating a Certificate Request1. Under Key Database Content, click Personal Certificate Requests. See Figure 9 on

page 22.

2. Click New. See Figure 10 on page 23.

3. Supply user-assigned label for the key pair. The label identifies the key pair andcertificate in the key database file.

4. Enter the common name. This should be unique and the full name of the user.

5. Enter the organization name.

6. Enter the organizational unit name. This is an optional field.

7. Enter the locality (city) where the user or application is located. This is an optionalfield.

8. Enter a three-character abbreviation of the state or province where the user orapplication is located. This is an optional field.

9. Enter the postal code appropriate for the user or application location. This is an optionalfield.

Figure 8. Set Certificate as Trusted Root


5.A

dm

inisterin

gP

D/M

Q

10. Enter the two-character country code where the user or application is located.

11. Click OK.

12. A message identifying the name and location of the certificate request file is displayed.See Figure 11 on page 23. Click OK.

Figure 9. Request Personal Certificate

22 3.7.1

The certificate request is now displayed in the list of outstanding requests. See Figure 12 onpage 24.

Figure 10. Enter Data for Certificate Request

Figure 11. Location of Certificate Request


5.A

dm

inisterin

gP

D/M

Q

Send the certificate request to the CA. The manner in which your certificate request is sentto the CA and approved depends upon how your PKI administrator set up the PKI for yourorganization.

Receiving Your Certificate from the CA1. Under Key Database Content, click Personal Certificates. See Figure 13 on page 25.

2. Click Receive.

3. Enter the file name and location of the certificate you received from the CA and clickOK. See Figure 14 on page 25.

Figure 12. Certificate Request Displayed in List

24 3.7.1

The certificate is now displayed in your list of certificates. See Figure 15 on page 26.

Figure 13. Receive Personal Certificate

Figure 14. Enter Certificate Name and Location


5.A

dm

inisterin

gP

D/M

Q

Importing Application or End-user Certificates for EncryptionIf an application or user needs to send an encrypted message, PD/MQ requires that therecipient’s certificate be imported into the key database. The steps to do this are almostexactly the same as those to import a CA certificate, with one critical difference: Do notselect the check box labeled Set the certificate as a trusted root after you import theapplication or end-user certificate. Verify that this box is not selected.

Mapping PKI Identities to Policy Director UsersPD/MQ requires that Policy Director be configured to store user and group information intoan LDAP directory. Figure 16 on page 27 shows a typical installation of Policy Director userand group information in an LDAP directory:

Figure 15. Certificate Request Completed

26 3.7.1

The secMap objects store links between a Policy Director user entry in LDAP and therepresentation of the Policy Director user in the Policy director authorization database. Themapping model is illustrated in Figure 17 on page 28.

User Object

(inetorgperson)

PD Information

(secUser)

UUID Mapping

(secMap)

UUID Mapping

(secMap)

Group Object

(accessGroup)

PD Information

(secGroup)

O=PISC Cn=Users Cn=Groups

C=GB secAuthority=Default

Figure 16. A typical Policy Director tree in LDAP


5.A

dm

inisterin

gP

D/M

Q

The authorization database represents users (and groups) as Unique Universal Identifiers(UUIDs). When a user is created using the Policy Director Management Console or thepdadmin command, the user is created in LDAP and the appropriate secMap object, and aUUID is also created with a pointer back to the user entry in LDAP.

PD/MQ extends the secMap object to link a user’s certificate to the user’s Policy Directoruser entry. The extension is done by adding an auxiliary object to the secMap object. Thisauxilliary object has an LDAP object class of secPKIMap. The relationship between secMapand secPKI map is shown in Figure 18 on page 29.

objectClass: secMap

top

secDN: cn=UserA,o=pisc,c=gb

secUUID: 1034....3e12

Authorization Database

10a34....3e12 T[PDMQ]ED

cn=jon

o=pisc

c=gb

Figure 17. Using the secMap object to tie Policy Director user entries to authorization database information

28 3.7.1

The secCertDN attribute in the secPKIMap object contains the Distinguished Name (DN) ofthe user’s PKI certificate. When PD/MQ receives a PKI identity in a certificate, it searchesthe secMap objects to find the one whose secCertDN attribute matches the DN of thecertificate.

Creating the secPKIMap Object Class in LDAPThe secPKIMap object class can be created using the Directory Management Tool (DMT)that is shipped with the SecureWay Directory Server. It can also be created by using theldapmodify command, passing as input the pdmq.ldif file found in the doc directory of thePD/MQ CD. You must have administrative access to the LDAP server to add the secPKIMapobject. Figure 19 on page 30 through Figure 21 on page 31 show the sequence of steps tocreate this object class. The first step is to create secPKIMap as an auxiliary object class,with a superior object class of secMap. The OID is 1.3.6.1.4.1.4228.4.1 and needs tospecified when creating the secPKIMap object class. The next step is to specify thesecCertDN as a required attribute of secPKIMap, and then specifying secCertSerialNumberand secAuthority as optional attributes.

objectClass:

objectClass:

objectClass:secMap

top

secMap

top

secPKIMap

secPKIMap


secUUID: 1034....3e12

secCertDN: cn=UserA,c=US


secUUID: 1034....3e12

secCertDN:

Standard objectclass Auxillary objectclass

Figure 18. Extending the secMap object with secPKIMap


5.A

dm

inisterin

gP

D/M

Q

Figure 19. Creating the object class

Figure 20. Creating the attributes of the secPKIMap object class

30 3.7.1

Adding secPKIMap Objects to Existing secMap ObjectsThis task can also be performed using DMT. The steps are shown in figures Figure 22 onpage 32 through Figure 24 on page 33 below. First, open the tree of objects. Then highlight aparticular secMap object to be updated, and click the Add auxiliary class button (Figure 22on page 32). You can also find a particular object using the Search capability of DMT, using

the DN of the Policy Director user as the search key for the secDN attribute in the tree ofsecMap objects. Highlight secPKIMap in the list of available auxiliary classes. Finally, editthe secMap object entry (Figure 24 on page 33), entering the secCertDN that matches theDN of the certificate for this Policy Director user.

Figure 21. Adding secAuthority and secCertSerialNumber as optional attributes


5.A

dm

inisterin

gP

D/M

Q

Figure 22. Browsing the tree of existing secMap objects

Figure 23. Attaching a secPKIMap object to an existing secMap object

32 3.7.1

Defining and Attaching Policy TemplatesThe namespace configured in PD/MQ represents the protected queues, which are resourcescreated by MQSeries. Policy templates can be defined and attached to these queues. POP isused to specify the quality of protection required on messages flowing through these queuesas well as the audit level. In addition, Policy Director ACL permission bits are also used tospecify who can put messages to and get messages from a queue.

Authorization policy templates can be defined and applied using Policy Director. See theTivoli SecureWay Policy Director Base: Administration Guide 3.7.1 for further informationon defining policy templates.

Specifying Authorization for PD/MQ OperationsPD/MQ relies upon the Policy Director ACLs to specify the following permission bits onMQSeries queues:

¶ E - Represents authority to enqueue messages on a given queue object; it authorizes anentity to call the MQPUT API on the queue.

¶ D - Represents authority to dequeue messages on a given queue object; it authorizes anentity to call the MQGET API on the queue.

These permissions are PD/MQ specific. They are prefaced by PDMQ in the console and thepdadmin command.

Figure 24. Updating the secPKIMap object with the certificate data for this Policy Director user


5.A

dm

inisterin

gP

D/M

Q

ACLs can be placed on queues, queue managers, or on the /PDMQ/Queues object.

Specifying the PD/MQ Protected Object Policy (POP)Quality of protection (QOP) defines how messages are cryptographically protected. POPdefines these QOP attributes:

¶ integrity - Represents INTEGRITY PROTECTION on all messages using this queue.

¶ privacy - Represents PRIVACY PROTECTION on all messages using this queue.

¶ no - Represents NO CRYPTOGRAPHIC PROTECTION on messages associated withthis queue. Asserting this bit does not, in any way, circumvent authorization enforcementon queue operations. NO CRYPTOGRAPHIC PROTECTION is appropriate forMQSeries queues.

In addition, POP specifies the audit level at all or none.

If you do not want any cryptographic protection, explicitly specify this by selecting a POPof no. If a queue in the Protected Object Space does not have a POP specified, all messagessent to that queue are integrity protected by default.

For ACL entries that specify privacy, you must also list queue recipients as extendedattributes of the queue in the Protected Object Space. This information is needed so PD/MQcan find the proper encryption keys for the recipients. If the PD/MQ configuration data doesnot have the correct recipient names listed, intended recipients are not able to read themessage (because they are not able to decrypt it), in spite of having the right permissions toread messages off the queue.

Successfully sending a message and having it received depends on:

¶ The sender being authorized to put the message on the queue, and being able tocorrectly protect the message (as specified in the QOP)

¶ The recipient being authorized to receive the message and correctly validate (andoptionally decrypt) the message

ACL Evaluation and Queue Name ResolutionPD/MQ evaluates ACLs based on the target queue for any MQPUT, MQOPEN, andMQGET operations. When an application specifies a queue manager and queue namecombination on a call to MQOPEN, PD/MQ might resolve the queue manager/queue namepair to the destination queue manager/queue name pair. This is controlled by theQname-resolution attribute associated with the /PDMQ object. If the Qname-resolutionattribute is set to local, PD/MQ uses the given queue manager/queue name pair. If theQname-resolution attribute is set to remote, PD/MQ resolves the queue manager/queuename pair to the destination queue manager/queue name pair.

Creating a PD/MQ Login ContextMQSeries application users using PD/MQ need to create a login context with their PKIidentity.

Note: The user identity for each application is derived from the configuration file map.confand is used to log in to the PKI environment.

34 3.7.1

PD/MQ picks up the user identity for each application from the map.conf configuration file(username and path to stash file) and logs into the PKI environment.

Additionally, on Windows NT, PD/MQ supports interactive login. Make sure that JavaRuntime is in the path. The user is required to enter or select the key database file andpassword for the file. If the filename and password are correct, the user is prompted toselect a certificate fromm the key database file and to enter the required duration of the usercontext. If the user cancels or fails the login, PD/MQ uses the information from themap.conf file to create a login context. For daemon applications, PD/MQ uses the PKIidentity specified in the PD/MQ configuration.

A successful PKI login creates a PKI login context for the MQSeries application usingPD/MQ. If the login fails, all subsequent operations on the MQSeries queue areunauthorized. Thus, PD/MQ allows only authenticated users to use MQSeries applications.

Note: PD/MQ will not issue any warnings if an application sends a message to a queueusing an expired certificate. However the recipient will be unable to retrieve themessage from the queue, and the message will be placed on the error queue.

A PD/MQ ScenarioThe use of PD/MQ authorization policy with MQSeries messages can be further elucidatedby a scenario. Note that the following scenario depicts the behavior exhibited in this release.For example, a user John on host tarzan, is using the queue manager TARZAN.QM andJane on host homer is using HOMER.QM as the queue manager.

John uses the remote queue OUT.HOMER.QUEUE (for MQPUT) and local queueIN.HOMER.QUEUE (for MQGET) to communicate with homer. Jane uses remote queueOUT.TARZAN.QUEUE (for MQPUT) and IN.TARZAN.QUEUE (for MQGET) tocommunicate with tarzan. Both users list each other as recipients for their messages.

Create the following ACLs:

acl-to-john

Jane PDMQ:E

John PDMQ:D

acl-to-jane

Jane PDMQ:D

John PDMQ:E

Next, create POP of msg-encr with a QOP set to privacy. Update the extended attributeQ-recipients to specify the DN of John as a recipient the queues OUT.TARZAN.QUEUEand IN.HOMER.QUEUE.

Attach the ACLs and POP as follows:

/PDMQ/Queue/HOMER.QM/IN.HOMER.QUEUE


5.A

dm

inisterin

gP

D/M

Q

acl-to-john This gives Jane thepermission to sendmessages to this queue andJohn the authority to getmessages from the queue.Attaching the POP ofmsg-encr ensures that allmessages sent to the queuewill be encrypted. TheQ-recipients attribute listsfor whom the messages willbe encrypted.

POP msg-encr

/PDMQ/Queue/TARZAN.QM/IN.TARZAN.QUEUE

acl-to-jane This gives John thepermission to sendmessages to this queue andJane the authority to getmessages from the queue.Since there is no POPassociated with the queue,messages are integrityprotected, and no auditrecords are generated.

POP none

In the first scenario, John sends a message to Jane on OUT.HOMER.QUEUE. PD/MQresolves OUT.HOMER.QUEUE to IN.TARZAN.QUEUE.

The ACL permits John to write to the remote queue. John sends the message without anyprivacy or integrity protection because the target queue for recipient Jane does not requireany cryptographic message protection on incoming messages. The quality of protectionrequirements are met. PD/MQ forwards the message to Jane’s application. Jane can readJohn’s message.

Now, let us consider the case where Jane sends messages to John onOUT.TARZAN.QUEUE. PD/MQ resolves OUT.TARZAN.QUEUE to IN.HOMER.QUEUE.

Jane has permission to enqueue messages on the remote queue. PD/MQ does not forward anincoming message to John’s application unless it is privacy protected. This implies integritytoo. On Jane’s end, PD/MQ digitally signs the message and also sends Jane’s certificatealong with the message. Because John mandates confidentiality on incoming messages,Jane’s message is encrypted before being sent so that only John can read it (assuming ofcourse that only John has been made the recipient). John must be listed in the recipient listin the extended attributes.

36 3.7.1

MQSeries Considerations

PD/MQ Interaction with MQSeries AuthorizationThe authorization applied by PD/MQ does not replace the authorization applied byMQSeries itself, but rather enhances it. Access to protected queues is first checked byPD/MQ, and if granted by PD/MQ, is then checked by the Queue Manager. Thus, MQSeriesadministrators assign permissions to queues both through PD/MQ and MQSeries to ensurethat a protected queue can be accessed. Assigning permissions locally to MQSeries queues(by using the SETMQAUT command) is described in the MQSeries Systems Administrationmanual, which is available at http://www-4.ibm.com/software/ts/mqseries/library/manualsa/

Resetting PD/MQ after applying service fixes to MQSeriesTo provide authorization and data protection to messages, PD/MQ relocates the MQI sharedlibrary supplied with MQSeries and replaces it with a PD/MQ specific version of the MQIshared library. This relocation is done by running the mvlib command. Before applying aservice fix to MQSeries, run mvlib -unconfig. After the service fix has been applied toMQSeries, run mvlib -config to restore the PD/MQ version of the MQI shared library.

PD/MQ and Maximum Message SizesOne of the attributes an MQSeries administrator can set on a queue (or queue manager) isthe MaxMsgLength. This is the longest physical length message that can be put on a queue.Since PD/MQ increases the size of messages (by adding a secure encapsulation to themessage), it is possible that a PD/MQ encapsulated message may exceed the MaxMsgLengthlimit, and cause a message to be rejected with a return code ofMQRC_MSG_TOO_BIG_FOR_Q or MQRC_MSG_TOO_BIG_FOR_Q_MGR. To addressthis, MQSeries administrators should increase the value of MaxMsgLength.

Unsupported MQSeries ConfigurationsPD/MQ Version 3.7.1 does not support the following MQSeries configuration options:

¶ Channel conversion

¶ Cluster workload balance queues

¶ Use of Message Reference Header messages (MQRMH)

¶ Use of non-threadsafe MQI libraries

6


6.M

QS

eriesC

on

sideratio

ns

38 3.7.1

PD/MQ Error Handling

The PD/MQ Error Handling QueuePD/MQ routes any invalid messages received to an error handling queue. Invalid messagesare those with one or more of the following conditions:

¶ Sender did not have the authority to write to the queue

¶ The sender’s certificate was invalid

¶ A policy mismatch (sender used integrity instead of privacy, used wrong algorithm)occurs.

¶ A message is sent without PD/MQ encapsulation from a regular MQSeries machine.

Note: PD/MQ will not issue any warnings if an application sends a message to a queueusing an expired certificate. However the recipient will be unable to retrieve themessage from the queue, and the message will be placed on the error queue.

You must define your own error queue using MQSeries. If you do not define a custom errorqueue, the error messaging system will not function. After this is done, all invalid messagesare delivered to your custom-defined error queue.

You must also configure PD/MQ to route invalid messages to the error queue by runningpdmqcfg.

When PD/MQ sends a message to the error handling queue, PD/MQ returnsMQCC_WARNING (return code) and MQRC_SUPPRESSED_BY_EXIT (reason code).

pdmqdlh dlqutil Utilitydlqutil is an interactive utility that lets MQSeries administrators examine messages thatPD/MQ places on the error handling queue. An administrator can either browse all messagesor search for a particular message based on the following criteria:

¶ Reason code

¶ Queue Manager and Queue Name the message was sent to

¶ Application Name, Application Put Date, Application Put Time

When you select a message on the PD/MQ error handling queue, you can display themessage (including the reason why PD/MQ put the message on the queue) or copy themessage to a file.

7


7.P

D/M

QE

rror

Han

dlin

g

40 3.7.1

Auditing PD/MQ

Policy Director lets administrators specify what level of auditing is to be recorded for accessto a resource. The audit level is specified in the POP, and can be set to all, none, permit,deny, error and admin. PD/MQ currently supports all or none. Setting any of the audit flagsin the POP turns on auditing for that resource.

If auditing is specified, PD/MQ puts audit records into a file in a PD/MQ directory. On NT,this directory is <InstallPath>\PDMQ\log. On Solaris and AIX, this directory is/opt/pdmq/log. PD/MQ generates one audit file per process that calls into MQSeries; the filename is <program_year–month–date–hour–min–sec_pid>.audit, where program is the nameof the program producing the audit trail, year–month–date–hour–min–sec is the time stamp,and pid is the process id of the process id of the process producing the audit trail.

PD/MQ administrators can turn on the auditing by setting the audit level in POP to all andlogaudit = yes in the pdmqazn.conf file. Similarly, to completely turn off the auditing,audit level in POP needs to be set to none, and logaudit = no in the pdmqazn.conf file.

The file itself contains a set of XML style entries. The following is a sample entry from anMQGET:<event rev="1.0">>date>2000-05-23-01:10:46.922I------</date><outcome status="0">0</outcome><originator blade="pdmq"><component rev="1.1">pdmq</component><action>0</action></Event id><location>bart</location><!-Hostname></originator><accessor name="administrator"><principal auth="LDAP_V3.0">test guy</principal></accessor><target resource ="5"><object>/MessageSeal/Queue/QueueName</object></target><data></data><data tag="action">get</data><data tag="operation">D</data><data tag="result">get call successful</data><data tag="prot-operation">sign only</data><data tag="sign-algorithm">default</data><data tag="encode-algorithm">default</data><data tag="originator">/C=us/O=tivoli/CN=test guy</data><data tag="MsgId">000000000000000000000000000000000000000000000000</data><data tag="MsgFormat>MQSTR</data></data><data></data></event>

8


8.A

ud

iting

PD

/MQ

42 3.7.1

Index

Special Characters/PDMQ/Queue queue manager 16

AACL 33ACL evaluation 34AIX

PD/MQ installation on 11auditing 41authorization for PD/MQ operations 33

CCA certificate, receiving 19certificate, application 26certificate, end-user 26certificate, receiving 24Certificate Authority

Entrust Web Connector 4iPlanet CMS 4Tivoli PKI 4

certificate request, creating 21compatibility, product 2creating a signed certificate request 17creating certificate request 21

Ddequeue authority 33dlqutil 39

Eenqueue authority 33environment variables

notation for viierror handling 39Error-handling-Q 16error handling queue 39evaluation, ACL 34

Ggsk4ikm 17GSKIT 4

IIBM SecureWay Directory Server 3iKeyman 17installation prerequisites, PD/MQ 9integrity 34

KKey Database File 17

LLDAP

directory 3login, PD/MQ 34

Mmaximum message size 37MaxMsgLength 37migration 5

AIX 6Solaris 5Windows NT 6

mq2pd 15MQSeries

adding objects to Policy Director 15MQSeries authorization 37MQSeries Library, relocating 13MQSeries resources 15MQSeries service 37mvlib 13

NNetscape Directory Server 3


Ind

ex

PPD/MQ

authorizing PD/MQ operations 33error handling 39installation on AIX 11installation on Solaris 7 10installation on Windows NT 12installation prerequisites 9login 34user identities 26using 15

PD/MQ components 2PD/MQ dependencies 2PD/MQ functions 1pdadmin 16pdmqazn.conf 14pdmqazn.conf.in 14pdmqcfg 13pdmqdlh 39pdmqsniff 14Peer Logic Directory Server 3PKI identities 17Policy Director 3

adding MQSeries objects 15components 4

policy templates, defining 33POP 34privacy 34Protected Object Policy 34Protected Object Space 13Public Key Infrastructure 4

QQOP 34Quality of Protection 34

Ssigned certificate request, creating 17Solaris

PD/MQ installation on 10svrsslcfg 14

Uuser identities, PD/MQ 26user registry 3

Vvariables

environment variablesnotation for vii

WWindows NT

PD/MQ installation on 12

44 3.7.1