2007/02/15
15 Feb, 2007

OpenSSL Tutorial for Apache Rampart/C

  • Malinda Kaushalye
  • Tech-lead - WSO2

For example, installing OpenSSL, obtaining certificates, how to configure a key store, etc. You are always welcome to refer to OpenSSL documentation and other related resources, but it usually takes time to connect them together. We suggest that you to complete this tutorial before configuring Rampart/C.

X509 Certificates, Public and Private Keys in Brief

In public key infrastructure we use two keys, namely Public key and Private key. The relationship between these two is that one encrypts data, and the other decrypts it. The difference is that one is kept a secret (hence named private key) whilst the other is published. An x509 certificate is issued by a certificate authority binding such a public key. A Certificate Authority (CA) is a trusted third party that issues digital certificates for other parties. In Rampart/C, we use X509 certificates to encrypt messages and corresponding private keys to decrypt the messages.

Ways You Can Use Certificates/Keys in Rampart/C

There are two ways you can use x509 certificates and keys.

  1. As a single entity - PEM format
  2. In a Key Store - PKCS12 format

PEM Format

Privacy Enhanced Mail (PEM) is the widely used format for certificates and keys. A PEM file contains two header lines that wraps base64 encoded certificate data. The format of a X509 certificate is as follows.

------BEGIN  CERTIFICATE-----
(Base64 encoded certificate data)
------END CERTIFICATE----

If you need to configure the receiver's certificate to encrypt data, you have to have it in PEM format.

PKCS12 Key Stores

PKCS12 is a standard that stores certificate and private key pairs in a secure way. Usually, a certificate/key pair is stored with a password. Unlike a PEM file, PKCS12 contains binary data and may contain more than one certificate. OpenSSL provides tools to convert from/to PKCS12 format. We will describe how to do this later. Rampart/C supports PKCS12 key stores. The file extension should be .pfx.

Installing OpenSSL

UNIX

The quickest and easiest way to install OpenSSL in your system is through the Advanced Package Tool (apt).

%apt-get install openssl.

This will install the latest OpenSSL version available in your system.

The other way is to download the tarball from the OpenSSL official Web site. For example, if you have downloaded openssl-0.9.x.tar.gz, extract it first.

%gunzip  openssl-0.9.x.tar.gz
%tar xvf openssl-0.9.x.tar

Then go to the directory openssl-0.9.x.

To install it in the default location (i.e./usr/local/ssl), use the following command sequence.

%./config
%make
%make install

Win32

There are many vendors who provide binary distributions of the latest OpenSSL release. You can then follow the installation procedure, which is vendor specific.

Obtaining a Certificate

There are three methods to obtain an x509 certificate.

  1. Generate a self-signed certificate.
  2. Signed by a local CA
  3. Signed by a recognized authority such as Verisign

Generate a Self-Signed Certificate

This is the simplest procedure, but is of very little use. For testing purposes you might need to generate a certificate quickly. Use the following command to generate a self-signed x509 certificate (mycert.pem), which is valid for 365 days and an RSA key (mykey.pem) of length 1024.

openssl req -x509 -nodes -days 365 -newkey rsa:1024 \
-keyout mykey.pem -out mycert.pem

Then you have to answer a few questions. The information you provide by answering these questions will be stored in the certificate.

