Mission:Messaging: Scripted WebSphere MQ key file management for UNIX and Windows

Although the iKeyman GUI makes interactive key management easy, human-driven processes are time consuming, can be prone to errors, and might not produce consistent results. Scripts address all of these issues. In addition, command line tools provide easy access to advanced options, such as FIPS compatibility and choice of signature algorithm. Whether you have a large deployment or just a few queue managers, when it comes to key management, scripts are the key to quality, consistency, repeatability, and efficiency. This content is part of the IBM WebSphere Developer Technical Journal.


T.Rob Wyatt, Senior Managing Consultant, WSO2 Inc

T.Rob WyattT.Rob Wyatt is a Senior Managing Consultant with IBM Software Services for WebSphere who assists customers with the administration, architecture, and security of WebSphere MQ. Recently he has focused on WebSphere MQ security, publishing in the IBM WebSphere Developer Technical Journal and presenting at the IMPACT and European Transaction and Messaging conferences. T.Rob also hosts The Deep Queue, a monthly WebSphere MQ security podcast.

developerWorks Professional author

24 June 2009

Also available in Chinese

A case study in scripted key management

A recent consulting engagement included a task to set up SSL channels between two queue managers. The standard operating procedure at this shop was to use interactive tools for nearly all administration tasks, and so my client had assumed that we would be using the iKeyman GUI for the creation of the keyrings and for all of the certificate tasks. They were a little reluctant when I suggested that we use scripts instead.

Their main objection was general unfamiliarity with scripting tools amongst the administration team. There was an underlying concern that a scripted solution would raise the minimum skill level needed to manage certificates. By comparison, the GUI was perceived as the easier and more expedient solution.

Beyond that, there was also a question of whether this was the best use of resources. I told my client up front that writing the scripts would take at least the same amount of time -- perhaps more -- as it would to walk their administrators through the same tasks using the GUI. The value of scripting is readily perceived in a large deployment, but with only two queue managers involved, the extra investment here was perceived as a waste of time.

Ultimately, it was business requirements that drove the decision. Since MD5 hashing has been broken, the client wisely stipulated that all keys must be signed using SHA-1 instead. The GUI tools do not expose controls that enable selection of the certificate signing algorithm, and they default to MD5 signatures. Changing that behavior in the GUI requires editing the iKeyman and Java™ configuration files. By comparison, the command line tools include the –sigalg option, which makes selection of the signature algorithm a trivial task.

When we finally got started, the client’s fears proved to be unfounded. The scripts are largely self-documenting and do not require sophisticated logic. They consist of nothing more than a commented list of commands with no branches or loops. Learning the scripts was just as easy for the administrators -- perhaps even easier than learning the GUI would have been. Also, our resource commitment was quite low since I already had some scripts from a previous assignment that were nearly perfect for what we needed.

We completed the SSL configuration in under three hours, and that included tailoring the scripts and training the staff on key management tasks. After about a month, the queue managers were migrated to new servers and rebuilt. The administrators were able to reuse the scripts we had created to set up SSL channels on the new queue managers in under an hour – unassisted -- using a process that is repeatable, consistent, and error-free. Our investment was recouped entirely with the first reuse.

In this installment of Mission:Messaging, I will walk you through the tasks to configure basic SSL channels with self-signed certificates, building two scripts as we go. Then, when it’s time to set up IBM® WebSphere® MQ SSL channels in your shop, you should be able to get your first channel pair up and running in under an hour as well.

First, a word about certificate types

The process to configure SSL with CA-signed certificates is similar to that for self-signed certificates, but the security policies created differ dramatically.

When using self-signed certificates, a policy of Deny-All is created. Each certificate added to the key ring is an exception to this policy. Granting access requires adding a certificate. Revoking access requires deleting a certificate. With self-signed certificates the MQ administrator must take specific action to grant access for a given certificate. All access control decisions rest with the administrator.

With CA-signed certificates, the effective policy is Allow-All for each trusted CA (Certificate Authority). In other words, adding a CA to a keyring establishes a trust policy for every certificate that CA has ever signed or will sign in the future. Narrowing down the scope of that trust requires use of the channel’s SSLPEER attribute to specify acceptable values for the Distinguished Name (DN) fields within the certificate. Revoking access requires a Certificate Revocation List, also known simply as a CRL. When a CA revokes a certificate, the action is published to a CRL. Customers of that CA mirror the CRL internally, where it can be checked by the queue manager when the channels start. If a channel start is attempted using a revoked certificate credential, the check of the local CRL copy will generate a hit and the connection will be refused.

