pathwai™ secure for websphere mq pr ... -...

Programmer’s GuidePathWAI™ Secure for WebSphere MQ

Version 300

GC32-9344-00

January 2003

Candle Corporation100 North Sepulveda Blvd.

El Segundo, California 90245

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

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.

Contents 3

List of Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

What’s New . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Chapter 1. Introducing PathWAI Secure . . . . . . . . . . . . . . . . . . . . . . . . . . . 17What is PathWAI Secure? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18What is Public Key Cryptography? . . . . . . . . . . . . . . . . . . . . . . . . . . 20How Does PathWAI Secure Work? . . . . . . . . . . . . . . . . . . . . . . . . . . 27

Chapter 2. The COBOL API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31Building COBOL/370 Programs with the PathWAI Secure API . . . . . 33Direct Subroutines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35Integrated Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Chapter 3. The C/C++ API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59Developing Applications with the C/C++ API. . . . . . . . . . . . . . . . . . 61Direct Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Integrated Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Chapter 4. The Java API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111Developing Java Applications with the PathWAI Secure API . . . . . . 113MQSecureEnvironment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115MQSecure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Contents


Appendixes

Appendix A. Messages and Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . 129PathWAI Secure Messages and Return Codes . . . . . . . . . . . . . . . . . 130BSAFE Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144COBOL API and Administration Reason Codes . . . . . . . . . . . . . . . 154User Key Database Reason Codes. . . . . . . . . . . . . . . . . . . . . . . . . . 156

Appendix B. Calculating Length of the PathWAI Secure Security Trailer . . . 157

Appendix C. Guide to Candle Customer Support . . . . . . . . . . . . . . . . . . . . 159Base Maintenance Plan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160Enhanced Support Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164Customer Support Contact Information. . . . . . . . . . . . . . . . . . . . . . 166

Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

List of Figures 5

FIGURE 1. Symmetric and Asymmetric Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . 20FIGURE 2. Encrypting and Decrypting a Message with Public/Private Keys. . . . . 22FIGURE 3. Digital Certificate. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23FIGURE 4. Using a Digital Envelope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

List of Figures

Preface 7

Preface

This guide documents the APIs that enable you to implement PathWAI™ Secure for WebSphere MQ ’s security services on an application-to-application basis. It provides the information you need to create or modify applications to use the services of PathWAI Secure to secure messages traveling over MQSeries networks.

Who should read this book?This guide is intended for system programmers and application developers who have a working knowledge of WebSphere MQ, but little or no PathWAI Secure experience. It assumes that WebSphere MQ is already installed, configured, and running.

How this book is organizedn Chapter 1 provides a brief introduction to PathWAI Secure. It covers the

functions of PathWAI Secure, the security services it offers, a high-level view of public key cryptography, and the methods of implementing application-to-application security.

n Chapter 2 documents the COBOL API syntax, parameters, and return codes.

n Chapter 3 documents the C/C++ API syntax, parameters, and return codes.

n Chapter 4 documents the Java API.

n Appendix A lists PathWAI Secure messages and return codes, RSA BSAFE return codes, and KMFREAD return codes.

P


n Appendix B provides guidelines for calculating the length of the MQSecure security trailer.

n Appendix C provides information on contacting Candle Customer Support.

Where to find more informationFor more information about PathWAI Secure, consult the PathWAI Secure Administrator’s Guide.

For more information on defining WebSphere MQ channels, consult your WebSphere MQ documentation.

We would like to hear from youCandle 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 [email protected]. Please include "PathWAI Secure for WebSphere MQ Programmer’s Guide, Version 300" in the subject line.

Ordering additional product documentationTo order additional product manuals, contact your Candle Support Services representative.

Printing this bookCandle 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.

Preface 9

3. On the Print pop-up, select one of the Print Range options forn a single pagen a range of pagesn 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.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 11

Restrictions

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

R


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.

What’s New 13

What’s New

PathWAI Secure for WebSphere MQ Version 300 introduces support for

n offset-based range encryption

n multi-threading environments

n extraction of message content and signatures for auditing purposes

n symmetric key reuse for application-to-application encryption

n asymmetric (public/private) key caching

The following sections detail the new API functions and changes to existing functions that implement this support. For information about new key management features, please see the “What’s New” section of the PathWAI™ Secure for WebSphere MQ Administrator’s Guide.

Note: These features are not supported by the COBOL API.

Offset-based range encryptionPathWAI Secure for WebSphere MQ Version 300 allows you to encrypt portions of messages based on offset and length as well as delimiters. This is particularly useful if you are using XML-defined messages or are reformatting messages and you do not want to introduce delimiters.

A set of new direct API calls perform the same functions as existing calls, but allow you to specify the offset and length of the portion or portions of the data to be encrypted:

n MQS_EncryptAtOffsets

n MQS_EncryptThenSignAtOffsets

W


n MQS_SignThenEncryptAtOffsets

n MQS_AnalyzeAtOffsets

MQSS_ARGS, the structure passed to the S_MQPUT and S_MQGET integrated API calls, has been modified to accommodate specification of a pointer to an array of offset/length pairs representing the ranges of message text to be encrypted.

Range encryption is not supported by the Java API.

MultithreadingYou can now execute PathWAI Secure API calls safely in a threaded environment. Version 300 introduces API calls that allocate storage in a thread-safe manner and clean up storage when all other PathWAI Secure calls have executed.

In the C/C++ API, there are two new direct API calls, MQS_CreateAPIContext and MQS_DestroyAPIContext and two corresponding integrated calls, S_MQCreateAPIContext and S_MQDestroyContext.

In Java, the context structure is established automatically by the PathWAI Secure class constructor.

Audit support PathWAI Secure V300 introduces several new calls which allow programmers to extract from the PathWAI Secure security trailer the information needed to counter future attempts to repudiate the message: the signature, the signer’s public key, the supporting certificate if included with the message, the encrypted symmetric key. This information can then be archived along with the message to create an audit trail.

Audit support is not available with the Java and COBOL APIs.

Symmetric key reusePathWAI Secure V300 lets you implement symmetric key reuse on an application-to-application as well as channel-to-channel basis.

What’s New 15

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.

In C/C++, symmetric key reuse is specified in the context structure MQS_APICONTEXT created by MQS_Create APIContext. In Java, it is controlled by static member variables of the MQSecureEnvironment class.

Key cachingPreviously available only with channel exits, key caching is now available on an application-to-application basis with the new MQS_CreateAPIContext call (C/C++) or the MQSecureEnvironment class (Java). Instead of accessing the user key database each time a key is required for an authentication or encryption operation, PathWAI Secure caches the key at first access 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.

Introducing PathWAI Secure 17

Introducing PathWAI Secure

OverviewThis chapter introduces PathWAI Secure, a suite of software tools that provide encryption and authentication for messages traveling over MQSeries networks. It also discusses public key cryptography and describes how PathWAI Secure implements it.

Chapter ContentsWhat is PathWAI Secure? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

What does PathWAI Secure do? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18Why secure messages? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18What security services does PathWAI Secure provide? . . . . . . . . . . . . 18How are PathWAI Secure services invoked? . . . . . . . . . . . . . . . . . . . . 19What type of encryption does PathWAI Secure use? . . . . . . . . . . . . . . 19What type of key management does PathWAI Secure provide? . . . . . 19

What is Public Key Cryptography? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Public/private keys pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20Digital certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21Digital envelopes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22Applications of public key cryptography . . . . . . . . . . . . . . . . . . . . . . . 25

How Does PathWAI Secure Work? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Securing messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27Managing users and user keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

1

What is PathWAI Secure?



What does PathWAI Secure do?PathWAI Secure provides authentication and encryption services for messages traveling over WebSphere MQ or CandleNet eBusiness Platform 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 UNIXand 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 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 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 pairsCentral 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 pairn Private key held only by ownern Public key distributed to everyone who

needs to communicate with owner

Private

Public



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 22).

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 certificatesDigital 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

Digital envelopesThe 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.

Sender encrypts message using receiver’s public key, obtained from repository.

Receiver decrypts message using private key, stored locally

Public key repository



FIGURE 3. Digital Certificate

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 24).

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.

CertificateNameSerial Number

Date



FIGURE 4. Using a Digital Envelope

Message text is encrypted using symmetric key to produce ciphertext

The symmetric key and the ciphertext are then encrypted using the receiver’s public key to produce a digital envelope

+message text

ciphertext

ciphertext

digital envelope

+

Digital envelope is “opened” using the receiver’s private key

The ciphertext is decrypted using the symmetric key

+

message text

ciphertext

ciphertext

digital envelope

+

Opening a digital envelope

Creating a digital envelope



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 21).

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 messagesPathWAI 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 keysPathWAI 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.

The COBOL API 31

The COBOL API

OverviewThis chapter documents the PathWAI Secure API subroutines used by COBOL/370 programs.

Chapter contentsBuilding COBOL/370 Programs with the PathWAI Secure API . . . . . . . . . 33

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Templates and samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33Calculating length of the PathWAI Secure security trailer. . . . . . . . . . . 33Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Direct Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35MQSANLY: Verify signature/decrypt message . . . . . . . . . . . . . . . . . . . 35MQSANLYA: Verify signature/decrypt message with multiple trailers . . 37MQSANLYM: Verify signature/decrypt message, multiple . . . . . . . . . . 39MQSENCR: Encrypt message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41MQSEANDS: Encrypt then sign a message. . . . . . . . . . . . . . . . . . . . . 43MQSERRM: Error message helper . . . . . . . . . . . . . . . . . . . . . . . . . . . 45MQSGETT: Get Trailer information . . . . . . . . . . . . . . . . . . . . . . . . . . 46MQSSIGN: Sign message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47MQSSANDE: Sign then encrypt a message . . . . . . . . . . . . . . . . . . . . 48

2


Integrated Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50SMQPUT: Secure MQPUT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51SMQGET: Secure MQGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53SMQERRM: Error Message Helper . . . . . . . . . . . . . . . . . . . . . . . . . . . 55SMQVERS: Version helper function . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57SEC-ARGS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57PathWAI Secure Get Trailer Info buffer . . . . . . . . . . . . . . . . . . . . . . . . 58

The COBOL API 33

Building COBOL/370 Programs with the PathWAI Secure API


OverviewCalls to the PathWAI Secure COBOL API invoke an LE/370 stub that bridges to a set of underlying functions common to all of the supported PathWAI Secure APIs.

PrerequisitesThe PathWAI Secure COBOL API requires that the LE/370 Version 2.4 or later build and run-time libraries are installed.

Templates and samplesJCL templates that may be used for the compile, pre-link, and link steps when creating an PathWAI Secure COBOL application are provided in the installed hilev.TMFSAMP library.

The hilev.TMFSAMP(COBSAPI) member contains examples of all PathWAI Secure COBOL API calls and the data structures containing the arguments required for those calls.

n Use the hilev.TMFSAMP(COBSCMP) member customized for your installation to compile the PathWAI Secure COBOL source.

n Use the hilev.TMFSAMP(PLNKSAMP) member customized for your installation to pre-link using the output from the compile step.

n Use the hilev.TMFSAMP(LNKSAMP) member customized for your installation to link the application load module using the output from the pre-link step.

Calculating length of the PathWAI Secure security trailerIn languages like C and C++ where storage for the output buffer is allocated programmatically, you need to determine the length of the PathWAI Secure security trailer to allocate the output buffer for cryptographic operations. The length of PathWAI Secure trailers depends on a number of different factors, including number of cryptographic operations, asymmetric key size, number of recipients, and number of embedded certificates. “ Calculating Length of



the PathWAI Secure Security Trailer” on page 157 provides guidelines for calculating the size of the required buffer.

Error handlingApplications must handle errors returned as a result of the failure of authentication and encryption operations. 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 (see “Messages and Return Codes” on page 129).

The COBOL API 35

Direct Subroutines

Direct Subroutines

MQSANLY: Verify signature/decrypt messageMQSANLY analyzes the digital signature to verify it and/or decrypts the messages, as necessary.

These functions are implemented in the MQSANLY routine:

n The input message is searched for a security trailer.

n If no security trailer is found, an error code is returned. Otherwise, the trailer is analyzed.

– If the trailer indicates that the message bears a digital signature, PathWAI Secure retrieves the public key of the sender (whose identity is available in the trailer) and verifies the signature.

– If this verification succeeds, PathWAI Secure returns the message in the buffer supplied by the caller.

– If the trailer indicates that the message (or parts of the message) is encrypted, PathWAI Secure retrieves the private key of the user invoking MQSANLY (based on the password supplied as the argument call), decrypts the symmetric key obtained from the security trailer, decrypts the body of the message using the symmetric key, and returns the new message in the buffer supplied by the caller.

Syntax

CALL ‘MQSANLY’ USING PASSWD,MESSAGE-DATA,DATA-LENGTH,OMSGBUFFER,OMSGLENGTH,REASON

Direct Subroutines


Parameters

Parameter Picture Description

PASSWD X(20) Password associated with the user ID to which the message is destined. This is used only for decryption.

MESSAGE-DATA

X(nnnn) Message to be analyzed

DATA-LENGTH

S9(9) BINARY Length of message to be analyzed

OMSGBUFFER

X(nnnn) Output buffer for processed message

OMSGLENGTH

S9(9) BINARY On entry contains size of OMSGBUFFER. On return MQSANLY updates this field with the actual size of the processed message.

REASON S9(9) BINARY On return contains 0 if operation was successful, otherwise contains reason code for failure.

The COBOL API 37

Direct Subroutines

MQSANLYA: Verify signature/decrypt message with multiple trailersThis routine is used for messages that may be both signed and encrypted.

These functions are implemented in the MQSANLYA routine:


n The message is further processed (verified or decrypted) based on the information in this trailer.


– If the trailer indicates that the message bears a digital signature, PathWAI Secure retrieves the public key of the sender (whose identity is taken from the trailer) and verifies the signature.

– If the trailer indicates that the message (or parts of the message) is encrypted, PathWAI Secure retrieves the private key of the receiver using the password supplied as argument call, then decrypts the symmetric key obtained from the security trailer, and decrypts the body of the message using the symmetic key. MQSANYLA processes messages that have been encrypted for multiple destinations, that is, it performs the functions of the MQSANYLM function if it encounters the appropriate security trailer.

– Continues analyzing trailers until the number of trailers indicated by the numTrailers parameter has been analyzed or an error is encountered.

– If processing succeeds, PathWAI Secure returns the message in the buffer supplied by the caller.

Syntax

CALL ‘MQSANLYA’ USING USERID,PASSWD,MESSAGE-DATA,DATA-LENGTH,OMSGBUFFER,OMSGLENGTH,NUMTRAILERS,REASON

Direct Subroutines


Parameters


USERID X(48) User ID for which this message was encrypted. This parameter’s value is only necessary if a group of user IDs was encrypted for (that is, an asterisk was the last character of the destination user ID on encryption). Otherwise, the parameter should be set to binary zeroes.


