Creating and Managing Certificates for

My webMethods Server

Version 8.2 and Later

November 2011

Contents
Introduction...................................................................................................................................................4
Scope.......................................................................................................................................................... 4
Assumptions ............................................................................................................................................ 4
Terminology ............................................................................................................................................. 4
File Formats .............................................................................................................................................. 5
Truststore Formats............................................................................................................................... 5
Keystore Formats................................................................................................................................. 6
Key/Certificate Formats ...................................................................................................................... 6
About My webMethods SSL Readiness................................................................................................ 6
Creating Certificates.....................................................................................................................................6
Tools .......................................................................................................................................................... 6
Java 1.6 - Keytool ................................................................................................................................. 6
OpenSSL................................................................................................................................................ 6
PKCS12Import ..................................................................................................................................... 7
Portecle.................................................................................................................................................. 7
Generating a Self-Signed Certificate ..........................................................................................................7
Generate a Private Key ........................................................................................................................... 7
Generate a Signing Request.................................................................................................................... 7
Remove the Passphrase from the Private Key..................................................................................... 8
Generate a Self-signed Certificate ......................................................................................................... 8
Import the Certificate into a Java Keystore .......................................................................................... 8
Package the PEM certificate and Private Key as PKCS#12 (PFX) ..................................................... 8
Import the Private Key and Public Certificate into the Java keystore.............................................. 8
Results ....................................................................................................................................................... 9
Generating A Certificate Chain for My webMethods Server .................................................................9
Creating an Internal Certificate Authority........................................................................................... 9
Create a Signing Request and Signing the Request .......................................................................... 10
Generate a Java Keystore...................................................................................................................... 10
Install the Internal CA Public Certificate ........................................................................................... 11

Copyright 2011 Software AG, Darmstadt, Germany and/or Software AG USA, Inc., Reston,
VA, United States of America, and/or their licensors.
Detailed information on trademarks and patents owned by Software AG and/or its subsidiaries is
located at http://documentation.softwareag.com/legal/.
Use of this software is subject to adherence to Software AGs licensing conditions and terms.
These terms are part of the product documentation, located at
http://documentation.softwareag.com/legal/ and/or in the root installation directory of the
licensed product(s).
This software may include portions of third-party products. For third-party copyright notices and
license terms, please refer to "License Texts, Copyright Notices and Disclaimers of Third Party
Products." This document is part of the product documentation, located at
http://documentation.softwareag.com/legal/ and/or in the root installation directory of the
licensed product(s).

Introduction
Secure Sockets Layer (SSL) is a set of cryptographic protocols that provide communications over
a network, the most important of these networks being the public internet. SSL and its successor
TLS (Transport Layer Security) are based on IETF standards. Enabling an SSL/TLS connection
ensures secure communications between a client and a server.
This article provides information to enable you to:

Create the certificates and keys needed by My webMethods Server for SSL.

Create a Java keystore and import a certificate into a Java keystore.

Create a certificate chain.

This article does not address general SSL configuration for My webMethods Server. For
information about specific SSL configuration procedures, see the chapter Using My
webMethods Server as an HTTPS Client in the 8.2 and later PDF publication Administering My
webMethods Server. This document is available in the webMethods section of the Software AG
Documentation Web site. You can also install webMethods product documentation on your local
file system with the Software AG Installer.
Available information in Administering My webMethods Server includes:

Importing CA Certificates.

Replacing Keystores if My webMethods Server Runs as an Application.

Replacing Keystores if My webMethods Server Runs as a Service.

Generating an Encrypted Password.

Communicating with webMethods Applications Using HTTPS.

Managing Authentication Certificates as My webMethods Administrator.

Scope
The My webMethods Server-specific portions of this article apply to version 8.2 and later.
General information about creating certificates and keystores can be applied to any SSL
installation.

Assumptions
This article assumes that the configuration is being performed on a UNIX platform by an
experienced and qualified administrator. A qualified security administrator should be able to
adapt the instructions for Windows if needed.

Terminology
The following terms are used in this document and are also used in the webMethods suite
documentation.