With CA-signed certificates, the MQ administrator controls only the string matching template for Distinguished Names (DN) that are allowed to connect. Any new certificate issued by the CA with a matching DN value will be able to connect. The only control available to prevent this is the CRL. When using CA-signed certificates, maintaining CRL is considered mandatory because it is the only mechanism with which to exclude a certificate that has been compromised.

Many discussions of SSL characterize the choice of certificate types based on the cost or the process involved. Frequently, the approach is to prototype with self-signed certificates because they are free and easily generated, then switch to CA-signed certificates in later stages. The choice should really be made based on the desired security policy and whether the enterprise is prepared to set up and maintain a certificate revocation list. From a security perspective, it is generally better to start with a Deny-All policy and grant exceptions than to start with an Allow-All policy and build a blacklist. For these reasons, I prefer self-signed certificates and these are what will be discussed here.

Process overview

For the purpose of this article, consider two queue managers, which I will refer to as QMA and QMB. At a high level, building a new WebSphere MQ SSL configuration with self-signed certificates requires these steps:

  1. Create the default keyring for QMA.
  2. Delete the default CA certificates from the keyring.
  3. Generate a self-signed certificate for QMA.
  4. Extract the public key of the new certificate.
  5. Repeat steps 1 through 4 for QMB.
  6. Import the public key of QMB into the keyring for QMA.
  8. Repeat steps 6 and 7 for QMB.

Steps 1 through 4 are required for any new queue manager and are a natural choice for a single script. Although steps 6 and 7 could be scripted, there are times when it is necessary to import many public keys into a keyring, and not necessarily a good idea to issue a REFRESH SECURITY after each one. So, step 6 will be a script unto itself. We will document the requirement to issue a REFRESH SECURITY command, which can be executed from the command line or from your favorite administrative tool as you see fit. But this is largely a matter of personal preference, so feel free to add REFRESH SECURITY as the last step of the second script if you like. Once we get into the scripts, there are a few additional details, which I’ll cover as we go.

Common script headers

Although this article covers only a very small subset of key and certificate management tasks, the intent of scripting is to create reusable tools. For this reason, each script will contain a header in which you will set any variables necessary to execute the line commands.

Reusability also influences where you will be working with keyring files. For one-time use, it would be easier to build the keyrings in a local temporary directory, generate and exchange the certificates, and then move the finished keyring files to their final destinations. But you cannot generate a fresh keyring from scratch every time you want to add a certificate and, unless you have a secure deployment server and some really good automation, it is not practical to maintain a central repository of keyrings and push them out to your queue managers after performing maintenance. To be reusable, your script will need to manipulate the keyrings where they are actually used. This will require you to embed several file and path elements into your common script headers. Let’s take a look at those now.

Because it is customary for the queue manager name to be included in the certificate’s Common Name field, you will need a variable to hold it:


To complete the distinguished name of the certificate, a domain is usually required:


You will also need several organization and location fields. I have lumped these together in a single variable, called ORG:


The lower-case version of the queue manager name is required for the certificate label. This is what the queue manager looks for so it can locate the certificate it will present during an SSL negotiation:


You also need to know where the queue manager lives in the file system. WebSphere MQ will mangle certain characters in order to create platform-portable file names. For example, if a queue manager name contains a dot character, this is converted to an exclamation point. If your queue manager name contains any characters other than alpha-numeric, you will need to look in the file system to determine the mangled name and set that value here:


The script should be useable for non-standard installations, and in particular when the queue manager is implemented on a high-availability hardware cluster. The PATH2QMGR variable is used to hold this location.


The same variable on a Windows® system would have this value, assuming a default installation:

PATH2QMGR=C:\Program Files\IBM\WebSphere MQ

The password to the keyring is stored in the script as a user-editable environment variable. Be sure not to leave the script lying around with the password saved. A good place from which to save and run the script is in the queue manager’s SSL directory. This directory must be protected so that only the mqm (or platform equivalent) user ID can read the files. Since the key database password is stashed here, there is no additional exposure in storing the script here as well:


The password must not contain embedded spaces or special shell characters. If you want to generate a really strong password, try the Perfect Passwords generator at Gibson Research Corporation.

Password expiry is only used once but I like to create a variable for it and place the variable with the other user-edited fields. This calls out to the script operator the fact that a policy decision is captured here. The value is in days and I’ve specified a 10-year expiry for this example:


The command we will be using here is the GSKit C API command and not the Java implementation. This is because the C version exposes some options on the command line that are not available in the Java version. As an added benefit, the C executable is much faster because the Java version must build and tear down a JVM for each command invocation. The entire C-based script can run in the time it takes a single command to execute with the Java version. To make this work, the script just needs to know the path to the C binaries. For UNIX® systems, the default location is in /opt:


On Windows systems, the default is on the C: drive:

PATH=C:\Program Files\IBM\gsk7\bin:C:\Program Files\IBM\gsk7\lib:%PATH%

That was the last of the user-editable variables. Before running any commands though, you need to tell the script the name of the keyring file. That is built using a combination of the default WebSphere MQ settings and the variables entered in the previous steps. For UNIX and Windows, respectively, those variables are:



These locations are the default and should already be present in the queue manager’s SSLKEYR attribute. If alternate locations are chosen, be sure to update the queue manager accordingly.

The settings above can be used for any certificate management script. Some of the command invocations will require different or additional parameters, but the implementation stays the same: put the user-editable variables together up front where they can be managed as a set.

Create the keyring and remove the default CA entries

The next step is to generate the keyring in its default state. This requires a single gsk7capicmd command invocation:

gsk7capicmd -keydb -create -db "$MQSSLDB" -pw $PASSWORD -type cms -expire $EXPIRY -stash -fips


  • The first gsk7capicmd parameter is the type of operation to be performed. In this case, a key database operation.
  • The second parameter is always the action to be performed within the operation type. Here, we intend to create a new key database which is pointed to by the fully-qualified –db option.
  • The database type is specified as cms because this is what the queue manager requires.
  • The –stash option creates a stash file with the password. This is how the queue manager is able to access the key database without human intervention.
  • Finally, the –fips option is specified. This not only generates a key database compliant with Federal Information Processing Security standards, but it also insures that the libraries and algorithms used when the command runs are FIPS compliant. I do not know of any negative impact to specifying use of FIPS-compliant commands and they do have the potential benefit of having been independently certified. Until I hear of a good reason not to use them in all cases, my policy is to always specify FIPS.

When the keyring is first created, it will be loaded up with a number of default CA signer certificates. Currently, these include root certificates from Entrust, Verisign, Thawte and RSA. As we saw earlier, the presence of these root CA certificates creates an Allow-All policy for every certificate that CA has ever issued or will ever issue in the future. Since we are using only self-signed certificates, all of these root certificates represent inappropriate access grants to our queue managers. Accordingly, the next step is to delete all of the default CA certificates.

The list of certificates changes over time. The specific certificates used here are from a V6.0 queue manager. Depending on your version and fix pack, the list you see could differ slightly. To insure that all of the CA certificates have been deleted, you will include a command to display all certificates in the keyring toward the end of the script.

The command to delete a certificate looks like this:

gsk7capicmd -cert -delete -label "Entrust.net Global Secure Server Certification Authority" -db "$MQSSLDB" -pw $PASSWORD -fips

The –label option identifies the certificate by a human-readable string. The label must be unique within a keyring and it is set when a certificate is created or imported. The same certificate could have different labels in different keyrings. In this case, the label identifies the specific certificate to be deleted.

I’ve only listed one example here. The full script listing contains twenty-four additional commands that remove root and intermediate certificates of the various vendors.

Generate the local queue manager’s certificate

The next step is to generate the new certificate for the local queue manager. The queue manager locates its certificate based on the label, which must always be the fixed string ibmwebspheremq followed by the queue manager’s name folded to lower case. In the example below, the label is derived by concatenating the fixed portion of the label with the $FOLDEDNAME variable set in the script header:

gsk7capicmd -cert -create -db "$MQSSLDB" -pw $PASSWORD -label "ibmwebspheremq$FOLDEDNAME" -dn "CN=$QMGRNAME.$DOMAIN,$ORG" -fips

This command introduces another new option, the Distinguished Name of the certificate, which is abbreviated as DN. The DN is a globally unique name representing the entity represented by the certificate. It is composed of several sub-fields, including:

  • CN=common name
  • O=organization
  • OU=organization unit
  • L=location
  • ST=state, province
  • C=country

It is important to note here that the scope of "globally unique" is per issuer. It is perfectly valid for two or more certificate authorities to issue certificates with the same DN component. In the case of a self-signed certificate, each certificate is its own root and the only enforcement of global uniqueness will be the controls you build around the human processes for issuing and managing certificates.