MESSAGE-DATA X(nnnn) Message to be analyzed

DATA-LENGTH S9(9) BINARY Length of message to be analyzed

OMSGBUFFER X(nnnn) Output buffer for processed message

OMSGLENGTH S9(9) BINARY On entry contains size of OMSGBUFFER. On return MQSANLY updates this field with the actual size of the processed message.

NUMTRAILERS S9(9) BINARY Number of security trailers that this routine anlayzes. Each trailer represents a signature or encryption or encryption operation on the message.


The COBOL API 39

Direct Subroutines

MQSANLYM: Verify signature/decrypt message, multipleMQSANLYM is used for messages that may be signed and encrypted and are sent to an WebSphere MQ cluster.

These functions are implemented in the MQSANLYM routine:


n The message is further processed (verified and/or decrypted) based on the information in this trailer.


n If the trailer indicates that the message bears a digital signature, PathWAI Secure retrieves the public key of the sender (whose identity is taken from the trailer) and verifies the signature.

n The trailer may contain one or more public-key-encrypted symmetric keys, one for each user targetted by the sender. When a match between the user supplied as an input parameter and one of the user names in these sections is found, the symmetric key is exposed using that user’s private key based on the parameter supplied password. The message contents can then be decrypted using the exposed symmetric key.

– If the trailer indicates that the message (or parts of the message) is encrypted, PathWAI Secure retrieves the private key of the destined user using the password supplied as argument call, decrypts the symmetric key obtained from the security trailer, then decrypts the body of the message using the symmetric key.

– Continues analyzing trailers until the number of trailers indicated by the numTrailers parameter below has been analyzed, or an error is encountered.


MQSANLYM is compatible with MQSANLY as it also processes messages encrypted for a single user and signed messages (that is, messages do not necessarily have to be encrypted for multiple destinations to allow processing to be successful). Candle recommends that you use MQSANLYM in place of MQSANLY to avoid application coding changes in the future.

Direct Subroutines


Syntax

CALL ‘MQSANLYM’ USING USERID,PASSWD,MESSAGE-DATA,DATA-LENGTH,OMSGBUFFER,OMSGLENGTH,REASON

Parameters


USERID X(48) User ID for which this message was encrypted. This parameter’s value is only necessary if a group of user IDs was encrypted for (that is, an asterisk was the last character of the destination user ID on encryption). Otherwise, the parameter should be set to binary zeroes.




OMSGBUFFER X(nnnn) Output buffer for processed message

OMSGLENGTH S9(9) BINARY. On entry contains size of OMSGBUFFER. On return MQSANLY updates this field with the actual size of the processed message.


The COBOL API 41

Direct Subroutines

MQSENCR: Encrypt messageMQSENCR enables an application to encrypt all or parts of a message.

In many situations, only certain fields in the body of the message, for example fields identifying account numbers, are sensitive enough to require encryption. An application is able to specify a sequence of bytes to indicate which fields need encryption by enclosing them between special characters (delimiters) that are passed to the encryption routine.

After the encryption is complete, the symmetric key used for the encryption is sent with the message. Note that this secret key bears no relationship to the RSA private key.

The symmetric key is encrypted, using the public key of the user ID to which the message is directed on the target system. The result is placed in the security trailer. This trailer is appended to the end of the encrypted message, which is then returned to the caller.

Syntax

CALL ‘MQSENCR’ USING DESTID,MESSAGE-TEXT,SMSGLENGTH,MSGBUFFER,MSGLENGTH,LDELIM,RDELIM,REASON-CODE

Parameters

Parameters Picture Description

DESTID X(48) User ID for which this message was encrypted

MESSAGE-DATA X(nnnn) Message to be encrypted

DATA-LENGTH S9(9) BINARY Length of message to be encrypted

OMSGBUFFER X(nnnn) Output buffer for encrypted message

Direct Subroutines


OMSGLENGTH S9(9) BINARY On entry contains size of OMSGBUFFER. On return MQSENCR updates this field with the actual size of the encrypted message.

LDELIM X(10) String indicator to be used as the left delimiter for range encryption. For full encryption, set this field to blank.

RDELIM X(10) String indicator to be used as the right delimiter for range encryption. For full encryption, set this field to blank.



The COBOL API 43

Direct Subroutines

MQSEANDS: Encrypt then sign a messageMQSEANDS enables an application to encrypt all or parts of a message and then sign the result.

In many situations, only certain fields in the body of the message, perhaps fields identifying account numbers, are sensitive enough to require encryption. An application is able to specify a sequence of bytes to indicate which fields need encryption by enclosing them between special characters (delimiters) that are passed to the encryption routine.

After the encryption is complete, the symmetric key used for the encryption is itself encrypted, using the public key of the target system. The result is placed in the security trailer and the trailer is appended to the end of the encrypted message.

The message is then signed, using the private key of the sender, and returned to the caller.

Syntax

CALL ‘MQSEANDS’ USING USERID,PASSWD,DESTID,MESSAGE-TEXT,SMSGLENGTH,MSGBUFFERMSGLENGTH,LDELIM,RDELIM,REASON-CODE

Parameters


USERID X(48) User ID of the person signing this message

PASSWD X(20) Password of the user signing this message

Direct Subroutines


DESTID X(48) User ID for which this message is being encrypted


DATA-LENGTH S9(9) BINARY Length of message to be encrypted

OMSGBUFFER X(nnnn) Output buffer for encrypted message

OMSGLENGTH S9(9) BINARY On entry, contains size of OMSGBUFFER. On return, MQSENCR updates this field with the actual size of the encrypted message.


RDELIM X(10) String indicator to be used as the right delimiter for range encryption. For full encryption, set this field to blank.

REASON S9(9) BINARY On return, contains 0 if operation was successful, otherwise contains reason code for failure.


The COBOL API 45

Direct Subroutines

MQSERRM: Error message helperThe MQSERRM helper function is used to obtain more information regarding an PathWAI Secure return code.

Syntax

CALL ‘MQSERRM’ USING REASON-CODE,MESSAGE-DATA,DATA-LENGTH

Parameters


REASON-CODE S9(9) BINARY Contains a reason code returned by an API call (PathWAI Secure and/or WebSphere MQ)

MESSAGE-DATA X(nnnn), where nnnn ≥ 80

An area that the error message character string is returned. This area must be at least 80 bytes.

DATA-LENGTH S9(9) BINARY The length of the area for the error message character string

Direct Subroutines


MQSGETT: Get Trailer information

Syntax

CALL ‘MQSGETT’ USING MESSAGE-DATA,DATA-LENGTH,TRAILER-INFO

Parameters




TRAILER-INFO Trailer information structure

The COBOL API 47

Direct Subroutines

MQSSIGN: Sign messageThe MQSSIGN subroutine is called by a program to add a digital signature at the end of the body of the message.

Syntax

CALL ‘MQSSIGN’ USING USERID,PASSWORD,MESSAGE-DATA,DATA-LENGTH,OMSGBUFFER,OMSGLENGTH,REASON-CODE

Parameters


USERID X(48) User ID of the signer

PASSWORD X(20) Password of the signer