Country Name (2 letter code) [AU]:
State or Province Name (full name) [Some-State]:
Locality Name (eg, city) []:
Organization Name (eg, company) [Internet Widgits Pty Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:
Email Address []:

Create Your Own CA and Sign Your Certificates

A self-signed certificate is of no use as it is not signed by a third party. There are well known third parties like Verisign and Thawte. However, getting a certificate signed is a complex and costly process. If you need to form a small trust community (e.g. for your company or with your clients) you can create your own Certificate Authority. This process has been simplified thanks to a pearl script available in OpenSSL distribution. If you have used default installation settings, this script (CA.pl) can be located in /usr/lib/ssl/misc/CA.pl. First create a directory for your CA. Then copy CA.pl and /usr/lib/ssl/openssl.cnf to the directory you just created. Now run the CA.pl script.

%./CA.pl -newca

If you press Enter, the script will create a new certificate/key pair for you. If you already have a certificate and you need to use it, just type the filename. Now you have a certificate authority setup in a sub directory called "demoCA". Simple, right?

Let's try to sign a certificate using the CA we have just set up. Copy your certificate request to the current directory and rename it to newreq.pem (In the next section, we will discuss how to generate a certificate request). Next, issue the following command.

%./CA.pl -sign

If everything is successful and the request is a valid one, a new certificate called newcert.pem will be created in the same directory.

Sign Your Certificate by a Recognized Authority

Signing you certificate by a recognized certificate authority consists of two steps. First you have to generate a certificate request locally. Then you need to fill a form providing some information and send it to the CA.

Here we describe how to generate such a request using OpenSSL. First you need to generate a private key. If you already have a private key skip this step.

%openssl genrsa -out x.key 1024

Then use that private key to generate your request to the CA.

%openssl req -new -key x.key -out request.pem

This will create a file called request.pem from the private key (x.key). The requset file has the following format.

-----BEGIN CERTIFICATE REQUEST-----
(Base64 encoded certificate request data)
-----END CERTIFICATE REQUEST-----

Then you have to provide your information to the certificate authority. Usually this can be done by sending a fax or by filling an online application. Make sure that you are sending accurate information and especially check your request and the information in it. Use the following commands for verification.

%openssl req  -noout -text -in  request.pem
%openssl req -noout -verify -key x.key -in request.pem


Exporting PEM Files to PKCS12 Key Stores

Use the openssl pkcs12 tool to export a certificate/key pair to a pkcs12 store. Assume that you have a key (x.key) and a certificate (x.cert). The first step is to have both of them in a single file (x.pem). Then export the pair to a pkcs12 keystore (x.pfx).

%cat x.cert x.key > x.pem
%openssl pkcs12 -export -in x.pem -out x.pfx

Then enter a password to secure your keys in the keystore.

Extracting Key/Cert Pair from a PKCS12 Key Store

If you have your keys/certificates in a pkcs12 keystore, you might need to extract them. For example, you might need to give you certificate to another party. Here, we will show you how you can do this.

%openssl pkcs12 -in x.pfx -clcerts -nokeys -out x2.cert

Enter the password you used in the export process. Similarly, you can get the private key too.

%openssl pkcs12 -in x.pfx -nocerts -out x2.key

Extract Information from a Certificate

If you get a certificate from another party, you might need to extract information from it. An x509 certificate contains the following information.

  • Certificate version
  • Serial Number
  • Algorithm ID
  • Issuer
  • Validity period
  • Subject
  • Public Key Algorithm
  • Subject Public Key
  • Issuer Unique Identifier (Optional)
  • Subject Unique Identifier (Optional)
  • Extensions (Optional)
  • Certificate Signature Algorithm
  • Certificate Signature

Use the following command to extract information from a certificate in PEM format.

%openssl x509  -noout -text -in  x.cert

To extract information from a certificate, which is stored in a pkcs12 key store, use the following.

%openssl pkcs12 -in x_store.pfx -nokeys -clcerts | openssl x509 -noout -text

Glossary

  • PKCS12 : Public Key Cryptography Standards #12. Personal Information Exchange Syntax Standard.
  • PEM: Privacy Enhanced Mail, is a standard for exchanging mails over the web in a secure way.
  • X509: A standard for Public Key Infrastructure, defines formats for public key certificates and validation algorithms.
  • CA: An entity issuing and validating digital certificates.


References

Author

Malinda Kaushalye Kapuruge is a Software Engineer, WSO2 Inc. kaushalye at wso2 dot com

 

About Author

  • Malinda Kaushalye
  • Tech-lead
  • WSO2 Inc.