Certificate. This is an electronic document primary used to provide a public key. The
server provides the certificate/public key to a client requesting a connection (for example,

a web browser). The client uses the public key to encrypt the data being sent to the
server. The server also holds a private key, known only to the server, and only that key
can decrypt the client data that was encrypted with the public key. In addition, the
certificate provides information about the Certificate Authority (CA) that signed the
certificate. The certificate is tamper-proof so that if any byte in the file is changed, the
certificate becomes invalid. The format of the file is known as X.509.

Truststore. This is a repository of trusted certificates. A trusted certificate is a certificate

signed by an external Certificate Authority (for example, VeriSign) that is known to be a
trusted entity. Any additional certificates from these trusted CAs are implicitly trusted as
well. A certificate from a top-level CA cannot be attested to by some other higher CA
(there being none), so that certificate is a root certificate. Such certificates are also termed
"self-signed." The Java documentation refers to each certificate entry in the truststore as
being a trusted certificate entry.

Keystore. A keystore is repository similar to a truststore, except that it contains one or

more pairs of signed certificate (the public key) and a private key, plus any intermediary
keys. The Java documentation refers to each keystore entry as being a key entry.

Java Keystore. This is a repository of certificates and keys in a format that is specific to
Java. The format of the file is referred to as JKS. The Java keystore typically contains
certificates and keys, and these are added, updated, and removed using a utility called
keytool. It is also possible to update the repository programmatically, for example, to add
private keys.

OpenSSL. This is an open source implementation of the SSL and TLS protocols. It also
comes with the utility openssl, which can be used to create and convert certificates.
OpenSSL normally comes in source form, although there is a binary distribution for
Windows. Most UNIX distributions have a version included with the base operating
system, but if you want the latest version, it must be downloaded and compiled.
OpenSSL may also come with the Perl-based helper utility CA.pl that you can use to
create a root CA and have it sign certificates.

File Formats
SSL certificates and keys come in a variety of formats; however, there are a few established
common formats that are frequently encountered.

Truststore Formats
As mentioned previously, the truststore is a collection of trusted certificates. Certificates contain
only public keys. Two common formats are:

PEM or CER files. These are individual X.509 certificates. These are the formats
normally produced by certificate authorities. Other file extensions include .CRT and
.KEY.

JKS files. This is a Java keystore which can contain multiple X.509 certificates. It
associates each certificate with an alias.

Keystore Formats
As mentioned previously, the keystore contains one or more collections of public keys and a
private key. Two common formats for this are:

PFX or P12 files. These are binary format files that contain the public key, the private
key, and any intermediate key.

JKS files. This is a Java keystore containing the same keys and certificates as a PFX or
P12 file. Creating a keystore with private keys is not straight forward, but there are tools
available to aid in creating these.

Key/Certificate Formats
My webMethods Server uses JKS as the keystore format.

About My webMethods SSL Readiness

By default, when My webMethods Server is installed, it is created with a self-signed trusted
certificate and keystore, meaning you do not have to carry out all of the procedures below to
implement SSL. The complete set of procedures is provided below in the event you want to create
additional certificates or keystores.
For more information, see the PDF publication Administering My webMethods Server available in
the webMethods section of the Software AG Documentation Web site.

Creating Certificates
Generally, each Software AG customer is responsible for creating the required certificates. This
section describes how to create a self-signed certificate from start to finish, and how to convert
and create all the required file formats.

Tools
The following tools are required to generate the truststores and keystores:

Java 1.6 - Keytool

A Java Runtime installation (JRE) or a Java Developer installation (JDK) must be installed. If you
have webMethods suite products installed, then a Java runtime is already installed. The Java
\bin directory contains the keytool utility. Type keytool help in a command line to obtain a full
list of options for using keytool.

OpenSSL
OpenSSL is an open source project that implements SSL and TLS protocols. It contains the
openssl utility.
OpenSSL is available from http://www.openssl.org/. It is dowloadable in source form only and
must be compiled. However, many UNIX distributions already contain a pre-built copy of
OpenSSL. Otherwise, you must obtain and compile the source code.
For Windows installations, you can obtain a downloadable pre-built binary distribution from
http://www.slproweb.com/products/Win32OpenSSL.html.

