Creating and Managing Certificates for My webmethods Server. Version 8.2 and Later

Transcription

1 Creating and Managing Certificates for My webmethods Server Version 8.2 and Later November 2011

2 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 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 Generate a Java Keystore Install the Internal CA Public Certificate... 11

3 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 Use of this software is subject to adherence to Software AG s licensing conditions and terms. These terms are part of the product documentation, located at 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 and/or in the root installation directory of the licensed product(s).

4 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: Scope 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. 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,

5 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.

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

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

8 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

9 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 authority s certificate is in the browser s 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 Authority s 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

10 3. Open the key file for editing: vi democa/myca.pem 4. Delete everything above -----BEGIN CERTIFICATE 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 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.

11 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 browser s 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.