The common name for queue managers is customarily the queue manager name, followed by the domain in which it resides. For example, QMA.us.ibm.com would be a valid CN for our QMA queue manager. The certificate might contain multiple Organization Unit (OU) entries. Careful selection of the OU naming helps to construct meaningful SSLPEER values. For example, if one of the OU entries is PROD or DEV, then it will be possible to construct an SSLPEER that prevents interconnection between production and development queue managers. (The channel’s SSLPEER attribute and Distinguished Names were discussed more fully in January’s Mission:Messaging column, Planning for SSL on the WebSphere MQ network.)

Extracting the new certificate

In order for the new certificate to be useful in an SSL negotiation, the remote queue manager must have access to the certificate’s public key. This is accomplished by extracting it to a file, copying the file to the remote node, and then importing it into the keyring residing there. Extracting the certificate will be the one of the last tasks in our current script, and then you will build a second script to import the certificate file into the remote keyring.

The command to extract the certificate is:

gsk7capicmd -cert -extract -db "$MQSSLDB" -pw $PASSWORD -label "ibmwebspheremq$FOLDEDNAME" -target $PATH2QMGR/$MANGLEDNAME/ssl/$FOLDEDNAME.crt -format ascii -fips

Here, you reuse the previous values for the keyring, certificate label, and password. The –target option identifies the location and name of the file that will contain the extracted certificate. The .crt extension for the file name matches the –format ascii option and will enable you to import the certificate later.

Tidying up

At this point, the work of the script is complete but the human operator needs to verify the results. You need to display the certificates in the keyring and ask the operator to check that no default CA certificates remain. This is required to catch changes that are made between releases of GSKit, which updates the inventory of default certificates:

gsk7capicmd -cert -list -db "$MQSSLDB" -pw $PASSWORD -fips

Second script: Adding certificates to the keyring

The final step is to exchange certificates between QMA and QMB. You will build a second script that will read the .crt file created previously and add it to the keyring of a queue manager. The preamble of the script will reuse many of the variables you used earlier. The only difference will be that the $FOLDEDNAME variable now refers to the remote queue manager and not the local one. The command to add the certificate to the keyring is:

gsk7capicmd -cert -add -db "$MQSSLDB" -pw $PASSWORD -label "ibmwebspheremq$FOLDEDNAME" -file $FOLDEDNAME.crt -format ascii –fips

Notice that the script expects the file name to match the lowercase name of the queue manager and to be in the current directory. It also uses the same standard label for the certificate, even though this is not a requirement. The only time that WebSphere MQ requires the label to be in a specific format is for the queue manager to locate its own certificate. I chose to use the same label to represent a particular certificate across all keyrings because the consistency helps administrators recognize and manage the certificates easier.

As with the first script, the contents of the keyring are displayed to verify the operation has completed successfully.

Wrapping up

The scripts provided with this article are examples of the minimum required to connect two queue managers. The design was such that the first script can be reused on any queue manager to create the keyring for the first time. The second script can be used repeatedly to add in certificates from any remote MQ node. The commands in these two scripts are sufficient to connect a network of any arbitrary size.

Of course, additional scripts can be easily built from these examples by substituting the appropriate commands. Some suggestions for you to try on your own include a script to delete a certificate, a standalone script to list the contents of a keyring, and a script to print the details of any certificate. Eventually, you might need a script to change the password of the key database, depending on the password expiry period used in your shop. Any of these can be created by making minor changes to one of the existing scripts.

The scripts I use are intentionally rather simple. Many of the fields in the scripts could be derived or parsed from the queue manager ini file or from the Windows registry with a little work. But as a consultant, I need tools that will run in the broadest range of environments possible, and which do not make too many assumptions. If you have the luxury of a permanent position, you might want to invest some time to make the scripts easier to use and more robust. Some enhancements you might consider adding would include logic to parse out things such as the location of the queue manager in the file system, or better error handling. The less the script user has to enter, the lower the probability of introducing human error. The better the diagnostics, the less chance of the operator missing an error message and continuing with a broken keyring. I’d be happy to host anything you come up with at t-rob.net, if you are inclined to share.

But whether you keep your scripts simple or enhance them, the automation will help you to implement SSL quickly, easily, and consistently.


Code sample0906_MQ_scriptingsample.zip4 KB



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

Zone=WebSphere, Information Management
ArticleTitle=Mission:Messaging: Scripted WebSphere MQ key file management for UNIX and Windows