PKCS12Import
There are several variations of this tool available. It is written in Java so it will run on any Javabased platform. If you have My webMethods Server installed, the Jetty implementation within it
contains a copy of this tool. The PKCS12Import.jar is also installed with other sever applications
(for example, GlassFish.

Portecle
This is a user-friendly GUI application for creating, managing, and examining keystores, keys,
certificates, certificate requests, certificate revocation lists, and more. This tool is Java-based and
works on Windows as well as UNIX operating systems that have a graphic user interface.
The instructions in this article are based on the command-line based tools and not on Portecle.
However, should you choose to use it, the tool can be obtained from
http://portecle.sourceforge.net/; documentation can also be found there.

Generating a Self-Signed Certificate

The following steps provide instructions to create a self-signed certificate and keys, and to
convert them into formats expected by webMethods products.
When you are prompted for a password, you are advised to use the same password consistently
throughout. Ensure that the password conforms to accepted strong password standards.
A separate set of certificates must be generated for each product.
Important: The command line syntax presented throughout the following sections uses the
convention of a backslash character (\) to indicate that the command continues into the next line.
Do not type the backslash character when entering the command.
First, create a certificate directory for each product you want to work with:
cd /home/webMethods
mkdir p ./certificates/<product>

Generate a Private Key

Use the following command to generate an RSA Private Key with 1024 bits (you will be
prompted to supply a passphrase):
openssl genrsa -des3 -out private_server.key 1024

Generate a Signing Request

Use the following command to create a signing request that will be self-signed later. You will be
prompted to provide a variety of values such as country, state, and so on. The most important of
these fields is Common Name. For My webMethods Server, enter the fully qualified host name
as the Common Name:
openssl req -new -key private_server.key -out signingrequest.csr

Remove the Passphrase from the Private Key

Use the following commands to strip out the passphrase from the private key:
cp private_server.key private_server.key.orig
openssl rsa -in private_server.key.orig -out private_server.key

Generate a Self-signed Certificate

Use the following command to request create a self-signed certificate, valid for one year. The
(trusted) self-signed certificate is named server.pem:
openssl x509 -req -days 365 -in signingrequest.csr -signkey \
private_server.key -out server.pem

Import the Certificate into a Java Keystore

Use the following command to import the generated certificate into a Java keystore and associate
it with an alias; in this command it is named mykey, but you can substitute a different value.
The name of the truststore keystore is server.jks. You will be prompted to supply a Java
keystore password, and to verify that you trust that certificate (yes):
keytool -import -file server.pem -keystore server.jks \
-alias mykey -trustcacerts

Package the PEM certificate and Private Key as PKCS#12 (PFX)

Use the following command to package the public certificate (with the public key) and the
private key into a binary format called PKCS#12, referred to as the keystore (it is the server that
uses this keystore). The name of the PKCS#12 keystore is certificate.pfx :
openssl pkcs12 -export -out certificate.pfx -inkey private_server.key \
-in server.pem

Import the Private Key and Public Certificate into the Java keystore
The Java keytool utility cannot import private keys. To do so, you must use an external tool that
uses the Java Cryptography API, and an instance of PKCS12Import is required. You will be
prompted for passwords, but be cautious as the passwords are echoed to the screen. Use one of
the following methods:

If you have My webMethods Server installed, the Jetty implementation within it contains
a version of PKCS12Import. Use the following command:

CLASSPATH=/opt/softwareag/MWS/lib/ext/jettyutil.jar:/opt/softwareag/MWS/lib/ext/jetty.jar
export CLASSPATH
java org.mortbay.jetty.security.PKCS12Import \
certificate.pfx certificate.jks

If you have a separate instance of PKCS12Import.jar (for example, from GlassFish), you
can use this command. The Java-keystore-based keystore is named certificate.jks:

java -classpath pkcs12import.jar com.sun.xml.wss.tools.PKCS12Import \

-file certificate.pfx -alias mykey -keystore certificate.jks

Results
The above steps result in the creation of the following four files:

server.pem - Trusted Certificate

server.jks Trusted Certificate in a Java Keystore format

certificate.pfx Keystore in PKCS#12 format

certificate.jks Keystore in a Java Keystore format

Generating A Certificate Chain for My webMethods Server