MESSAGE-DATA X(nnnn Message to be signed

DATA-LENGTH S9(9) BINARY Length of message to be signed

OMSGBUFFER X(nnnn) Output buffer for signed message

OMSGLENGTH S9(9) BINARY On entry contains size of OMSGBUFFER. On return MQSSIGN updates this field with the actual size of the signed message.

REASON-CODE S9(9) BINARY On return contains 0 if operation was successful, otherwise contains reason code for failure

Direct Subroutines


MQSSANDE: Sign then encrypt a messageThis subroutine adds a digital signature to the message, then the signed message is encrypted and returned to the caller.

Syntax

CALL ‘MQSSANDE’ USING USERID,PASSWD,DESTID,MESSAGE-TEXT,SMSGLENGTH,MSGBUFFER,MSGLENGTH,LDELIM,RDELIM,REASON-CODE

Parameters


USERID X(48) User ID of the person signing this message

PASSWD X(20) Password of the user signing this message

DESTID X(48) User ID for which this message is being encrypted


DATA-LENGTH

S9(9) BINARY Length of message to be encrypted

OMSGBUFFER

X(nnnn) Output buffer for encrypted message

OMSGLENGTH S9(9) BINARY On entry contains size of OMSGBUFFER. On return MQSENCR updates this field with the actual size of the encrypted message.


The COBOL API 49

Direct Subroutines

RDELIM X(10 String indicator to be used as the right delimiter for range encryption. For full encryption, set this field to blank.

REASON S9(9) BINARY On return contains 0 if operation was successful, otherwise contains reason code for failure


Integrated Subroutines



OverviewThe integrated subroutines provide a secure layer on top of standard WebSphere MQ MQPUT and MQcalls. The two principal subroutines are SMQPUT and SMQGET. These subroutines use the standard WebSphere MQ MQPUT and MQGET parameters, as well as some additional PathWAI Secure parameters. PathWAI Secure also provides two helper calls, SMQVERS and S_MQERRM.

S_MQPUT calls the appropriate stand-alone PathWAI Secure API subroutines to sign and/or encrypt the message, then calls WebSphere MQ MQPUT to put the message in the queue.

S_MQGET calls WebSphere MQ MQGET to get the message, then calls the appropriate PathWAI Secure stand-alone subroutines to verify a signature and/or decrypt the message.

The COBOL API 51


SMQPUT: Secure MQPUTSMQPUT is called by a program to sign, encrypt, or sign and encrypt a message, then place the message in the WebSphere MQ queue. The input PathWAI Secure parameters indicate which security functions should be applied to the message.

PathWAI Secure parameters are specified in the SEC_ARGS data structure. For information concerning WebSphere MQ MQPUT parameters, please consult the WebSphere MQ documentation.

Syntax

CALL ‘SMQPUT’ USING SEC-ARGS,HCONN,HOBJ,MQMD, MQPMO,DATA-LENGTH,MESSAGE-DATA,COMPCODE,REASON-CODE

Parameters


SEC_ARGS PathWAI Secure API structure

HCONN Connection handle

HOBJ Object handle

MQMD Message descriptor

MQPMO MQPut options

DATA-LENGTH S9(9) BINARY Length of message to be secured put

MESSAGE-DATA X(nnnn) Message to be secured put



COMPCODE Value returned from the API call


The COBOL API 53


SMQGET: Secure MQGETSMQGET is called by a program to retrieve a message from a queue, then analyze the message trailer to verify the signature and/or decrypt the message.

PathWAI Secure parameters are specified in the SEC_ARGS data structure. For information concerning WebSphere MQ MQGET parameters, please consult the WebSphere MQ documentation.

Syntax

CALL ‘SMQGET’ USING SEC-ARGSHCONN,HOBJ,MQMD,MQGMO,DATA-LENGTH,MESSAGE-DATA,COMPCODE,REASON-CODE

Parameters


SEC_ARGS PathWAI Secure API structure

HCONN Connection handle

HOBJ Object handle

MQMD Message descriptor

MQGMO MQGet options

DATA-LENGTH S9(9) BINARY Length of a buffer to place message in. On return, SMQGET updates this field with the actual size of message.

MESSAGE-DATA X(nnnn) Returned message



COMPCODE Value returned from the API call.


The COBOL API 55


SMQERRM: Error Message HelperThe SMQERRM helper function is used to obtain more information regarding an PathWAI Secure return code.

Syntax

CALL ‘SMQERRM’ USING REASON-CODE,MESSAGE-DATA,DATA-LENGTH

Parameters


REASON-CODE S9(9) BINARY. Contains a reason code returned by an API call (PathWAI Secure and/or WebSphere MQ)

MESSAGE-DATA X(nnnn) where nnnn ≥ 80 An area that the error message character string is returned. This area must be at least 80 bytes.

DATA-LENGTH S9(9) BINARY The length of the area for the error message character string



SMQVERS: Version helper functionThe SMQVERS helper function is used to determine the version of your installed PathWAI Secure product. Typically, it is used when working with Candle support personnel.

Syntax

CALL ‘SMQVERS’ USING MESSAGE-DATA,DATA-LENGTH

Parameters


MESSAGE-DATA X(nnnn) where nnnn ≥ 80

An area where the version character string is returned. This area must be at least 80 bytes.

DATA-LENGTH

S9(9) BINARY The length of the area for the version character string

The COBOL API 57

Data Structures

Data Structures

SEC-ARGS

Information structure

10 SEC-ARGS

15 REQUEST-ID PIC S9(9) BINARY

15 USER-ID PIC X(48)

15 PASSW PIC X(48)

15 DEST-ID PIC X(48)

15 LEFT-DELIM PIC X(10)

15 RIGHT-DELIM PIC X(10)

Request Identifiers (REQUEST-ID)

Flag Picture Description

SSREQ-SIGN S9(9) BINARY VALUE 256 Perform sign message

SSREQ-SEAL S9(9) BINARY VALUE 257 Perform encrypt (FULL) message

SSREQ-ERANGE S9(9) BINARY VALUE 258 Perform encrypt (RANGE) message

SSREQ-SEAL-SIGN S9(9) BINARY VALUE 259 Perform encrypt (FULL) then sign message

SSREQ-SIGN-SEAL S9(9) BINARY VALUE 260 Perform sign then encrypt (FULL) message

SSREQ-RSEAL-SIGN S9(9) BINARY VALUE 261 Perform encrypt (RANGE) then sign message

SSREQ-SIGN-RSEAL S9(9) BINARY VALUE 262 Perform sign then encrypt (RANGE) message

Data Structures


PathWAI Secure Get Trailer Info buffer

Trailer information structure

10 TRAILER-INFO

15 TR-TYPE PIC S9(9) BINARY

15 TR-USER-ID PIC X(48)

15 TR-MD-FORMAT PIC X(8)

PathWAI Secure Trailer Types (TR-TYPE)

Type Picture Description

10 MQS-NOTRAILER S9(9) BINARY VALUE 0 No trailer detected

10 MQS-SIGNTRAILER S9(9) BINARY VALUE 1 Signed message trailer

10 MQS-ENCRYPTTRAILER S9(9) BINARY VALUE 2 Encrypted (FULL) message trailer

10 MQS-NOACTIONTRAILER S9(9) BINARY VALUE 3 No action trailer

10 MQS-RANGETRAILER S9(9) BINARY VALUE 4 Encrypted (RANGE) message trailer

The C/C++ API 59

The C/C++ API

OverviewThis chapter documents the syntax and parameters for the PathWAI Secure C/C++ API calls. It also provides information on how to implement them and discusses the difference between the direct and integrated functions.

Chapter ContentsDeveloping Applications with the C/C++ API . . . . . . . . . . . . . . . . . . . . . 61

PathWAI Secure header file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61PathWAI Secure library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Implementing security functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61Calculating length of the PathWAI Secure security trailer. . . . . . . . . . . 62Error handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Direct Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64MQS_Analyze: Verify digital signature/decrypt message . . . . . . . . . . . 65MQS_AnalyzeAll: Verify digital signature/decrypt for multiple trailers . 67MQS_AnalyzeMultiple: Verify signature/decrypt message sent to multiple destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71MQS_ComposeMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73MQS_CreateAPIContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74MQS_DecomposeMessage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76MQS_DestroyAPIContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

3


MQS_Encrypt: Encrypt message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78MQS_EncryptAtOffsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80MQS_EncryptThenSign: Encrypt message then sign the result . . . . . . 83MQS_EncryptAtOffsetsThenSign . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85MQS_ErrorMsg: Error message helper function . . . . . . . . . . . . . . . . . 87MQS_GetKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88MQS_GetTrailerInfoEx: Get information from an MQSecure trailer. . . 89MQS_RangeCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92MQS_SetLocalCCSID. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93MQS_SetMQFormat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94MQS_Sign: Sign message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95MQS_SignThenEncrypt: Add digital signature then encrypt result. . . . 96MQS_SignThenEncryptAtOffsets . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98MQS_Version: Version helper function . . . . . . . . . . . . . . . . . . . . . . . 100

Integrated Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101S_MQCreateAPIContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102S_MQDestroyAPIContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104S_MQGET—Secure MQGET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108S_MQVERSION—Version helper function . . . . . . . . . . . . . . . . . . . . 109S_MQERRORMSG—Error message helper function. . . . . . . . . . . . . 110

The C/C++ API 61

Developing Applications with the C/C++ API


PathWAI Secure header fileTo develop applications that invoke PathWAI Secure, include the header file sec_api.h in all sources issuing MQS_... calls. sec_api.h is found in the following locations:

where mqsecure is the directory where PathWAI Secure was installed.

PathWAI Secure libraryLink the program with the platform-specific library as follows:

Implementing security functionsTable 1 shows the calls that must be made to invoke various PathWAI Secure functions. For each security function implemented in a sending program, there must be a reciprocal function on the receiving end.

Windows mqsecure\samp

UNIX mqsecure/samp

OS/390 hilevdsn.TMFSAMP

Windows sec_api.lib

UNIX sec_api

OS/390 PDS (SEC@API) to be used in the prelink step

Table 1. Required Calls for PathWAI Secure Security Functions

Function Direct Call Integrated Call

Signing a message MQS_Sign S_MQPUT using SSREQ_SIGN

Authenticating a signature

MQS_Analyze

MQS_AnalyzeAll

S_MQGET



Calculating length of the PathWAI Secure security trailerIn languages like C and C++ where storage for the output buffer is allocated programmatically, you need to determine the length of the PathWAI Secure security trailer to allocate the output buffer for cryptographic operations. The length of MQSecure trailers depends on a number of different factors, including number of cryptographic operations, asymmetric key size, number of recipients, and number of embedded certificates. ‘Calculating Length of the PathWAI Secure Security Trailer” on page 157 provides guidelines for calculating the size of the required buffer.

Encrypting a message MQS_Encrypt S_MQPUT using SSREQ_SEAL

Range encrypting a message

MQS_Encrypt

MQS_EncryptAtOffsets

S_MQPUT using SSREQ_RSEAL or SSREQ_ROSEAL

Decrypting a message MQS_Analyze

MQS_AnalyzeAll

S_MQGET

Signing and encrypting a message

MQS_SignThenEncrypt

MQS_EncryptThenSign

S_MQPUT using SSREQ_SIGN_SEAL or SSREQ_SEAL_SIGN,

Signing and range encrypting a message

MQS_SignThenEncrypt

MQS_EncryptThenSign

MQS_SignThenEncryptAt Offsets

MQS_EncryptThenSignAtOffsets

S_MQPUT using SSREQ_SIGN_RSEAL, SSREQ_SIGN_ROSEAL, SSREQ_RSEAL_SIGN, or SSREQ_ROSEAL_SIGN

Authenticating and decrypting a message

MQS_AnalyzeAll S_MQGET

Utility functions MQS_ErrorMsgMQS_Version

S_MQERRORMSGS_MQVERSION

Table 1. Required Calls for PathWAI Secure Security Functions (continued)

Function Direct Call Integrated Call

The C/C++ API 63


Error handlingApplications must handle errors returned as a result of the failure of authentication and encryption operations. The MQSecure APIs return an error code that can be converted to an actual message. The application should interpret the error code and log the message (see “Messages and Return Codes” on page 129).

Direct Calls


Direct Calls

OverviewThis section discusses in some detail the direct API function calls and provides the syntax and parameters for each. (The functions are also invoked by the integrated API calls, according to the type of security specified in the parameters.)

The C/C++ API 65

Direct Calls

MQS_Analyze: Verify digital signature/decrypt message

Description

MQS_Analyze analyzes the digital signature to verify it and/or decrypts the messages, as necessary.

These functions are implemented in the MQS_Analyze routine:



– If the trailer indicates that the message bears a digital signature, PathWAI Secure retrieves the public key of the sender (whose identity is available in the trailer) and verifies the signature.

– If this verification succeeds, PathWAI Secure returns the message in the buffer supplied by the caller.

– If the trailer indicates that the message (or parts of the message) is encrypted, PathWAI Secure retrieves the private key of the user invoking MQS_Analyze (based on the password supplied as the argument call), decrypts the symmetric key obtained from the security trailer, decrypts the body of the message using the symmetric key, and returns the new message in the buffer supplied by the caller.

Syntax

int MQS_Analyze(char *passw,unsigned char *inMsg,long inLen,unsigned char *outMsg,long *outLen);

Direct Calls


Parameters

Return Codes

See “PathWAI Secure Messages and Return Codes” on page 130.

passw Password of the user ID to which the message is destined. Required only for decryption, which implies retrieval of user’s private key (password protected).

inMsg Message to be analyzed (verify digital signature or decrypt)

inLen Length of the message to be analyzed

outMsg Buffer allocated by the caller where MQS_Analyze returns the processed message. It must be allocated by the calling routine, and it should be about the same size as inMsg.

outLen I/O field. On input, the calling routine places the size of outMsg in this field. On output, MQS_Analyze returns the actual length of the processed message. If the return code is OUT_BUF_SHORT, the required size is returned in this field.

The C/C++ API 67

Direct Calls

MQS_AnalyzeAll: Verify digital signature/decrypt for multiple trailers

Description

This routine is used for messages that may be both signed and encrypted. These functions are implemented in the MQS_AnalyzeAll routine:


n The message is further processed (verified or decrypted) based on the information in this trailer.


– If the trailer indicates that the message bears a digital signature, PathWAI Secure retrieves the public key of the sender (whose identity is taken from the trailer) and verifies the signature.

– If the trailer indicates that the message (or parts of the message) is encrypted, PathWAI Secure retrieves the private key of the receiver using the password supplied as argument call, then decrypts the symmetric key obtained from the security trailer, and decrypts the body of the message using the symmetic key. MQS_AnalyzeAll processes messages that have been encrypted for multiple destinations, that is, it performs the functions of MQS_AnalyzeMultiple if it encounters the appropriate security trailer.

– Continues analyzing trailers until the number of trailers indicated by the numTrailers parameter has been analyzed or an error is encountered.


Syntax

int MQS_AnalyzeAll(char *dest_id,char *passw,unsigned char *inMsg,long inLen,unsigned char *outMsg,

Direct Calls


long *outLen;long *numTrailers);

Parameters

Return Codes


dest_id User ID to which the message is destined

passw Password associated with the user ID to which the message is destined. Required only for decryption, which implies retrieval of user’s private key (password protected).



outMsg Buffer allocated by the caller where MQS_AnalyzeAll returns the processed message. It must be allocated by the calling routine, and it should be about the same size as inMsg.

outLen I/O field. On input, the calling routine places the size of outMsg in this field. On output, MQS_AnalyzeAll returns the actual length of the processed message. If the return code is OUT_BUF_SHORT, the required size is returned in this field.

numTrailers I/O field. On input, the calling routine places the number of PathWAI Secure trailers to be analyzed. On output, MQS_AnalyzeAll returns the actual number of trailers analyzed.

The C/C++ API 69

Direct Calls

MQS_AnalyzeAtOffsets

Description

This routine performs the same functions as MQS_Analyze and MQS_AnalyzeAll, but adds three parameters: pInRanges, pOutRanges, and numRanges. If pInRanges and pOutRanges are not NULL and numRanges is not zero, they will override the use of the range structures embedded in a range-encrypted message. The function facilitates the range decryption of a transformed, range-encrypted message, such as one passing through an XML flow.

This function uses a supplied array of offset/length pairs relating to valid ranges of ciphertext and a count of these pairs.

On successful completion, the function returns an array of RANGE structures containing the offset/length pairs related to the decrypted ranges in the output buffer.

Syntax

int MQS_AnalyzeAtOffsets(char *user_id,char *passw, UCHAR *inData,long inDLen,UCHAR *outData, long *pOutDLen, long *pNumTrailers,PRANGE pInRanges,long numRanges,PRANGE pOutRanges)

Direct Calls


Parameters

dest_id User ID to which the message is destined

passw Password associated with the user ID to which the message is destined. Required only for decryption, which implies retrieval of user’s private key (password protected).

inData Message to be analyzed (verify digital signature or decrypt)

inDLen Length of the message to be analyzed

outData Buffer allocated by the caller where MQS_AnalyzeAtOffsets returns the processed message. It must be allocated by the calling routine, and it should be about the same size as inData.

outDLen I/O field. On input, the calling routine places the size of outData in this field. On output, MQS_AnalyzeAtOffsets returns the actual length of the processed message. If the return code is OUT_BUF_SHORT, the required size is returned in this field.

numTrailers I/O field. On input, the calling routine places the number of PathWAI Secure trailers to be analyzed. On output, MQS_AnalyzeAtOffsets returns the actual number of trailers analyzed.

pInRanges An array of RANGE structure containing offset/length pairs that dictate where the ciphertext ranges are embedded in inData. These ranges override any offset/length pairs in the message-embedded range structure that may be found in inData. This parameter can be NULL if no ranges exist in the message or the message-embedded ranges are to be used

Note: The offset will be applied to decryption of ranges only if a range security trailer is being processed. This allows other types of trailer to be processed in a multiple trailer message.

numRanges A long containing the number of array elements in pInRanges.

pOutRanges An array of RANGE structures to contain the offsets/length pairs related to the decrypted ranges in outData

The C/C++ API 71

Direct Calls

MQS_AnalyzeMultiple: Verify signature/decrypt message sent to multiple destinations

Description

This routine is used for messages that may be signed and encrypted and are sent to an WebSphere MQ cluster.

These functions are implemented in the MQS_AnalyzeMultiple routine:


n The message is further processed (verified and/or decrypted) based on the information in this trailer.


n If the trailer indicates that the message bears a digital signature, MQSecure retrieves the public key of the sender (whose identity is taken from the trailer) and verifies the signature.

n The trailer may contain one or more public-key-encrypted symmetric keys, one for each user targeted by the sender. When a match between the user supplied as an input parameter and one of the user names in these sections is found, the symmetric key is exposed using that user’s private key based on the supplied password. The message contents can then be decrypted using the exposed symmetric key.

– If the trailer indicates that the message (or parts of the message) is encrypted, MQSecure retrieves the private key of the destined user using the password supplied as argument call, decrypts the symmetric key obtained from the security trailer, then decrypts the body of the message using the symmetric key.

– Continues analyzing trailers until the number of trailers indicated by the numTrailers parameter below has been analyzed, or an error is encountered.

– If processing succeeds, MQSecure returns the message in the buffer supplied by the caller.

MQS_AnalyzeMultiple is compatible with MQS_Analyze as it also processes messages encrypted for a single user and signed messages (that is,

Direct Calls


messages do not necessarily have to be encrypted for multiple destinations to allow processing to be successful). Candle recommends that you use MQS_AnalyzeMultiple in place of MQS_Analyze to avoid application coding changes in the future.

Syntax

int MQS_AnalyzeMultiple(char *dest_id,char *passw,unsigned char *inMsg,long inLen,unsigned char *outMsg,long *outLen);

Parameters

dest_id User ID to which the message is destined.

passw Password of the user ID to which the message is destined.



outMsg Buffer allocated by the caller where MQS_AnalyzeMultiple will return the processed message. It must be allocated by the calling routine, and it should be about the same size as inMsg.

outLen I/O field. On input, the calling routine places the size of outMsg in this field. On output, MQS_AnalyzeMultiple returns the actual length of the processed message. If the return code is OUT_BUF_SHORT, the required size is returned in this field.

The C/C++ API 73

Direct Calls

MQS_ComposeMessage

Description

This call composes a PathWAI Secure message from from message payload and control structures and outputs a contiguous PathWAI Secure message and forms an input structure that contains pointers to the individual components that make up the entire message.

Syntax

intMQS_ComposeMessage ( PMQSS_MESSAGE_COMPONENTS pMsgComponentslong *pOutMessageLen,UCHAR *outMessage,);

Parameters

The parameters are as follows:

Return codes

pMsgComponents Pointer to a MQSS_MESSAGE_COMPONENTS structure that contains the pointers to the individual control structures and their lengths or numbers (see “MQSS_MESSAGE_COMPONENTS variables” on page 90)

pOutMessageLen Pointer to a long containing length of reconstituted MQSecure message. If the allocated output buffer is too short to accommodate the reconstituted message, the required length is returned.

outMessage Pointer to unsigned characters to contain the reconstituted MQSecure message

SUCCESS Message was reconstituted successfully

OUT_BUF_SHORT The message output area to contain the reconstituted message was too short to accommodate the output from the operation. The required length is returned in the pOutMessageLen parameter.

Direct Calls


MQS_CreateAPIContext

Description

This call establishes a context for each thread in a multi-threaded environment.

The context structure MQS_APICONTEXT provides a mechanism for:

n enabling reuse of symmetric keys

n enabling caching of asymmetric key

For exploitation in future releases, the context structure provides a mechanism for

n versioning

n issuing of debug messages to a log

If you are writing a multi-threaded program, you must use this call. Before destroying a thread after all PathWAI Secure calls have completed, you must issue MQS_DestroyAPI to clean up storage acquired for the thread.

Programs written for earlier versions of PathWAI Secure do not need to be modified to include this function. However, if you are coding new applications, even if you are not using thread-aware programs, Candle recommends that you use this call to take advantage of the considerable performance enhancements offered by key reuse and caching, and to facilitate compatibility with future releases of PathWAI Secure.

Syntax

int MQS_CreateAPIContext(MQS_APICONTEXT *pMQSAPIContext)

Parameters

*pMQSAPIContext A pointer to the structure MQS_APICONTEXT

The C/C++ API 75

Direct Calls

MQS_APICONTEXT variables

The structure MQS_APICONTEXT is defined in sec_api.h. It contains the following variables:

Variables Type Definition

Version Long Set to MQS_APICONTEXT_VERSION_1

Debug Long Enable/disable logging of debugging messages:

1 Debug

0 No debug

nKeyReusesMax Long Number of times a symmetric key is reused before a new key is generated

KeyGenerationInterval Long The amount of time (in seconds) a symmetric key is reused before a new key is generated

Direct Calls


MQS_DecomposeMessage

Description

This call takes an PathWAI Secure message, decomposes it into message payload and control structures, and returns a structure that contains pointers to the individual components that make up the entire message.

Decomposition applies to the most recent cryptographic operation applied to the message payload. If multiple cryptographic operations need to be decomposed, the output of each operation will have to be processed by the API call and, conversely, the analysis process will have to be performed cryptographic operation by cryptographic operation.

Syntax

int MQS_DecomposeMessage (UCHAR *inMessage, long inMessageLen, PMQSS_MESSAGE_COMPONENTS pMsgComponents)

Parameters

Return Codes

inMessage Pointer to unsigned characters containing PathWAI Secure message.

inMessageLen Long containing length of PathWAI Secure message

pMsgComponents Pointer to a MQSS_MESSAGE_COMPONENTS structure that will contain the pointers to the individual control structures and their lengths or numbers (see “MQSS_MESSAGE_COMPONENTS variables” on page 90)

SUCCESS Message was decomposed successfully

OUT_BUF_SHORT One or more storage areas supplied on input were too short to accommodate the output from the operation. The required length/number of sections is contained in the length/number of sections output fields.

The C/C++ API 77

Direct Calls

MQS_DestroyAPIContext

Description

Should be called after all MQSecure calls on a given thread to release storage. This function must be called if you called MQS_CreateAPIContext.

Syntax

int MQS_DestroyAPIContext(MQS_APICONTEXT *pMQSAPIContext)

Parameters

Since none of the MQS_APICONTEXT variables are relevant at this point, the input parameter is currently ignored and it is safe to pass in NULL. However, since this structure will be exploited in future releases, Candle advises that you pass an address rather than NULL.


Direct Calls


MQS_Encrypt: Encrypt message

Description

MQS_Encrypt enables an application to encrypt all or parts of a message.


After the encryption is complete, the symmetric key used for the encryption is sent with the message.

The symmetric key is encrypted, using the public key of the user ID to which the message is directed on the target system. The result is placed in the security trailer. This trailer is appended to the end of the encrypted message, which is then returned to the caller.

Syntax

int MQS_Encrypt(char *dest_id,unsigned char *inData,long inDLen,unsigned char *outData,long *outDLen,char *leftDelim,char *rightDelim);

Parameters

dest_id User ID for which this message is to be encrypted. The public key of this user ID must be registered in the user key database. This user ID’s public key is used to encrypt the message, which can only be decrypted by someone who has the corresponding private key. If the message is being sent to a WebSphere MQ cluster, the user ID may be a prefix (shared by all members of the cluster) with an appended wildcard asterisk (*).

inData Data to be encrypted

inDLen Length of the data to be encrypted

The C/C++ API 79

Direct Calls

Return codes


outData Buffer allocated by the caller where MQS_Encrypt returns the encrypted data. It must be allocated by the calling routine and should be about 200 bytes larger than inData.

outDLen I/O field. On input, the calling routine places the size of outData in this field. On output, MQS_Encrypt returns the actual length of the encrypted data, including the trailer. If the return code is OUT_BUF _SHORT, the required size is returned in this field. For range encryption, there is an extra 16-byte overhead per range.

leftDelim Character to be used as the left delimiter for range(s) of bytes encryption. Used in conjunction with rightDelim. If leftDelim and rightDelim are NULL, full encryption is performed. Otherwise, only those text portions enclosed between leftDelim and rightDelim are encrypted.

rightDelim Character to be used as the right delimiter for range(s) of bytes encryption. Used in conjunction with leftDelim. If leftDelim and rightDelim are NULL, full encryption is performed. Otherwise, only those text portions enclosed between leftDelim and rightDelim are encrypted.

Direct Calls


MQS_EncryptAtOffsets

Description

This routine performs the same functions as MQS_Encrypt, but passes an array of zero-based offset/length pairs and a count of those pairs instead of a pair of character arrays representing left and right delimiters embedded in the message text.

On successful completion, the function returns an array of RANGE structures containing the offset/length pairs related to the encrypted ranges in the output buffer.

Overlapping ranges and ranges extending beyond the boundaries of the message are not allowed. Ranges must be specified in ascending order by offset.

Syntax

int MQS_EncryptAtOffsets (char *dest_id, UCHAR *inData, long inDLen,UCHAR *outData, long *pOutDLen,PRANGE pRangeOffsetsIn,short lNumRangeOffsetsIn,PRANGE pRangeOffsetsOut)

The C/C++ API 81

Direct Calls

Parameters

dest_id User ID for which this message is to be encrypted. The public key of this user ID must be registered in the sender’s user key database. This user ID’s public key is used to encrypt the message, which can only be decrypted by someone who has the corresponding private key. If the message is being sent to a WebSphere MQ cluster, the user ID should be a prefix shared by all members of the cluster with an appended wildcard asterisk (*).



outData Buffer allocated by the caller where MQS_EncryptAtOffsets returns the encrypted data. It must be allocated by the calling routine and should be about 200 bytes larger than inData.

outDLen I/O field. On input, the calling routine places the size of outData in this field. On output, MQS_EncryptAtOffsets returns the actual length of the encrypted data, including the trailer. If the return code is OUT_BUF _SHORT, the required size is returned in this field. For range encryption, there is an extra 16-byte overhead per range.

pRangeOffsetsIn Pointer to an array of RANGE structures. Offsets are zero-based. This is an existing structure mapped in RANGE.H. Ranges of message text starting at each offset and for the length of data specified will be encrypted using the appropriate symmetric key and the resulting ciphe rtext embedded in the output message buffer at the appropriate offset.

lNumRangeOffsetsIn A short containing the count of offset/length pairs pointed to by pRangeOffsetsIn

pRangeOffsetsOut Pointer to an array of RANGE structures. This is an existing structure mapped in RANGE.H. This array contains the zero-based offsets and lengths of the ranges AFTER each range has been encrypted.

Direct Calls


Example

The example encrypts two 4-byte ranges of an input message at offset 2 and 12 bytes for a user ID input to the function EncryptARange. The output buffer will contain two blocks of ciphertext, each 4, 8, or 16 bytes long depending on the cipher used. The clear text segments will be contiguous to the ciphertext segments. This output is identical to the current output from range encryption, except that the delimiter character strings will not be present.

void EncryptARange( char *user_id) {

RANGE eRangeIn[2];RANGE eRangeOut[2];char inMessage="abcdefghijklmnopqrstuvwxyz0123456789";char outMessage[256];int rCode=0;long nRanges=2;/*Encrypt 4 byte segments at zero-based offsets 2 and 12 into message */

eRangeIn[0].offset=2;eRangeIn[0].length=4;eRangeIn[1].offset=12;eRangeIn[1].length=4;

rCode=MQS_EncryptAtOffsets( user_id,inMessage,sizeof(inMessage),outMessage,sizeof(outMessage)eRangeIn,eRangeOut,nRanges);

The C/C++ API 83

Direct Calls

MQS_EncryptThenSign: Encrypt message then sign the result

Description

MQS_EncryptThenSign enables an application to encrypt all or parts of a message and then sign the result.


After the encryption is complete, the symmetric key used for the encryption is itself encrypted, using the public key of the target system. The result is placed in the security trailer and the trailer is appended to the end of the encrypted message.

The message is then signed, using the private key of the sender, and returned to the caller.

Syntax

int MQS_EncryptThenSign(char *user_id,char *passw,char *dest_id,unsigned char *inData,long inDLen,unsigned char *outData,long *outDLen,char *leftDelim,char *rightDelim),unsigned char *mdFormat);

Parameters

user_id User ID of the sender. This sender’s private key is used to sign the data. The receiver will use the sender’s public key to verify the sender’s signature.

passw Password of the sender. Required to protect the sender’s private key, used in the signing operation.

Direct Calls


Return codes


dest_id User ID for which this message is to be encrypted. The public key of this user ID must be registered in the user key database. This user ID’s public key is used to encrypt the data, which can only be decrypted by someone who has the corresponding private key.

inMsg Message to be encrypted

inLen Length of the message to be encrypted

outMsg Buffer allocated by the caller where MQS_EncryptThenSign returns the encrypted and signed data. It must be allocated by the calling routine and should be about 400 bytes larger than inData (200 bytes for each of the two operations). (See ‘Calculating Length of the PathWAI Secure Security Trailer” on page 157 for guidelines for calculating the buffer size.)

outLen I/O field. On input, the calling routine places the size of outMsg in this field. On output, MQS_EncryptThenSign returns the actual length of the encrypted and signed message, including the trailer. If the return code is OUT_BUF _SHORT, the required size is returned in this field. For range encryption, there is an extra 16-byte overhead per range.



mdFormat The original WebSphere MQ mdFormat that should be restored after the message is analyzed

The C/C++ API 85

Direct Calls

MQS_EncryptAtOffsetsThenSign

Description

This routine performs the same functions as MQS_EncryptThenSign except that it passes an array of zero-based offset/length pairs, and a count of those pairs instead of a pair of character arrays that represent left and right delimiters embedded in the message text.

On successful completion, the function will return an array of RANGE structures containing the offset/length pairs related to the encrypted ranges in the output buffer.

Overlapping ranges are not allowed and ranges extending beyond the boundaries of the message are not allowed. Ranges must be specified in ascending order by offset.

Syntax

int MQS_EncryptAtOffsetsThenSign(char *user_id,char *passw,char *dest_id,unsigned char *inData,long inDLen,unsigned char *outData,long *outDLen,PRANGE pRangeOffsetsIn,short lNumRangeOffsetsIn,PRANGE pRangeOffsetsOutunsigned char *mdFormat);

Parameters


passw Password of the sender. Required to protect the sender’s private key.

Direct Calls


dest_id User ID of the person this data is to be encrypted for. The public key of this user ID must have have been registered in the user key database. This user ID’s public key is used to encrypt the data, which can only be decrypted by someone who has the corresponding private key.



outData Buffer allocated by the caller where MQS_SignThenEncryptAtOffsets returns the encrypted data. It must be allocated by the calling routine and should be about 200 bytes larger than inData.

outDLen I/O field. On input, the calling routine places the size of outData in this field. On output, MQS_SignThenEncryptAtOffsets returns the actual length of the encrypted data, including the trailer. If the return code is OUT_BUF _SHORT, the required size is returned in this field. For range encryption, there is an extra 16-byte overhead per range.

pRangeOffsetsIn Pointer to an array of RANGE structures. This is an existing structure mapped in RANGE.H. Ranges of message text starting at each offset and for the length of data specified will be encrypted using the appropriate symmetric key and the resulting cipher text embedded in the output message buffer at the next available offset.

lNumRangeOffsetsIn A short containing the count of offset/length pairs pointed to by pRangeOffsetsIn

pRangeOffsetsOut Pointer to an array of RANGE structures. This is an existing structure mapped in RANGE.H. This array contains the offsets and lengths of the ranges AFTER each range has been encrypted.

mdFormat The original WebSphere MQ mdFormat that should be restored after the message is analysed

The C/C++ API 87

Direct Calls

MQS_ErrorMsg: Error message helper functionThe MQS_ErrorMsg helper function is used to obtain more information regarding an PathWAI Secure return code.

Syntax

char *MQS_ErrorMsg(int errCode);

Parameters

Returns

Pointer to a character string associated with errCode.

errCode Return code from any of the MQS functions. See “PathWAI Secure Messages and Return Codes” on page 130.

Direct Calls


MQS_GetKey

Description

This call retrieves the DER-encoded public key for a given PathWAI Secure user ID. This call may be useful if a public key is required to be used outside of the PathWAI Secure environment for encryption or signature verification.

Syntax

int MQS_GetKey(char *user_id,UCHAR *public_key,int *public_keylen)

Parameters

Return Codes

See “Messages and Return Codes” on page 129.

user_id Character string containing the PathWAI Secure user ID for which the public key is to be retrieved

public_key Unsigned character string that will contain the PathWAI Secure user’s DER-encoded public key on output

public_keylen Pointer to a long containing the length of the returned DER-encoded public key

The C/C++ API 89

Direct Calls

MQS_GetTrailerInfoEx: Get information from an MQSecure trailer

Description

MQS_GetTrailerInfoEx enables an application to get information from the MQSecure security trailer. The function is passed a pointer to a buffer containing an WebSphere MQ message with the MQSecure trailer attached. The function returns selected information from the trailer.

Syntax

void MQS_GetTrailerInfoEx(UCHAR *inMsg,long inLen,PTRAILER_INFO_EX);0

Parameters

TRAILER_INFO_EX variables

inMsg The input WebSphere MQ message with MQSecure trailer attached

inLen The length of InMsg

PTRAILER_INFO_EX Pointer to a TRAILER_INFO_EX structure (see below)

Variable Type Description

type int On return contains a trailer type, or error code:

MQS_NoTrailer. No trailer found

MQS_SignTrailer Sign trailer found

MQS_EncryptTrailer Encrypt trailer found

MQS_NoActionTrailer. No action trailer

MQS_RangeTrailer. Range trailer

MQS_ClusterTrailer. Cluster trailer found

MQS_InputParmMissing. Input parameter missing

MQS_DecomposeMessageFailure. Process failure

Direct Calls


MQSS_MESSAGE_COMPONENTS variables

Note: If non-zero, the areas addressed by the pointers in this structure must be pre-allocated and the lengths of these areas passed as input to the MQS_ComposeMessage, MQS_DecomposeMessage, and

user_id[48] char On return contains the user ID used to sign the message or the user ID for which it was encrypted.

PMQSS_MESSAGE_COMPONENTS Pointer to an MQSS_MESSAGE_COMPONENTS structure (see below)

msgSymEncrypt UCHAR Symmetric encryption algorithm

msgSigningAlgorithm UCHAR Signing algorithm

Type Variable

UCHAR *pCertTable

long lNumCertificates

UCHAR *pCertificates

long lCertificatesLen

UCHAR *pBlobs

long lBlobsLen

PRSA_ENCR pClusterSections

long lNumClusterSections;

PRANGE pRanges;

long lNumRanges;

PTRAILER pSecurityTrailer;

long lSecurityTrailerLen;

UCHAR *pMessage;

long lMessageLen;

Variable Type Description

The C/C++ API 91

Direct Calls

MQS_GetTrailerInfoEx API calls. In the case of MQS_DecomposeMessage, the pre-allocated areas may be too short and, if so, the length of the required area will be returned along with an appropriate error code. If the pointers are initialized to zero, the storage required will be allocated by the underlying functions. It is the responsibility of the caller to free these areas if this approach is used.

Return codes

None

Direct Calls


MQS_RangeCount

Description

This call returns the count of encryption ranges established by a specified pair of left and right delimiters that mark the beginning and end of each range to be encrypted within the body of a PathWAI Secure message.

This call is useful for calculating the length of the output buffer on a range encryption operation. Each range in the input message will increase in length by 1–16 bytes in the output depending on the algorithm used to encrypt the message ranges. The AES and RC6 encryption algorithms round input ranges up to the next 16 byte boundary while Triple-DES, RC2, and RC5 round up to the next 8 byte boundary. RC4 is a stream cipher and results in no change in length between input and output. (See also “Calculating Length of the PathWAI Secure Security Trailer” on page 157.)

Syntax

int MQS_RangeCount(UCHAR*inMessage,long inMessageLen,char *leftDelimiter,char *rightDelimiter)

Parameters

i

Return Codes

See “Messages and Return Codes” on page 129.

nMessage Unsigned character string containing message for which encryption ranges are to be counted

inMessageLen Long containing length of message

leftDelimiter 1-9 byte character string containing the delimiter marking the beginning of each encryption range

rightDelimiter 1-9 byte character string containing the delimiter marking the end of each encryption range

The C/C++ API 93

Direct Calls

MQS_SetLocalCCSID

Description

This call establishes the code page that will be used to convert message data into the local platform’s character set. This call is necessary because direct calls do not assume the presence of a WebSphere MQ queue manager which can be interrogated to obtain this information using the MQI call MQINQ.

Syntax

int MQS_ SetLocalCCSID (longinCCSID)

Parameters

Return Codes

inCCSID Pointer to a long containing the code page to be set

SUCCESS Code page was set successfully

Direct Calls


MQS_SetMQFormat

Description

This call establishes the WebSphere MQ message format in a PathWAI Secure security trailer before a message is MQPUT. The call is useful when writing direct calls in an application that depends on re-establishing a message format in the WebSphere MQ message descriptor after performing PathWAI Secure cryptographic operations.

Syntax

int MQS_SetMQFormat(UCHAR *inMessage, long inMessageLen, UCHAR *mdFormat)

Parameters

Return Codes

inMessage Pointer to unsigned characters containing message for which WebSphere MQ message format is to be set

inMessageLen Long containing length of message

mdFormat Pointer to unsigned characters containing the WebSphere MQ message format that is to be set for the message

SUCCESS WebSphere MQ message format was set in message trailer successfully

INVALID_TRAILER Format of security trailer appended to message is invalid

INVALID_TR_VERSION Security trailer appended to message is for an unsupported version of PathWAI Secure

The C/C++ API 95

Direct Calls

MQS_Sign: Sign messageThe MQS_Sign function is called by a program to add a digital signature at the end of the body of the message.

Syntax

int MQS_Sign(char *user_id,char *passw,unsigned char *inMsg, long inLen,unsigned char *outMsg,long *outLen);

Parameters

Return Codes


user_id User ID of the sender. This sender’s private key is used to sign the message. The receiver uses the sender’s public key to verify the sender’s signature.


inMsg Message to be signed

inLen Length of the message to be signed

outMsg Buffer allocated by the caller, where MQS_Sign returns the signed message and must be allocated by the calling routine. It should be about 200 bytes larger than inMsg.

outLen I/O field. On input, the calling routine places the size of outMsg in this field. On output, MQS_Sign returns the actual length of the processed message. If the return code is OUT_BUF_SHORT, the required size is returned in this field.

Direct Calls


MQS_SignThenEncrypt: Add digital signature then encrypt resultThis function adds a digital signature to the message, then the signed message is encrypted and returned to the caller.

Syntax

int MQS_SignThenEncrypt(char *user_id,char *passw,char *dest_idunsigned char *inData, long inDLen,unsigned char *outData,long *outDLen,char *leftDelim,char *rightDelim,unsigned char *mdFormat);

Parameters

user_id User ID of the sender. This sender’s private key is used to sign the message. The receiver will use the sender’s public key to verify the sender’s signature.


dest_id User ID of the person this message is to be encrypted for. The public key of this user ID must have have been registered in the user key database. This user ID’s public key is used to encrypt the message, which can only be decrypted by someone who has the corresponding private key.



outData Buffer allocated by the caller where MQS_SignThenEncrypt returns the encrypted data. It must be allocated by the calling routine and should be about 400 bytes larger than inData (200 bytes for each of the two operations). (See ‘Calculating Length of the PathWAI Secure Security Trailer” on page 157 for guidelines for calculating the buffer size.)

The C/C++ API 97

Direct Calls

Return Codes


outDLen I/O field. On input, the calling routine places the size of outData in this field. On output, MQS_SignThenEncrypt returns the actual length of the encrypted data, including the trailer. If the return code is OUT_BUF _SHORT, the required size is returned in this field. For range encryption, there is an extra 16-byte overhead per range.



mdFormat The original WebSphere MQ mdFormat that should be restored after the message is analysed.

Direct Calls


MQS_SignThenEncryptAtOffsets

Description

This routine performs the same functions as MQS_SignThenEncrypt except that an array of zero-based offset/length pairs, and a count of those pairs, are passed as parameters instead of a pair of character arrays that represent left and right delimiters embedded in the message text.

On successful completion the function will return an array of RANGE structures containing the offset/length pairs related to the encrypted ranges in the output buffer.

Overlapping ranges are not allowed and ranges extending beyond the boundaries of the message are not allowed. Ranges must be specified in ascending order by offset.

Syntax

int MQS_SignThenEncrypt(char *user_id,char *passw,char *dest_idunsigned char *inData, long inDLen,unsigned char *outData,long *outDLen,PRANGE pRangeOffsetsIn,short lNumRangeOffsetsIn,PRANGE pRangeOffsetsOutunsigned char *mdFormat);

Parameters



The C/C++ API 99

Direct Calls

dest_id User ID of the person this data is to be encrypted for. The public key of this user ID must have have been registered in the user key database. This user ID’s public key is used to encrypt the data, which can be decrypted only by someone who has the corresponding private key.

inData data to be encrypted


outData Buffer allocated by the caller where MQS_SignThenEncryptAtSets returns the encrypted data. It must be allocated by the calling routine and should be about 200 bytes larger than inData.

outDLen I/O field. On input, the calling routine places the size of outData in this field. On output, MQS_SignThenEncryptAtSets returns the actual length of the encrypted data, including the trailer. If the return code is OUT_BUF _SHORT, the required size is returned in this field. For range encryption, there is an extra 16-byte overhead per range.

pRangeOffsetsIn Pointer to an array of RANGE structures. This is an existing structure mapped in RANGE.H. Ranges of message text starting at each offset and for the length of data specified will be encrypted using the appropriate symmetric key and the resulting cipher text embedded in the output message buffer at the next available offset.

lNumRangeOffsetsIn Short containing the count of offset/length pairs pointed to by pRangeOffsetsIn

pRangeOffsetsOut Pointer to an array of RANGE structures. This is an existing structure mapped in RANGE.H. This array contains the offsets and lengths of the ranges AFTER each range has been encrypted.

mdFormat Original WebSphere MQ mdFormat that should be restored after the message is analysed

Direct Calls


MQS_Version: Version helper functionThe MQS_Version helper function is used to determine the version of your installed PathWAI Secure product, typically when working with Candle support personnel.

Syntax

void MQS_Version(char *vBuf,int bufLen);

Parameters

Return Codes

None.

vBuf Buffer where a string showing the current version of the API is placed

bufLen Size of vbuf.

The C/C++ API 101

Integrated Calls

Integrated Calls

OverviewThe integrated API calls provide a secure layer on top of standard WebSphere MQ MQPUT and MQcalls. The two principal calls are S_MQPUT and S_MQGET. These integrated calls use the standard WebSphere MQ MQPUT and MQGET parameters, as well as some additional MQSecure parameters.

S_MQCreateAPIContext creates and initializes the context in which PathWAI Secure will operate.

S_MQPUT calls the appropriate stand-alone MQSecure API functions to sign and/or encrypt the message, then calls WebSphere MQ MQPUT to put the message in the queue.

S_MQGET calls WebSphere MQ MQGET to get the message, then calls the appropriate MQSecure stand-alone API functions to authenticate and decrypt the message.

S_MQDestroyAPIContext destroys the context created by S_MQCreateAPIContext.

In addition, PathWAI Secure provides two helper calls, S_MQVERSION and S_MQERRORMSG.

Integrated Calls


S_MQCreateAPIContext

Description

This call establishes a context for each thread in a multi-threaded environment.

In addition, the context structure MQS_APICONTEXT provides a mechanism for:

n enabling reuse of symmetric keys

n enabling caching of asymmetric key.

For exploitation in future releases, the context structure provides a mechanism for

n versioning

n issuing debug messages to a log

If you are writing a multi-threaded program, you must use this call. Before destroying a thread after all PathWAI Secure calls have completed, you must issue MQS_DestroyAPI to clean up storage acquired for the thread.

Programs written for earlier versions of PathWAI Secure do not need to be modified to include this function. However, if you are coding new applications, even if you are not using thread-aware programs, Candle recommends that you use this call to take advantage of the considerable performance enhancements offered by key reuse and caching, and to facilitate compatibility with future releases of PathWAI Secure.

Syntax

int S_MQCreateAPIContext(MQS_APICONTEXT *mqsAPIContext)

MQS_APICONTEXT parameters

The MQS_CreateAPIContext parameters are specified in the MQS_APICONTEXT data structure (defined in sec_api.h):

Parameter Type Definition

Version Long Set to MQS_APICONTEXT_VERSION_1

The C/C++ API 103

Integrated Calls

Debug Long Enable/disable debugging mode:

1 Debug

0 No debug

nKeyReusesMax Long Number of times a symmetric key is reused before a new key is generated

KeyGenerationInterval Long The amount of time (in seconds) a symmetric key is reused before a new key is generated


Integrated Calls


S_MQDestroyAPIContext

Description

Should be called after all MQSecure calls on a given thread to release storage. This function must be called if you called S_MQCreateAPIContext.

Syntax

int MQS_DestroyAPIContext(MQS_APICONTEXT *pMQSAPIContext)

Parameters

Since none of the MQS_APICONTEXT variables are relevant at this point, the input parameter is currently ignored and it is safe to pass in NULL. However, since this structure will be exploited in future releases, Candle advises that you pass an address rather than NULL.

Return codes



The C/C++ API 105

Integrated Calls

S_MQPUT—Secure MQPUTS_MQPUT is called by a program to sign, encrypt, or sign and encrypt a message, then place the message in the WebSphere MQ queue. The input PathWAI Secure parameters indicate which security functions should be applied to the message.

PathWAI Secure parameters are specified in the MQSS_ARGS data structure. The address of this data structure is supplied as the first parameter to S_MQPUT. All other parameters supplied are standard WebSphere MQ MQPUT parameters. For information concerning WebSphere MQ MQPUT parameters, please consult the WebSphere MQ documentation.

Syntax

void S_MQPUT(PMQSS_ARGS mqsArgs,

MQHCONN hConn,

MQHOBJ hObj,

PMQMD pMD,

PMQPMO pPO,

MQLONG inLen,

PMQBYTE inMsg,

PMQLONG pCompCode,

PMQLONG pReason);

MQSS_ARGS parameters


request_id long Request type (see below)

user_id char[48] The user ID of sender for signing

passw char[48] Password of sender for signing

dest_id char[48] The user ID of receiver for encryption

leftDelim char[10] Left delimiter for (optional) range encryption. Required if rightDelim is specified.

Integrated Calls


Request types

rightDelim char [10] Right delimiter for (optional) range encryption. Required if leftDelim is specified.

rangesIn PRANGE Pointer to an array of RANGE structures. This is an existing structure mapped in RANGE.H. Ranges of message text starting at each offset and for the length of data specified will be encrypted using the appropriate symmetric key and the resulting cipher text embedded in the output message buffer at the next available offset.

rangesOut PRANGE Pointer to an array of RANGE structures. This is an existing structure mapped in RANGE.H. Ranges of encrypted message in the output buffer after successful completion of the range encryption operation.

numRanges long A long containing the count of offset/length pairs pointed to by rangesIn

Request Type Definition

SSREQ_SIGN Sign message

SSREQ_SEAL Encrypt entire message

SSREQ_RSEAL Range encrypt (encrypt portion or portions of message) between delimiters

SSREQ_ ROSEAL Range encrypt (encrypt portion or portions of message) at offsets

SSREQ_SEAL_SIGN Encrypt then sign message


The C/C++ API 107

Integrated Calls

Return codes


SSREQ_RSEAL_SIGN Range encrypt (encrypt portion or portions of message) between delimiters then sign message

SSREQ_ROSEAL_SIGN Range encrypt (encrypt portion or portions of message) at offsets then sign message

SSREQ_SIGN_SEAL Sign then encrypt message

SSREQ_SIGN_RSEAL Sign then range encrypt (encrypt portion or portions of message) between delimiters

SSREQ_SIGN_ROSEAL Sign then range encrypt (encrypt portion or portions of message) at offsets

Request Type Definition

Integrated Calls


S_MQGET—Secure MQGETS_MQGET is called by a program to retrieve a message from a queue, then analyze the message trailer in order to authenticate and/or decrypt it.

PathWAI Secure parameters are specified in the MQSS_ARGS data structure. The address of this data structure is supplied as the first parameter to S_MQGET. All other parameters supplied are standard WebSphere MQ MQGET parameters. For information concerning WebSphere MQ MQGET parameters, please consult the WebSphere MQ documentation.

Syntax

void S_MQGET(PMQSS_ARGS mqsArgs,MQHCONN hConn,MQHOBJ hObj,PMQMD pMD,PMQGMO pGO,MQLONG inLen,PMQBYTE inMsg,PMQLONG pInLen,PMQLONG pCompCode,PMQLONG pReason);

MQSS_ARGS parameters

Return codes



passw char[48] Password for user ID of receiver for decryption

numTrailers long Number of trailers to be analyzed

The C/C++ API 109

Integrated Calls

S_MQVERSION—Version helper functionThe S_MQVersion helper function is used to determine the version of your installed PathWAI Secure product and typically when working with Candle support personnel.

Syntax

void S_MQVersion(char *vBuf,int bufLen);

Parameters

Return codes

None

vBuf Buffer where a string showing the current version of the API is placed.

bufLen Size of vBuf.

Integrated Calls


S_MQERRORMSG—Error message helper functionThe S_MQErrorMsg helper function is used to obtain more information regarding an PathWAI Secure return code.

Syntax

char *S_MQErrorMsg(int errCode);

Parameters

Return code

Pointer to a character string associated with errCode.

errCode Reason code from S_MQGET or S_MQPUT

The Java API 111

The Java API

OverviewThis chapter discusses the PathWAI Secure Java API. It discusses what you need to know to invoke the Java bindings and details the syntax and parameters for the methods.

Chapter contentsDeveloping Java Applications with the PathWAI Secure API. . . . . . . . . . 113

Java environment prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113PathWAI Secure Java classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Logging failure of security operations . . . . . . . . . . . . . . . . . . . . . . . . 114

MQSecureEnvironment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115Variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

MQSecure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Constructor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117analyzeMsg: Verify digital signature/decrypt message . . . . . . . . . 118analyzeMsgAll: Verify digital signature/decrypt for multiple trailers 119analyzeMsgMultiple: Verify signature/decrypt message sent to multiple destinations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120DestroyAPIContext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

4


encryptMsg: Encrypt message. . . . . . . . . . . . . . . . . . . . . . . . . . . 122encryptAndSignMsg: Encrypt then sign message. . . . . . . . . . . . . 123GetLastError: Retrieve last PathWAI Secure error . . . . . . . . . . . . 124signMsg: Add digital signature. . . . . . . . . . . . . . . . . . . . . . . . . . . 125signAndEncryptMsg: Sign then encrypt message. . . . . . . . . . . . . 126

The Java API 113

Developing Java Applications with the PathWAI Secure API


Note: The Java interface does not support the integrated APIs, only the stand-alone APIs.

Java environment prerequisitesPathWAI Secure supports JDK Version 1.1.8 and above. The Java API is supported on Windows 95/98, Windows NT 4.0 or later, Sun Solaris, AIX, and HP-UX.

LibrariesTo compile PathWAI Secure Java applications the following must be added to the CLASSPATH= environmental variable setting, or using the -classpath switch on execution of javac during compilation.

In Windows environments:

mqsecure\java\lib

In UNIX environments:

mqsecure/java/lib

where mqsecure is the directory and path where you installed PathWAI Secure.

In addition, the standard WebSphere MQ Java libraries must be specified in the CLASSPATH= environmental variable.

PathWAI Secure Java classesPathWAI Secure supplies three classes:

n MQSecureEnvironment contains static variables which control the environment in which an PathWAI Secure object is constructed

n MQSecure contains the methods that implement the PathWAI Secure direct API calls

n MQSecureException converts an PathWAI Secure error code into a text message. This occurs when the exception MQSecureException is thrown by an PathWAI Secure method in the MQSecure class.



These classes are imported by the package com.candle.mqsecure.

The methods implemented by these classes are Java native methods that bridge to the PathWAI Secure DLL sec_api through functions contained in the mqs_japi DLL. mqs_japi is copied to the same directory as the other PathWAI Secure DLLs at installation time. This directory must be specified in the PATH environmental variable.

Invoking PathWAI Secure Java methodsPathWAI Secure methods perform I/O to the user key database and therefore cannot be used in applet code under a browser (that is, the methods must be invoked by a Java application).

Logging failure of security operationsApplications must handle errors returned as a result of the failure of authentication and encryption operations. 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.

The Java API 115

MQSecureEnvironment

MQSecureEnvironment

Description

MQSecureEnvironment contains static member variables that control the environment in which a PathWAI Secure object is constructed. You must create an instance of MQSecureEnvironment if you wish to take advantage of symmetric key reuse and key caching.

Values set in the MQSecureEnvironment class take effect when the PathWAI Secure constructor is called, so you should set the values in the MQSecureEnvironment class before constructing an MQSecure instance.

After creating a new instance of PathWAI Secure, all further calls to methods acting upon the object must be on the same thread. When finished, you must call the PathWAI Secure method DestroyAPIContext() from the same thread to clean up resources.

Variables

nKeyReusesMax

public static int nKeyReusesMax

Number of times to reuse the symmetic key (equivalent to Knn in channel exits)

keygenerationinterval

public static int keygenerationinterval

The period of time that should elapse before the symmetric key is regenerated (in seconds)

debug

public static int debug

Enable or disable debugging mode: 1 = debug, 2 = no debug.

MQSecure


MQSecure

ConstructorCreates a new PathWAI Secure object with code page attributes of the input WebSphere MQ queue manager.

Syntax

public MQSecure(MQQueueManager qMgr)

Parameter

MethodsTable 2 summarizes the PathWAI Secure methods:

qMgr The WebSphere MQ queue manager object

Table 2. PathWAI Secure Methods

Method Description

analyzeMsg(MQMessage, String) Receives a message that has been signed or encrypted by PathWAI Secure

analyzeMsgAll(MQMessage, String, String, int)

Receives a message that has been signed or encrypted by PathWAI Secure

analyzeMsgMultiple(MQMessage, String, String)

Receives a message that has been signed and/or encrypted by PathWAI Secure and sent to a WebSphere MQ cluster

encryptAndSignMsg(MQMessage, String, String, String)

Encrypts then signs a WebSphere MQ message

encryptMsg(MQMessage, String) Encrypts an WebSphere MQ message

DestroyAPIContext() Cleans up resources used by PathWAI Secure

GetLastError() Retrieves a string representation of the last PathWAI Secure error

The Java API 117

MQSecure

ExceptionsThe PathWAI Secure methods throw the following exceptions:

signAndEncryptMsg(MQMessage, String, String, String)

Signs then encrypts a WebSphere MQ message

signMsg(MQMessage, String, String)

Signs a WebSphere MQ message

MQSecureException A PathWAI Secure error has occurred.

MQException A WebSphere MQ error has occurred. The MQSecureException object contains a text message explaining the error.

IOException Thrown if there is a problem accessing the user key database to get the public or private key

Table 2. PathWAI Secure Methods (continued)

Method Description

MQSecure


analyzeMsg: Verify digital signature/decrypt message

Description

Receives a message that has been signed or encrypted by PathWAI Secure.

If the message has been encrypted, this method decrypts it. If the message has been signed, this method verifies the signature. If the decryption or verification is unsucessful, an MQException is thrown.

Syntax

public void analyzeMsg(MQMessage msg,String Password) throws

MQException, IOException, MQSecureException

Parameters

msg WebSphere MQ MQMessage object containing the message plus PathWAI Secure trailer

password Password for the user that the message is encrypted for. Can be an empty string for a message that is not encrypted.

The Java API 119

MQSecure

analyzeMsgAll: Verify digital signature/decrypt for multiple trailersDescription

Receives a message with multiple trailers that has been signed or encrypted by PathWAI Secure.

If the message has been encrypted, this method decrypts it. If the message has been signed, this method verifies the signature. If the decryption or verification is unsuccessful, an MQException is thrown.

Syntax

public void analyzeMsgAll(MQMessage msg, String Destinationid, String Password, int numTrailers) throws MQException, IOException, MQSecureException

Parameters


destinationid The user ID that the message is encrypted for

password Password of the user ID that the message is encrypted for. Can be an empty string for a message that is not encrypted.

numTrailers I/O field. On input, the calling routing places the number of PathWAI Secure trailers to be analyzed. On output, MQS_AnalyzeAll returns the actual number of trailers analyzed.

MQSecure


analyzeMsgMultiple: Verify signature/decrypt message sent to multiple destinations

Description

Receives a message that has been signed and/or encrypted by PathWAI Secure. If the message has been encrypted, this method decrypts it. If the message has been signed, this method verifies the signature. If the decryption or verification is unsuccessful, an MQException is thrown. The message may or may not have been encrypted for multiple users using a destination of a user ID with an appended asterisk.

This method must be used for messages sent to WebSphere MQ clusters.

Syntax

public void analyzeMsgMultiple(MQMessage msg, String Userid, String Password) throws MQException, IOException, MQSecureException

Parameters


userid The user ID for which the message is encrypted

password Password associated with the user ID for which the message is encrypted. Can be an empty string for a message that is not encrypted

The Java API 121

MQSecure

DestroyAPIContext

Description

Destroys the context set up by the PathWAI Secure constructor. This method must be called on the same thread as the constructor.

Syntax

public void DestroyAPIContext() throws MQSecureException

Parameters

None.

MQSecure


encryptMsg: Encrypt messageDescription

Encrypts a WebSphere MQ message.

This method takes an MQMessage as input and encrypts the message using the input user ID. The message is encrypted using the public key of the input userid.

Syntax

public void encryptMsg(MQMessage msg,MString destinationid) throws

MQException, IOException, MQSecureException

Parameters

msg The WebSphere MQ MQMessage object containing the message to sign

destinationid The PathWAI Secure user ID whose private key will be used to sign the message. If the message is being sent to a WebSphere MQ cluster, the destination ID may be a prefix (shared by all members of the cluster) with an appended wildcard asterisk (*).

The Java API 123

MQSecure

encryptAndSignMsg: Encrypt then sign messageDescription

Encrypts then signs an WebSphere MQ message.

This method takes an MQMessage as input, encrypts the message using the input destination user ID, and then signs the encrypted message using the input user ID and password. The message is encrypted using the public key of the input destination ID. The encrypted message is then signed using the private key of the input user ID.

Syntax

public void encryptAndSignMsg(MQMessage msg,String Userid,String Password,String Destinationid)

throws MQException, IOException, MQSecureException

Parameters

msg The WebSphere MQ MQMessage object containing the message to sign.

userid The PathWAI Secure userid whose private key will be used to sign the message.

password The password for the PathWAI Secure user ID whose private key will be used to sign the message.

destinationid The PathWAI Secure user ID whose public key will be used to encrypt the message. If the message is being sent to a WebSphere MQ cluster, the destination ID may be a prefix (shared by all members of the cluster) with an appended wildcard asterisk (*).

MQSecure


GetLastError: Retrieve last PathWAI Secure errorDescription

Retrieves a string representation of the last PathWAI Secure error.

This method retrieves the last PathWAI Secure error code and creates a string object containing a text representation of the error code.

Syntax

public static native String GetLastError()

The Java API 125

MQSecure

signMsg: Add digital signatureDescription

Signs an WebSphere MQ message.

This method takes an MQMessage as input and signs the message using the input user ID and password. The message is signed using the private key of the input user ID.

Syntax

public void signMsg(MQMessage msg,String Userid,String Password) throws MQException,

IOException, MQSecureException

Parameters

msg The WebSphere MQ MQMessage object containing the message to sign

userid The PathWAI Secure user ID whose private key will be used to sign the message

password The password for the PathWAI Secure user ID whose private key will be used to sign the message

MQSecure


signAndEncryptMsg: Sign then encrypt messageDescription

Signs then encrypts an WebSphere MQ message.

This method takes an MQMessage as input, signs the message using the input destination ID and then encrypts the encrypted message using the input user ID and password. The message is signed using the private key of the input user id. The signed message is then encrypted using the public key of the input destination ID.

public void signAndEncryptMsg(MQMessage msg,String Userid,String Password,String Destinationid)

throws MQException, IOException, MQSecureException

Parameters

msg The WebSphere MQ MQMessage object containing the message to sign.

userid The PathWAI Secure user ID whose private key will be used to sign the message.

password The password for the PathWAI Secure user ID whose private key will be used to sign the message.

destinationid The PathWAI Secure user ID whose public key will be used to encrypt the message. If the message is being sent to a WebSphere MQ cluster, the destination ID may be a prefix (shared by all members of the cluster) with an appended wildcard asterisk (*).

Appendixes 127

Appendixes

128 PathWAI Secure for WebSphere MQ Programmers’s Guide, Version 300

Messages and Return Codes 129

Messages and Return Codes

OverviewThis appendix contains PathWAI Secure messages and return codes. For convenience, it also contains the RSA BSAFE return codes for Crypto-C and Cert-C. 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 ContentsPathWAI Secure Messages and Return Codes . . . . . . . . . . . . . . . . . . . . . 130BSAFE Return Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144COBOL API and Administration Reason Codes . . . . . . . . . . . . . . . . . . . 154User Key Database Reason Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

A

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.



PathWAI Secure return codes

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.

0 SUCCESSOperation was successful.

512–550 See “Crypto_C return codes” on page 144.



1025 NO_MEMORYNo memory available.

1026 VRFY_INVALID_SENDERSending user ID is invalid or unknown.

1027 VRFY_MSG_MODIFIEDMessage has been modified.

1028 USERID_NO_MATCHRetyped user ID different.

1029 INVALID_PASSWORDPassword is invalid and/or incorrect.

1030 OUT_BUF_SHORTOutput buffer is too short.

1031 INVALID_TRAILERTrailer is invalid.

1032 INVALID_TR_VERSIONInvalid trailer version.

1033 TRAILER_APPLApplication trailer detected.

1034 TRAILER_NODENode trailer detected.

1035 NO_RANGESNo encryption ranges found.

1036 INVALID_RANGE_PTREncryption range array is invalid.

1037 INVALID_RANGEEncryption range found outside message.

1038 INVALID_REQUESTInvalid PathWAI Secure indirect API request.

1039 INVALID_CHARSETInvalid character set.

1040 USERID_BLANKuser ID is blank.



1041 PASSWORD_BLANKPassword is blank.

1042 PASSWORD_NO_MATCHRetyped password is different.

1043 OVERLONG_INPUTInput buffer too long.

1044 CANCELLEDRequest cancelled by user.

1045 INVALID_UPDATE_REQUpdate request not Valid.

1046 TOO_MANY_CLIENTSToo many clients open at the same time.

1047 INVALID_CLIENTInvalid client handle detected.

1048 INVALID_UINFOBuffer invalid for import users.

1049 USERID_IS_REVOKEDuser ID has been revoked.

1050 NO_USERS_EXPORTEDNo users available for export.

1051 NO_EXPORT_ADMIN_KEYExport of the administrator key is invalid.

1052 NO_EXPORT_FOREIGN_KEYExport of foreign user keys is invalid.

1053 PRIVATE_KEY_OUT_OF_SYNCHPrivate keys are out of synchronization.

1054 CONV_TABLES_NOTFOUNDUnable to find code page conversion tables.

1055 NO_SCYEXITSCYEXIT not defined.

1056 CONV_TABLES_INTERNAL_ERRORInternal error doing code page conversion.



1057 CONV_TABLES_OPEN_FAILEDUnable to open a conversion table file.

1058 CONV_TABLES_READ_FAILEDIncorrect length read for a conversion table file.

1059 CONV_TABLES_MQSSDIR_NOTFOUNDConversion table processing unable to find MQSSDIR.

1060 CONV_TABLES_NO_LOCAL_CCSIDLocal CCSID not set.

1061 SECURITY_SEQUENCE_MISMATCHSecurity exit processing sequence error.

1062 RANDOM_NUMBER_MISMATCHMismatch in security exit random numbers.

1063 GENERATE_RANDOM_NUMBER_BADRandom number generation failure.

1064 BAD_SECURITY_PHASE_NUMBERSecurity Message sequence number not 1–4.

1065 SECURITY_EXCHANGE_INCOMPLETEAll phases of security exchange not completed.

1066 ADMIN_ID_ALREADY_DEFINEDAdministrator ID has already been defined—invalid request.

1067 OUTOFSYNC_EXITDATAExitdata parameters are out of sync.

1068 NULL_NUMTRAILERSThe number of trailers is not specified for PathWAI Secure Get.

1069 INVALID_NUMTRAILERSThe number of trailers is specified incorrectly for PathWAI Secure Get.

1070 NULL_SALT_ADDRESSThe salt pointer is null

1071 KMFPUTENV_INVALID_INPUTInput to internal function KMFPutEnv is invalid.

1072 PUPRKEY_TOKEN_FAILEDCCA_PuPrKeyToken function failed.



1073 PUBLIC_KKEY_TOKEN_FAILEDCCA_PublicKeyToken function failed.

1074 PKA_ENCRYPT_FAILEDCCA_PKAEncrypt failed.

1075 PKA_DECRYPT_FAILEDCCA_PKADecrypt failed.

1076 CSNBOWH_FAILEDCSNBOWH one-way hash failed.

1077 CSNDDSV_FAILEDCSNDDSV digital signature verify failed.

1078 CSNDDSG_FAILEDCSNDDSG digital signture generate failed.

1079 CSNDPKI_FAILEDCSNDPKI PKA key import failed.

1080 CSNBRNG_FAILEDCSNBRNG generate random number failed.

1081 CSNDPKB_FAILEDCSNDPKB build key token failed.

1082 INVALID_INPUT_PARAMETERInvalid input parameters.

1084 LDAP_WRITE_USER_FAILEDWrite of public key to LDAP repository failed.

1085 LDAP_DELETE_USER_FAILEDDelete of public key from LDAP repository failed.

1086 USER_ID_ALREADY_DEFINEDUser ID already defined to LDAP from another platform.

1087 LDAP_OPEN_FAILUREInactive LDAP server address and/or port specified.

1088 LDAP_UNKNOWN_ATTRIBUTERequested attribute not defined to LDAP.

1089 LDAP_VERIFY_FAILEDUnable to authenticate LDAP entry.



1090 CSNBCKM_FAILEDCCA function CSNBCKM failed.

1091 CSNBDEC_FAILEDCCA function CSNBDEC (decipher) failed.

1092 TDES_KEY_INVALIDInvalid TDES key.

1093 TDES_BUFFER_INVALIDInvalid TDES buffer.

1094 CSNBENC_FAILEDCCA function CSNBENC failed.

1095 CCPOPEN_BAD_CRYPTOCPInvalid call to CCPOPEN, bad cryptoCP.

1096 CCPOPEN_ERROR_REASONError in CCPOpen, reason code stored.

1097 CCPOPEN_HARDWARE_NOT_SETHardware support not requested.

1098 DECRYPT_RESTRICTEDDecryption failed, algorithm restricted.

1099 LDAP_CONNECTION_NOT_REQUIREDProduct not configured to connect to LDAP repository.

1100 THREAD_STORAGE_NOT_ACQUIREDThread specific storage could not be acquired.

1101 THREAD_STORAGE_NOT_AVAILABLEExisting thread storage could not be found.

1102/ LDAP_CONNECTION_NOT_DEFINEDLDAP environmental variable(s) not defined.

1103 CH_AUTH_REMOTE_SUFFIX_MISSINGSigned message received from ID missing channel authentication ID suffix.

1104 CH_AUTH_REMOTE_ID_INVALID_CHL_NAMESigned message received from ID without channel name.

1105 CH_AUTH_REMOTE_SUFFIX_INVALIDSigned message received from ID without standard suffix



1106 CH_AUTH_SUFFIX_MISMATCHSigned message received from remote ID with suffix matching local ID.

1107/ SEC_EXIT_UNKNOWN_EXITREASONUnknown value encountered for ExitReason.

1108 GET_MQSDATA_PTR_FAILEDGetMQSDataPtr call failed.

1109 HARDWARE_NOT_SUPPORTEDCryptographic hardware not supported on this platform.

1110 FILENAME_TOO_LONGFile name too long.

1111 TDES_PAD_ERRORTriple-DES software pad byte count error

1112 SIGNING_ALGORITHM_UNKNOWNEnvironment variable MQSECURE_SIGNING_ALGORITHM setting not recognized.

1113 CLUSTER_AUTH_CHANNEL_NAME_MISMATCHClustering authentication user ID channel name invalid.

1114 CLUSTER_AUTH_INPUT_PARM_MISSINGClustering authentication input parameter missing

1115 CLUSTER_AUTH_FIRST_QUALIFIER_MISSINGClustering authentication user ID first qualifier missing

1116 CLUSTER_AUTH_FIRST_QUALIFIER_INVALIDClustering authentication user ID first qualifier invalid

1117 CLUSTER_AUTH_CHANNEL_NAME_MISSINGClustering authentication user ID channel name missing

1118 CLUSTER_AUTH_THIRD_QUALIFIER_MISSINGClustering authentication user ID third qualifier missing

1119 CLUSTER_AUTH_THIRD_QUALIFIER_INVALIDClustering authentication user ID third qualifier invalid

1120 THREAD_STORAGE_NOT_ALLOCATEDThread-level storage has not been allocated

1121 SYMMETRIC_ALGORITHM_UNSUPPORTEDSymmetric encryption algorithm not supported.



1122 USERID_DELETE_FAILEDDeletion of user ID from database failed.

1123 JNI_GETBYTEARRAY_BADJNI GetByteArrayElements() returned NULL.

1124 JNI_GETSTRINGUTF_BADJNI GetStringUTFChars() returned NULL.

1125 JNI_NEWBYTEARRAY_BADJNI NewByteArray() returned NULL.

1126 JNI_NEWSTRINGUTF_BADNI NewStringUTF() returned NULL.

1127 CHANNEL_SECURITY_SETTING_MISMATCHChannel definition PUTAUT(CTX) or PUTAUT(ALTMCA) required.

1128 CHANNEL_SECURITY_SETTING_INVALIDMQSECURE_CHANNEL_SECURITY variable setting not recognized.

1129 MCA_USER_IDENTIFIER_TOO_SHORTPathWAI Secure User ID too long for MCA User Identifier>

1130 MQMD_USER_IDENTIFIER_TOO_SHORTPathWAI Secure User ID too long for Message Descriptor User Identifier.

1131 INVALID_CONTEXTUnable to establish certificate context.

1132 AVA_NOT_FOUNDCertificate field matching the attribute–value assertion specified for PathWAI Secure user ID not found.

1133 MQSECURE_ID_MAPPING_ATTRIBUTE_UNKNOWNEnvironment.variable setting not recognized.

1134 OVERLAPPING_RANGESOverlapping encryption ranges specified.

1135 RANGES_NOT_ASCENDINGEncryption ranges not specified in ascending order by offset.

1136 NO_BASE_CERTIFICATENeither PathWAI Secure ID nor Subject Name supplied.



1137 CONFLICTING_CHAIN_PARMSBoth PathWAI Secure ID and Subject Name supplied.

1138 MAPPING_RECORD_NOT_FOUNDCertificate mapping database record not found.

1139 MAPPING_INDEX_RECORD_NOT_FOUNDCertificate mapping database index record not found.

1140 CERTIFICATE_NOT_FOUND Certificate not found in certificate database.

1141 USER_CERTIFICATE_REQUIREDUser specified that certificate is always required for message embedding, but the certificate was unavailable.

1142 INVALID_CERT_TABLEInvalid certificate table

1143 EMBED_CERTS_NOT_VERIFIEDCould not verify embedded certificate(s).

1144 PKCS12FILE_OPEN_PROBLEMProblem encountered opening PKCS#12 file for input.

1145 ADMIN_NOT_CERTIFIEDAdministrator must have certificate to export to PKCS#7 file.

1146 NO_DELETE_PKI_USERCRLs must be updated/imported to revoke users imported from third-party certificate authority.

1147 TRUST_POINT_NOT_FOUNDCertificate verification chain could not be built to requested trust point.

1148 OCSP_NO_STATUInternal OCSP error

1149 OCSP_CERT_REVOKEDOCSP Responder reports certificate is revoked.

1150 OCSP_CERT_NOT_REVOKEDOCSP Responder reports certificate is not revoked.

1151 OCSP_CERT_REVOCATION_UNKNOWNOCSP Responder reports certificate status unknown.



1152 OCSP_ENVIRONMENT_ERROR 115OCSP Error returned by KMFGetEnv().

1153 OCSP_CACHE_HIOCSP Cache Error: Certificate found in cache.

1154 OCSP_CACHE_MISSOCSP Cache Error: Certificate not found in cache.

1155 OCSP_CACHE_ERROROCSP Cache Error. Certificate lookup error

1156 MESSAGE_BUFFER_POINTER_NULLPointer to message buffer is null.

1157 NO_CLUSTERSCluster-type trailer missing cluster control structures

1158 SECURITY_TRAILER_BUFFER_POINTER_NULLPointer to security trailer buffer is null.

1159 CLUSTER_BUFFER_POINTER_NULLPointer to cluster buffer is null.

1160 BLOBS_BUFFER_POINTER_NULLPointer to blobs buffer is null

1161 RANGE_BUFFER_POINTER_NULLPointer to range buffer is null.

1162 CERT_TABLE_BUFFER_POINTER_NULLPointer to certificate table buffer is null.

1163 CERT_BUFFER_POINTER_NULLPointer to certificate buffer is null.

1164 1164 OCSP_HTTP_ASCEBERR OCSP ASCII/EBCDIC conversion error in CertC.

1537 USER_NOT_FOUNDUser ID not found.

1538 INVALID_KEYSIZEUser key size is invalid.

1539 INVALID_RECSIZEUser key database record size is invalid.



KMFREAD return codes

1540 BUFFER_TOO_LONGUser key buffer too long.

1541 DUPLICATE_KEYDuplicate keys detected.

1542 TOO_MANY_RECORDSToo many user key database records.

1543 END_OF_FILEEnd of user key database detected.

1544 DBSRV_DOWNUser key database server is down.

1545 UPDATE_NOT_CACHEDUser key database cache not updated.

1546 IMPORT_ADMIN_NOT_FOUNDImport administrator not in the user key database.

1547 DB_ALREADY_CONVERTEDInput database already converted

1548 DB_EMPTYInput database is empty

2000 MQSeries error code

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 WebSphere MQ 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


Cert-C 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.


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_SUPPORTED

Recipient key encryption 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


COBOL API and Administration Reason Codes



Message S9(9) Binary Value

Meaning

MQS-OKAY 0

MQS-NO-MEMORY 1025 No memory available.

MQS-VRFY-INVALID-SENDER 1026 Sending user ID is invalid/unknown.

MQS-VRFY-MSG-MODIFIED 1027 Message has been modified.

MQS-USERID-NO-MATCH 1028 Retyped user ID is different.

MQS-INVALID-PASSWORD 1029 Password is invalid and/or incorrect.

MQS-OUT-BUF-SHORT 1030 Output buffer is too short.

MQS-INVALID-TRAILER 1031 Trailer is invalid.

MQS-INVALID-TR-VERSION 1032 Invalid trailer version

MQS-TRAILER-APPL 1033 Application trailer detected.

MQS-TRAILER-NODE 1034 Node trailer detected.

MQS-NO-RANGES 1035 No encryption ranges found.

MQS-INVALID-RANGE-PTR 1036 Encryption range array is invalid.

MQS-INVALID-RANGE 1037 Encryption range found outside message.

MQS-INVALID-REQUEST 1038 Invalid PathWAI Secure API request

MQS-INVALID-CHARSET 1039 Invalid character set

MQS-USERID-BLANK 1040 User ID is blank.

MQS-PASSWORD-BLANK 1041 Password is blank.

MQS-PASSWORD-NO-MATCH 1042 Retyped password is different.

MQS-OVERLONG-INPUT 1043 Input buffer is too long.

MQS-CANCELLED 1044 Request cancelled by user.

MQS-INVALID-UPDATE-REQ 1045 Update request is not valid.

MQS-TOO-MANY-CLIENTS 1046 Too many clients open at same time.

MQS-INVALID-CLIENT 1047 Invalid client handle detected.



MQS-INVALID-UINFO 1048 Buffer invalid for import users.

MQS-USERID-IS-REVOKED 1049 User ID has been revoked.

MQS-NO-USERS-EXPORTED 1050 No users available for export.

MQS-NO-EXPORT-ADMIN-KEY 1051 Export of administrator key invalid.

MQS-NO-EXPORT-FOREIGN-KEY 1052 Export of foreign user keys invalid.

MQS-PRIVATE-KEY-OUT-OF-SYNCH 1053 Private keys out of sync.

Message S9(9) Binary Value

Meaning

User Key Database Reason Codes


User Key Database Reason Codes

Message S9(9) Binary Value Meaning

MQS-USER-NOT-FOUND 1537 User ID not found

MQS-INVALID-KEYSIZE 1538 User key size is invalid

MQS-INVALID-RECSIZE 1539 User key database record size invalid

MQS-BUFFER-TOO-LONG 1540 User key buffer too long

MQS-DUPLICATE-KEY 1541 Duplicate keys fetected

MQS-TOO-MANY-RECORDS 1542 Too many user key database records

MQS-END-OF-FILE 1543 End of user key database detected

MQS-DBSRV-DOWN 1544 User key database server is sown

MQS-UPDATE-NOT-CACHED 1545 User key database cache not updated

MQS-IMPORT-ADMIN-NOT-FOUND 1546 Import administrator not in database

Calculating Length of the PathWAI Secure Security Trailer 157

Calculating Length of thePathWAI Secure Security Trailer

In languages where storage for the output buffer is allocated programmatically (C, C++, COBOL) you need to determine the length of the PathWAI Secure security trailer in order to allocate the output buffer for signing functions. PathWAI Secure trailers are variable in length. You can use the following values to roughly calculate the length of the trailer.

In Version 200 and before, digital signature and encrypted symmetric key are embedded in the fixed portion of the trailer and no additional length should be calculated.

Fixed portion of trailer 208 bytes

Each digital signature or encrypted symmetric key

96–256 bytesLength depends on the modulus length of the RSA keys supported (768–2048 bits)

Each range in a range-encrypted message for offset/length control structures

8 bytes

Message encrypted for multiple recipients

154 bytes + 96–256 bytes for the public-key-encrypted symmetric key for each user

Each message-embedded certificate

size of certificate + 16 bytes

B


To accurately calculate the length of output from PathWAI Secure operations consideration must also be given to the block size of the symmetric cipher and the bytes added as the result of padding operations:

For example, a 161 byte message AES-encrypted for a user with a public key modulus of 1024 bits which is signed by a user with a private key modulus of 2048 bits will add:

In this example, the 161 byte input message will have (416+256+128+15 = 799) bytes added, resulting in a 976 byte signed encrypted PathWAI Secure message.

Since the size and the number of certificates embedded in messages are variable and cannot necessarily be known in advance, determining the length of the required buffer must be an iterative process. Check for the failure code OUT_BUF_SHORT (1030). If this code is returned, reallocate the output buffer with the length returned in the output data field describing the output buffer length (OutLen in C/C++, OMSGLENGTH in COBOL) and call the function again.

Triple-DES, RC2, and RC5 1–8-bytes for a wholly encrypted message or for each encrypted range in the message

RC6 and AES 1–16 bytes for a wholly encrypted message or for each encrypted range in the message

RC4 No additional length. Output of encryption is the same size as the input because this is a stream cipher and has appropriate characteristics, such as no padding.

One trailer for each cryptographic operation (signing and encryption)

(200 bytes + 200 bytes) = 416 bytes.

Digital signature operation 2048 bits = 256 bytes

Encryption 1024 bits = 128 bytes

AES symmetric encryption 16 bytes - (input message lengthmod16)For example, if the message is 161 bytes long, this will be an additional 15 bytes.

Guide to Candle Customer Support 159

Guide to CandleCustomer Support

IntroductionCandle 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160– 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164– Assigned Support Center Representative (ASCR)– Maintenance Assessment Services (MAS)– Multi-Services Manager (MSM)

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

C

Base Maintenance Plan



OverviewCandle 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 supportCandle 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.

eSupportIn 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 levelsResponses 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 Crisis

A crisis affects your ability to conduct business, and no procedural workaround exists. The system or application may be down.

Severity 2High

A high-impact problem indicates significant business effect to you. The program is usable but severely limited.

http://www.candle.com/support/



Candle has established the following service-level objectives:

Severity 3Moderate

A moderate-impact problem involves partial, non-critical functionality loss or a reasonable workaround to the problem. A “fix” may be provided in a future release.

Severity 4Low

A low-impact problem is a “how-to” or an advisory question.

Severity 5Enhancement Request

This is a request for software or documentation enhancement. Our business units review all requests for possible incorporation into a future release of the product.

Call Status Severity 1 Goal

Severity 2 Goal

Severity 3 Goal

Severity 4 Goal

Severity 5Goal

First Call Time to Answer

90% within one minute

Level 1 Response(Normal Business Hours)

90% within 5 minutes

90% within one hour

Level 2 Response

(Normal Business Hours)

Warm Transfer

90% within two hours

90% within eight hours

Scheduled follow-up (status update)

Hourly or as agreed

Daily or as agreed

Weekly or as agreed Notification is made when an 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 PurposesCandle 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 EscalationsCandle 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 BeyondWhat 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 supportn eSupport using the World Wide Webn Regularly scheduled product updates and maintenance provided at no

additional chargen Over 200 specialized technicians providing expert support for your

Candle products

Enhanced Support Services



OverviewOur 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 informationTo 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.

http://www.candle.com/support/

Glossary 167

Glossary

A

authentication The act of verifying information such as identity, ownership, or authorization.

C

certificate See digital certificate

channel exit A program that performs additional processing at a defined place in the processing carried out by the message channel agent (MCA).

Certificate Authority An internal entity or trusted third party (such as VeriCert) that issues, signs, revokes, and manages digital certificates. See also digital certificate, trust point, root certificate.

D

digital certificate See also root certificate, trusted certificate

digital envelope A ”package” composed of a message encrypted by a symmetric key and the symmetric key itself, encrypted using the receiver’s public key.

digital signature The encryption of a message digest with a private key. Used for verifying the identify of the sender of the message.

Data Encryption Standard (DES) A block cipher developed by IBM and the U.S. government in the 1970s as an official standard.

DES see Data Encryption Standard

digest Commonly used to refer to the output of a hash function. For example, a message digest refers to the hash of a message.

E

encryption The transformation of plain text into an apparently less readable form through a mathematical

G


process. The encrypted text may be read by anyone who has the key that decrypts the ciphertext.

end-to-end security Secures a message from the source application to the target application, regardless of the number of physical machines it hops across in transit.

H

hash function A function that takes a variable sized input and has a fixed size output.

K

key 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 a string or block of text or other data to encrypt or decrypt it. See also private key, public key, secret key.

key management The tasks involved in the creation, distribution, authentication, and storage of keys.

key pair The public key and private key issued to a particular user ID.

M

MCA See message channel agent

message channel agent (MCA) A program that controls the sending and receiving of messages.

message digest The result of applying a hash function to a message.

N

node-to-node security Secures a message as it travels across a single physical channel connection from a source machine to a target machine.

O

OCSP See online certificate status protocol

online certificate status protocol (OCSP) A protocol for sending requests for certificate status to an online server, or responder.

P

password-based encryption (PBE) All private keys must be encrypted

PBE See password-based encryption.

Glossary 169

PKCS See public key cryptography standards.

private key The secret member of a key pair. It is used for signing and decryption.

public key The member of a key pair that is made available to all communicating users. It is used for encryption and authentication.

public key cryptography Cryptography based on methods involving a public key and a private key.

Public key cryptography standards (PKCS) A set of standard protocols for exchanging information securely on the Internet using a public key infrastructure (PKI).

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.

S

secret key See symmetric key.

symmetric key An encryption/decryption key shared by both sender and receiver. Also known as a secret key.

T

trusted certificate In MQSecure, a certificate designated as “trusted” by the site for the purpose of authenticating users.

trust point An assigned level of trust. The trust point may itself be part of some other verification chain.

certificate path/chain, cross certificates,

Index 171

Index

Aadd signature

C/C++ 95COBOL 47Java 125

administration reason codes 154Adobe portable document format 8Advanced Encryption Standard (AES) 19AES (RijnDael) algorithm 19analyzeMsg (Java method) 118analyzeMsgAll (Java method) 119analyzeMsgMultiple (Java methods) 120APIs

when to use 28application-to-application security 27ASCR

assigned support center representative 164

assigned support center representativeASCR 164

asymmetric keysdescription of 20

asymmetric keys, caching 102authentication 18

BBSAFE return codes 144

CC/C++ API

direct calls 64–100integrated calls 101–110

C/C++ API functions 59–110compose message 73create context 74create context (integrated) 102decrypt at offsets 69decrypt message 65decrypt message (multiple

destinations) 71decrypt message (multiple trailers) 67destroy context 77encrypt message 78encrypt then sign message 83error message helper 87error message helper (integrated) 110get public key 88get trailer information 89MQGET, authenticate, and decrypt 108range count 92set local code page 93set WebSphere MQ message format 94sign then encrypt message 96sign, encrypt, and MQPUT 105verify signature 65verify signature (multiple destinations) 71verify signature (multiple trailers) 67version helper 100version helper (integrated) 109

C/C++ API header file 61

I


C/C++ API libraries 61C/C++ API reason codes 154caching asymmetric keys 102caching of asymmetric key 74calculating length of security trailer 33,

157–158certificate revocation lists

description 21certificates

description 21CLASSPATH environment variable 113-classpath switch 113cleaning up storage 102COBOL API 31–58

integrated subroutines 50–56SEC_ARGS data structure 51, 53

COBOL API subroutinesdecrypt message 35decrypt message (multiple

destinations) 39decrypt message (multiple trailers) 37encrypt message 41encrypt then sign message 43error message helper 45get trailer information 46integrated subroutines ??–56MQGET, authenticate, and decrypt 53sign message 47sign then encrypt message 48sign, encrypt, and MQPUT 51verify signature 35verify signature (multiple destinations) 39verify signature (multiple trailers) 37

code page 93com.candle.mqsecure 114create context 101, 102cryptographic approach 19customer service

telephone support 160customer support

base maintenance plan 160contact information 166

enhanced support services 164eSupport 161severity levels 161

Ddata structures (COBOL)

get trailer info buffer 58SEC-ARGS 57

debug messages 74, 102debug variable 115decrypt message


decrypt message (multiple destinations)C/C++ 71COBOL 39Java 120

decrypt message (multiple trailers)C/C++ 67COBOL 37Java 119

delimiter-based range encryption 83, 96delimiter-based range encryption

(C/C++) 78DES encryption 19destroy context 101DestroyAPIContext 121DestroyAPIContext method 115Digital 21digital certificates, See certificates 21digital envelopes 22, 23digital signature 25direct calls (C/C++) 64–100DLLs

mqs_java 114sec_api 114

Eencrypt message

C/C++ 78COBOL 41

Index 173

Java 122encrypt then sign message


encryptAndSignMsg (Java method) 123encryption 26encryption algorithms 19encryptMsg (Java method) 122error handling 34, 114error handling (C/C++) 63error message helper

C/C++ 87COBOL 45

error message helper (integrated)C/C++ 110COBOL 55

eSupportcustomer support 161

exceptions, MQSecure methods 117

Gget trailer info buffer (COBOL data

structure) 58get trailer information

COBOL 46GetLastError (Java method) 124

Hheader file

C/C++ API 61helper functions

error message 45error message (integrated) 55version 100, 109version (integrated) 56

Iimporting Java classes 113inCCSID 93integrated calls (C/C++) 101–110integrated function calls 28

integrated subroutines (COBOL) 50–56integrated version helper function

C/C++ 109COBOL 56

integrity 18integrity, message 25invoking MQSecure Java methods 114IOException 117

JJava API 111–117

environment prerequisites 113Java API methods

decrypt message 118decrypt message (multiple

destinations) 120decrypt message (multiple trailers) 119encrypt message 122encrypt then sign 123get last error message 124sign message 125sign then encrypt 126verify signature 118verify signature (multiple

destinations) 120verify signature (multiple trailers) 119

Java classesMQSecure 113MQSecureException 113

Java exceptionsIOException 117MQException 117MQSecureException 117

Java libraries 113Java methods 116–117JCL templates

templates, JCL 33

Kkeygenerationinterval variable 115KMFREAD return codes 142


Llength of security trailer, calculating 157–

158libraries

C/C++ 61Java 113

Mmaintenance assessment service

MAS 164MAS

maintenance assessment service 164message digest 25message encryption 26message format, WebSphere MQ 94message integrity, ensuring 25methods, Java 116–117mqdirecc return codes 132–153mqdirect return codes 132–153MQException 117MQPUT

C/C++ 105COBOL 51

MQS_Analyze (C/C++ function) 65MQS_AnalyzeAll (C/C++ function) 67MQS_AnalyzeAtOffsets 69MQS_AnalyzeMultiple (C/C++

function) 71MQS_APICONTEXT structure 75, 102MQS_APICONTEXT variables 104MQS_ComposeMessage 73MQS_CreateAPIContext 74MQS_DecomposeMessage

C/C++ API functionsdecompose message 76

MQS_DestroyAPI 74MQS_DestroyAPIContext 75, 77MQS_Encrypt (C/C++ function) 78MQS_EncryptAtOffsets 80MQS_EncryptAtOffsetsThenSign 85MQS_EncryptThenSign (C/C++

function) 83

MQS_ErrorMsg (C/C++ function) 87MQS_GetKey 88MQS_GetTrailerInfoEx 89mqs_java DLL 114MQS_RangeCount 92MQS_SetLocalCCSID 93MQS_SetMQFormat 94MQS_Sign (C/C++ function) 95MQS_SignThenEncrypt (C/C++

function) 96MQS_SignThenEncryptAtOffsets 98MQS_Version (C/C++ function) 100MQSANLY (COBOL subroutine) 35MQSANLYA (COBOL subroutine) 37MQSANYLM (COBOL subroutine) 39MQSEANDS (COBOL subroutine) 43MQSecure class 113MQSecure constructor

parameters 116syntax 116

MQSecure constructor methods 116MQSecure errors, retrieving (Java) 124MQSecure method exceptions 117MQSecureEnvironment class 113, 115MQSecureEnvironment variables 115MQSecureException 117MQSecureException class 113MQSENCR (COBOL subroutine) 41MQSeries MQGET 53MQSeries MQPUT 51, 105MQSERRM (COBOL subroutine) 45MQSGETT (COBOL subroutine) 46MQSS_ARGS data structure 102, 105, 108MQSS_ARGS parameters 108MQSS_MESSAGE_COMPONENTS

structure 90MQSSANDE (COBOL subroutine) 48MQSSIGN (COBOL subroutine) 47MSM

multi-services manager 164multi-services manager

MSM 164

Index 175

multi-threaded programs 74, 102

NnKeyReusesMax variable 115node-to-node security 27

OOCSP responder

description 21offset-based range encryption 85, 98offset-based range encryption (C/C++) 80overview 18

Ppartial encryption, See range encryption 27PATH environmental variable 114PDS (SEC@API) 61platform mutual authentication 18printing problems 9privacy 18privacy, ensuring 26public key cryptography 20–26public keys

retrieving 88public/private key pairs

description 20

Rrange encryption 27

delimiter-based 78, 83, 96offset-based 69, 80, 85, 98

range encryption, offset-based 85, 98RANGE structures 85, 98RC2 algorithm 19RC4 algorithm 19RC5 algorithm 19reason codes

administration 154C/C++ API 154user key database 156

releasing storage 75, 77, 104

repudiation 18request identifiers 57request types 106REQUEST-ID 57required calls (C/C++) 61retrieve last MQSecure error (Java) 124return codes

BSAFE 144KMFREAD 142mqdirect, mqdirecc 132–153

reuse of symmetric keys 74reusing symmetric keys

Java 115reusing symmtric keys 102RijnDael (AES) algorithm 19RSA BSAFE return codes 144RSA RC2 encryption 19

SS_MQCreateAPIContext 101, 102S_MQDestroyAPIContext 101, 104S_MQErrorMsg (C/C++ function) 110S_MQGET (C/C++ function) 108S_MQPUT (C/C++ function) 105S_MQVersion (C/C++ function) 109samples, COBOL 33sec_api 61sec_api DLL 114sec_api.h 61, 75sec_api.lib 61SEC_ARGS data structure 51, 53SEC-ARGS (COBOL data structure) 57secure MQGET 53

COBOL 108secure MQPUT 51securing messages

through APIs 27through channel exits 27

security trailer 89security trailer, calculating length of 33severity levels

customer support 161


sign messageC/C++ 95COBOL 47Java 125

sign then encrypt messageC/C++ 96COBOL 48Java 126

sign, encrypt, and MQPUTCOBOL 51

sign, encrypt, and MQPUT (integrated)C/C++ 105

signAndEncryptMsg (Java method) 126signMsg (Java method) 125SMQERRM (COBOL subroutine) 55SMQGET (COBOL subroutine) 53SMQPUT (COBOL subroutine) 51SMQVERS (COBOL subroutine) 56storage

creating 102releasing 102

storage, releasing 104symmetric key reuse 74, 102

Java 115symmetric keys

description of 20reusing 102

Ttelephone support

customer service 160thread contexts 74thread-aware programs 74trailer types 58TRAILER_INFO_EX structure 89TRAILER_INFO_EX variables 89Triple-DES algorithm 19

Uuser key database reason codes 156

Vvariables, MQS_APICONTEXT 75verify 67verify signature


verify signature (multiple destinations)C/C++ 71COBOL 39Java 120

verify signature (multiple trailers)C/C++ 67COBOL 37Java 119

version helper functionC/C++ 100

version helper function (integrated)C/C++ 109COBOL 56

versioning 74, 102

WWebSphere MQ message format 94WebSphere MQ MQGET 27WebSphere MQ MQPUT 27

pathwai™ secure for websphere mq pr ... -...

Documents