For external websites that need to be secured, an external Certificate Authority (CA) such as
VeriSign is engaged to sign your certificate requests. Virtually all browsers will have a copy of
their public certificates. The browser downloads the certificate from a website, determines the
authority that signed it, and if the signing authoritys certificate is in the browsers list of trusted
certificates, then the website is also trusted (provided other aspects of the certificate are also
valid). Otherwise, the browser displays a message that that there is a certificate problem.
For internal use, you can dispense with engaging an external CA, as it is possible to set up an
internal organizational CA. Provided that the public CA certificate is installed in all connecting
browsers, then anything signed by the internal CA will be trusted as well.
This section provides brief instructions about how to:

Create an internal certificate authority.

Create a signing request and get that signed by the internal CA.

Generate a Java keystore for use by My webMethods Server.

Install the internal CA certificate and test My webMethods Server.

Creating an Internal Certificate Authority

This procedure requires a Perl script (CA.pl) that can be downloaded from various sources on the
internet if it is not part of the OpenSSL installed on your system. For Windows platforms, a Perl
interpreter is also required.
The CA.pl script creates a directory named demoCA, and also generates the private and public
keys for the root CA.
1.

Create a directory that will hold all of the Internal Certificate Authoritys files by running the
Perl script with the following command:
/usr/local/openssl/CA.pl newca

2.

Create a copy of the public key with just the certificate:

cp demoCA/cacert.pem demoCA/myca.pem

3.

Open the key file for editing:

vi demoCA/myca.pem

4.

Delete everything above -----BEGIN CERTIFICATE -----.

5.

Save the file.

Create a Signing Request and Signing the Request

Next, create a signing request and sign it using the internal root CA.
1.

In the demoCA directory, create the signing request:

cd demoCA
openssl req -new -nodes -keyout private/server.key \
-out server.csr -days 365

2.

Then sign it using the root CA:

cd ..
openssl ca -config openssl.cnf -policy policy_anything \
-out demoCA/certs/server.crt -infiles demoCA/server.csr

3.

After the certificate is signed, the signing request (demoCA/server.csr) can be deleted.

Generate a Java Keystore

You now have a copy of the private and public keys for both the root CA and the server. A Java
keystore must be created to contain the private and public key for the server and the public root
CA certificate. This involves creating a PKCS#12 file and importing that into a Java keystore
using PKCS12Import. Use these commands:
openssl pkcs12 -export -out certificate.pfx inkey \
demoCA/private/server.key -in demoCA/certs/server.crt -certfile \
demoCA/cacert.pem
CLASSPATH=/opt/softwareag/MWS/lib/ext/jettyutil.jar:/opt/softwareag/MWS/lib/ext/jetty.jar
export CLASSPATH
java org.mortbay.jetty.security.PKCS12Import certificate.pfx \
certificate.jks
keytool -import -file demoCA/myca.pem -keystore \
certificate.jks -trustcacerts

The result of this is that you have a file (certificate.jks) that you can install into My webMethods.

Install the Internal CA Public Certificate

To enable a browser to trust the certificate coming from My webMethods Server, you must install
the root CA certificate into the browsers trusted cache.
1.

Copy the public certificate (myca.cer) to the file system on the system where the browser is
running. Then install the certificate:

Mozilla Firefox: Tools > Options > Advanced tab > Encryption tab > View Certificates
> Import. Browse to myca.cer and click This certificate can identify web sites. Click
OK.

Internet Explorer: Tools > Internet Options > Content Tab > Certificates > Import.
Follow the wizard: Click Next. Browse to myca.cer then click Next. Under Place all
certificates under the following store, click Browse. select Trusted Root Certification
Authorities. Click Next and then click Finish. You are warned that Internet Explorer
cannot validate the certificate. Click Yes to install.

Opera: Menu > Settings > Preferences > Advanced tab > Security. Click Manage
Certificates. Click the Authorities tab, then click Import. Browse to myca.cer, and then
click Install. Click OK.

Chrome: Click the tool icon (top-right, to the right of the address bar). Click Options.
Select the Under the Hood tab. Scroll down to the Security section and click Manage
Certificates. Select the Trusted Root Certificate Authorities tab then click Import.
Follow the wizard: Click Next. Browse to myca.cer then click Next, click Next, then click
Finish and Close.