Chapter 1: About This Manual

Certificates and private keys

The AKM solution requires the use of certificates and private keys for client/server authentication during TLS communication. These keys and certificates uniquely identify an instance of the key server, protect the distribution of encryption keys to applications, and secure access to the AKM Administrative Console.

Who is this for?

All AKM deployments generate a full set of authentication certificates, including a private CA, and this is the recommended method of generating certificates. However it is also possible to use manually created certificates with AKM.

This guide is designed for Crypto Officers who wish to manually create, distribute, configure and manage the certificates and private keys that AKM requires for proper operation. The examples in this guide use the OpenSSL application and assume that you are creating a private Certificate Authority. OpenSSL is not required for certificate generation, and you can use another certificate authority or application to create certificates for you.

SECURITY ALERT: Although you can use a public certificate authority such as VeriSign or Thawte, it is recommended not to do so as this creates a security vulnerability where anyone with a certificate signed by this CA would be able to gain access to the AKM server. You should create a CA certificate solely for use by AKM. You can accomplish this by using a private CA such as OpenSSL, the AKM Certificate Manager, or a ready to use implementation of AKM.

Limitations

The OpenSSL application for X509 certificates includes a set of options in a category called “trust settings”. These options are experimental and are not currently supported by Alliance Key Manager.

You must not use a password with ANY private key you install on the AKM server.

Other resources

The following documents provide additional information on the installation and use of Alliance Key Manager:

Change log

The following table provides information on the changes to this documentation:

Version Date Description
2.0.0 1/10/2010 Reformat and revise for AKM version 2.0.0
2.0.1 2/15/2010 Document the maximum CA certificate depth as 3.
2.0.2 11/23/2011 Add information about intermediate certificate authorities.
2.0.1.003 10/13/2012 Added new section on certificate authority compromise.
2.1.13.001 5/28/2013 Update for style and readability.
2.1.13.002 9/26/2013 Updates and corrections.
3.0.0.001 10/1/2014 Update introductory chapters.

Chapter 2: Introduction

Terminology

“Encryption” is the process of transforming data into a form that cannot be understood. The original data is called “plaintext” and the encrypted data is called “ciphertext”. “Decryption” is the reverse process: changing the ciphertext back to plaintext.

The term “encryption” is often used to refer to the entire process of encrypting and decrypting data. The usage should be clear from the context.

Two types of keys: symmetric and asymmetric

“Symmetric keys” encrypt and decrypt data with the same key. Alliance Key Manager creates and manages symmetric encryption keys for use in your organization.

“Asymmetric keys” are created as key pairs. One key is used to encrypt and the other to decrypt. The keys in an asymmetric key pair are referred to as the “public” and “private” keys.

It uses asymmetric encryption keys to protect the distribution of symmetric encryption keys, and for other internal uses.

AKM uses asymmetric keys for the following tasks:

  • Secure the connections between the key server and the Crypto Officer client

  • Secure the connections between the key server and key clients

  • Encrypt exported symmetric keys

  • Decrypt imported symmetric keys

  • Secure server’s key encryption key

  • Secure server’s authentication key

AKM components

The Alliance Key Manager has three components:

  1. Key server: Creates, stores, and delivers encryption keys; Server management front end for administration

  2. Admin (Crypto Officer) client: Creates encryption keys, modify policy, import/export keys, etc.

  3. Key client: Retrieves encryption keys for local encryption and decryption; Sends data for remote encryption and decryption on the AKM server

RSA algorithm

There are many ways to encrypt data. Each type of encryption has an algorithm and a key. The algorithm is published and well understood. If the key is kept secret no one but the holder of the key will be able to decrypt the data.

The asymmetric algorithm used by AKM is called “RSA”. The RSA algorithm uses public and private key pairs.

Key sizes

It is recommended that RSA keys used for TLS session establishment be at least 2048 bits in length.

NOTE: AKM does not support 1024-bit keys for session establishment.

RSA key pairs

Data encrypted with one key in a key pair can only be decrypted with the other key in the pair.

For example, assume we have a key pair “K” and call the public key “Kpub” and the private key “Kpriv”. Data encrypted with Kpub can be decrypted with Kpriv. Data encrypted with Kpriv can be decrypted with Kpub.

If you encrypt with the private key anyone who has the public key can be assured that the data was encrypted by you (the owner of the private key). Public keys are often published so anyone who has access to it will be able to decrypt your data.

If you encrypt with the public key you can be assured that only the owner of the private key will be able to decrypt the data.

Data encrypted with your public key cannot be decrypted with the private key of another key pair. Only the private key associated with the key pair can decrypt the data. The same is true of data encrypted with the private key.

Private keys are stored as files and must be protected and kept secret. Public keys are packaged and distributed in files called certificates.

IMPORTANT: You must NOT use a password when creating a private key used by AKM. A password-protected private key will render the key server inoperable.

You will need to use several key pairs with AKM. See Chapter 3: AKM Requirements below for more detail.

Certificates

When using a public key it is desirable to have a way to determine if the key is valid. To this end public keys are usually packaged with several pieces of information about the key called “metadata”. The file containing the key value and its metadata is called a “certificate”.

Certificates contain the public key value, date ranges for which it is valid, who the certificate is issued to, the identity of the issuer, what the certificate can be used for and a hash of the certificate among other things.

For interoperability purposes, standards bodies have defined how a certificate should be formatted. The certificates used by AKM follow the ITU-T X.509 standard. You can read an overview of X.509 here. There are multiple versions of this standard, the latest being version 3. When we refer to “X.509” we always mean X.509v3.

Public Key Infrastructure (PKI)

The term “public key infrastructure” or “PKI” is used to refer collectively to the all the various components and procedures for using RSA private keys and certificates for security.

Certificate authority (CA)

A “certificate authority” or “CA” is a security group with the software tools needed to create and sign certificates.

There are a number of public CAs who will create certificates for you (for a fee or for free). You can also create your own CA called a “local” or “private CA”.

The CA will do the following for you:

  • Verify your identity

  • Accept a request for a certificate

  • Format the certificate according to the X.509v3 standard

  • Sign the certificate

  • Return the signed certificate

  • Provide you with its certificate for validating the signature

You can learn more about certificate authorities and public key infrastructure here and here.

If you use a public CA, be sure to tell them that you need the signed certificate in PEM format.

If you want to create your own CA and use it to sign certificates, see Appendix A: Setting up a Certificate Authority on Linuxfor instructions for Linux, or Appendix B: Setting up a Certificate Authority on Windows.

Using OpenSSL to Create a private Certificate Authority

This manual uses OpenSSL for the examples of creating private keys and certificates. If you plan to use OpenSSL to create these files, please see Appendix B: Setting Up a Certificate for Use on Windows for information on how to create the Certificate Authority (CA) private key and self-signed certificate.

Intermediate Certificate Authority support

Some certificate authorities allow for the creation of an Intermediate Certificate Authority which can then create certificates and private keys. Examples of CA’s that support the creation and use of intermediate CAs are Entrust and Microsoft Active Directory Certificate Authority (AD CS). Alliance Key Manager supports the use of an intermediate certificate authority. You must install both the Root CA certificate and the Intermediate CA certificate on the AKM server in the CACerts directory. You must also add TrustedCACert entries in your AKM configuration file for both of these certificates. For example (your file names may be different):

TrustedCACert=RootCA
TrustedCACert=IntermediateCA

On the client side you must install the Root CA certificate and set the certificate depth to “2”.

SECURITY ALERT: Using this method will not limit access to the branch of the certificate chain signed by the Intermediate CA certificate. Certificates signed by the root CA certificate will still have access to AKM.

Signature

Broadly speaking a certificate contains the public key value, key metadata, certificate metadata and a signature.

To create a signature, a hash algorithm is selected and the data in the body of the certificate is run through that hash algorithm to get the hash value. The most commonly used hash is SHA.

The hash value is then encrypted with the private key of the CA. That encrypted value is converted to hex and added to the certificate.

The signature itself consists of two parts: a line identifying the hash algorithm and the encryption algorithm (e.g. Signature Algorithm: sha1WithRSAEncryption) and the hashed-encrypted-hexed value itself.

When the certificate is presented to a user, the user can convert the signature value from hex to binary and decrypt with the public key of the CA. This gives the value of the hash calculated by the CA.

The user then calculates the hash value of the certificate data above the signature and compares the new value to the stored value. If they are equal then the user can be assured that the certificate is valid.

In order for all this to happen the user will need to have the public key of the CA. This key will be found in a certificate obtained from the CA.

Distinguished name (DN)

Each certificate contains identity information. This information is formatted, according to the rules of X.509, as a “distinguished name”, or “DN”. There are two DNs in a certificate: that of the issuer (the CA) and that of the user (called the subject).

A DN is composed of an ordered list of naming attributes. Each attribute has a type and a value in type=value format, for example C=U.S.

The most common naming attributes are:

  • C - country

  • O - organization (your company)

  • OU - organizational unit (e.g. Accounting)

  • L - locality (city)

  • CN - common name (your name)

The CN and OU attributes from the clients may need to match previously configured information in the server. We will discuss this in the administrative and key client sections below.

NOTE: Distinguished names can assume two different formats: LDAP and DNS. AKM only supports LDAP formatted DNs. All references to DNs in this document use the LDAP format.

Self-signed certificates

Since a CA signs your certificate it makes sense to ask who signs a CA’s certificate. A CA could have its certificate be signed by another CA but at some point you will arrive at a CA who we will refer to as the root CA. This entity will sign its own certificate and this is referred to as a self-signed certificate.

In a self-signed certificate the issuer DN and the subject DN are the same.

Certificate signing request (CSR)

In order to create and sign a certificate for you the CA needs to have a certain amount of information. The X.509 standard provides a format for this called a “certificate signing request”, or “CSR”. We will discuss this in detail below.

The IBM i Digital Certificate Manager requires that certificates be created using a CSR. You can read more about certificate signing requests here.

Passwords

RSA private keys must be secured to prevent unauthorized users from accessing them. One way to do this is with a password. When a password protected private key is accessed it presents a dialog to the user asking for the password.

This can be a problem if you are running in batch mode and do not have a user available to enter the password; it is also a problem if you have a high volume of transactions making it impractical to enter passwords.

When using the openssl req command we include the -nodes argument to create a private key without a password.

IMPORTANT: You must not use a password with the private keys that you install on the AKM server.

Backup

You must pay special attention to backing up private keys and their corresponding certificates. Hardware can fail and the loss of a key pair could mean the encrypted data might not be able to be decrypted resulting in the loss of that data.

Your backup strategy must take into account that the private keys must be secured (kept secret) and you must be able to match the private key with its certificate.

TLS

“Transport Layer Security”, or “TLS”, is a software protocol used to encrypt communications over the internet. This protocol requires that both sides of the session (the client and the server) must present a signed certificate to the partner.

AKM uses TLS sessions between the key client and the server and between the administrative client and the server. The AKM server must present a signed certificate to each client that it communicates with. Also, each client must present a signed certificate to the server.

OpenSSL

We have mentioned several processing steps so far: creating an RSA key pair, creating a CSR, creating and signing a CSR, verifying a signature, creating a CA and so on.

These tasks would take an enormous amount of programming to accomplish from scratch. Fortunately there is an open source software package that handles much of the work for you called OpenSSL.

We make extensive use of OpenSSL examples in this document, and will refer to it often as we discuss the details of creating keys and certificates.

Certificate revocation list (CRL)

Certificates may be compromised (for example, someone may get access to the private key associated with the certificate). When this is discovered the CA that issued the certificate will revoke the certificate.

Since the certificate will already be loaded on your system you will need a mechanism for checking whether or not it has been revoked.

The CA will normally create a list of certificates that it has revoked called a “certificate revocation list:”, or “CRL”. This list can then be put on your system and OpenSSL can check if a certificate it is validating is on the list or not.

There is a problem with this approach when it comes to performance. Large CAs will have very large CRLs and in a high-performance environment this can slow down processing.

AKM does not support the use of CRLs. Instead the Crypto Officer is responsible for monitoring which certificates have been compromised and removing them from the system. This should not be a problem for them since the normal process for having a CA revoke a certificate would be for the Crypto Officer to determine that the certificate had been somehow compromised and then notify the CA to revoke it.

 

#Chapter 3: AKM Requirements

Key pairs

AKM requires the use of multiple RSA key pairs. You will need these key pairs in the form of a private key file and its corresponding signed certificate containing the public key.

You will need a separate unique key pair for each of the following:

  1. Identifying the AKM server to all clients: one key pair for the AKM server (see Chapter 6: Creating a Key and CSR for the AKM Server).

  2. Connecting a Crypto Officer to the AKM server: one key pair for each Officer (see Chapter 7: Creating a Key and CSR for the Crypto Officer).

  3. Connecting a key client to the AKM server: one key pair for each different key client (see Chapter 8: Creating a key and CSR for the Key Client).

  4. Exporting symmetric keys: A different key pair for each source (see Chapter 9: Creating a Key and CSR for Exporting Symmetric Keys).

  5. Importing symmetric keys: a different key pair for each source (see Chapter 10: Creating a Key and CSR for Importing Symmetric Keys).

  6. Secure server’s key-encryption-key (KEK): the symmetric keys that AKM secures are encrypted and stored in a database file. The key that is used to encrypt these keys is called the “key encryption key”, or “KEK”. (See Chapter 12: Creating and Securing the Key Encryption Key (KEK).)

  7. Secure server’s authentication key (AK): the data encryption keys in AKM are stored in database records. Each record contains information about the key (key name, creation date, key size etc.) called “key policy” as well as the key’s binary value.

To guard against this data being altered by an attacker the policy and binary value of the key is run through a hash algorithm and the resultant value is secured using a key called the “authentication key”. This secure hash is called an HMAC and it is appended to the end of each record.

When a key is accessed the hash value is recalculated and compared to the stored value. If they are different we know that the key record has been altered.

The authentication key is created at Initial Setup time and is stored on the server. In order to secure the key it is encrypted with an RSA public key and stored as an encrypted file. When the AKM server starts it reads the encrypted file and uses the corresponding RSA private key to decrypt it.

Before the program creating the authentication key can be run the RSA private key and certificate must be created and stored in the appropriate directory on the server.

See Chapter 13: Creating and Securing the Authentication Key (AK).

Chapter 4: Setting Up OpenSSL on Windows

OpenSSL does not come preinstalled or configured on Windows. If you want to use Windows for your OpenSSL platform you can follow the instructions in this chapter to do so.

Download the OpenSSL for Windows components

OpenSSL for Windows is provided by Shining Light Productions. Go to their website at:

  • http://www.slproweb.com/products/Win32OpenSSL.html

This page contains downloads for both 32-bit and 64-bit versions of Windows. The instructions shown here are for the 32-bit version.

In the “Download Win32 OpenSSL” table on this webpage you will find a number of packages to download. You will need two of these packages.

At the time of writing this document the latest version was v0.9.8k. In the future your version may be later than this. Follow these two steps:

  1. Download Win32 OpenSSL v0.9.8l Light. This will place Win32OpenSSL_Light-0_9_8l.exe on your machine. (Note that the name may be different).

  2. Download Visual C++ 2008 Redistributables (this is the 32-bit version). This will take you to a Microsoft webpage from which you can download vcredist_x86.exe.

Install the components

Install the Visual C++ package first.

Run vcredist_x86.exe to install the Visual C++ package. This will start a setup wizard program. Follow the instructions to install this package.

On the final screen of the setup program you will be shown a link to access the latest service packs and security updates. This redirects you to a .NET support page with very little information regarding what you need to update. We recommend that you contact Microsoft support if you need more information regarding these updates.

Next, run Win32OpenSSL_Light-0.9.8k.exe to install the OpenSSL package.

This will start a setup wizard program. Follow the instructions to install this package. In our examples, the install directory is C:\OpenSSL.

OpenSSL is now installed on your system.

Modify the Windows Path variable in the system variables section

You will need to determine the path to the OpenSSL bin directory and add it to the Windows path variable.

In our installation of the OpenSSL package it was placed in C:\OpenSSL so we needed to add C:\OpenSSL\bin to our path variable. See the documentation for your version of Windows for how to do this. On Windows XP the procedure is like this:

  1. Click Start, Control Panel, and System

  2. Go to the “Advanced” tab

  3. Click Environment variables

  4. Under “System variables”, click New

Restart your Windows system for the path change to take effect.

Test the installation

Open a command prompt.

Enter the version command: openssl version

On our example installation this shows as:

OpenSSL 0.9.8k 25 Mar 2009

Note: Your version may be different.

Chapter 5: Setting Up OpenSSL on Linux

Create a directory for SSL on your system.

OpenSSL is a command line application that can help you create and manage private keys, public certificates, and a certificate authority (CA). It is available for both Linux and Windows. This chapter shows the use of OpenSSL on Linux. The commands are the same for a Windows system. See Appendix B for information on installing OpenSSL on a Windows system.

Modern Linux systems ship with OpenSSL installed, configured, initialized and ready to go. We assume you have this set up on your system. If not, you will need to communicate with your Linux vendor to determine how they implement OpenSSL on their distribution.

We recommended leaving the OpenSSL installed on your system in its original state and creating other directories for your SSL needs. In this document we will create separate directories for different types of users:

  • The key server

  • The key client

  • The administrative client

  • A certificate authority

To create a local certificate authority see Appendix A - Setting up a Certificate Authority on Linux

For Crypto Officers instructions will be found in Chapter 7: Creating a Key and CSR for the Crypto Officer

For programs that need key values for encrypting (which we will call “requestors”) see Chapter 8: Creating a Key and CSR for the Key Client.

In our examples we create a single directory to hold all of these:

cd /home/userName	(where userName is your Linux user ID). 

mkdir SSL			(We will refer to this directory as ~/SSL )

Then we create directories for each function:

cd ~/SSL

mkdir CA

mkdir Server

mkdir Admin

mkdir Req

These paths will be referred to as “~/CA”, “~/Server”, “~/Admin” and “~/Req”. See the appropriate chapter for more information.

 

Chapter 6: Creating a Key and CSR for the AKM Server

As mentioned earlier we will assume a directory /home/userName/SSL/Server exists where we will put the files needed for connecting to clients. We will refer to this path as “~/Server”.

Create a copy of openssl.cnf for the server

OpenSSL uses a configuration file named openssl.cnf.

We recommend making a copy of this file and modifying its contents to reflect the appropriate default values for your location. When you create private keys and CSRs you will be prompted for a lot of information and by initializing this file you can just hit the Enter key to get the correct values.

First you need to find the default configuration file on your system:

cd ~/SSL
sudo find / -name openssl.cnf

NOTE: [sudo] is a command commonly used on Ubuntu and other Linux distributions. You may not need to use the [sudo] command on your version of Linux.

On our reference system this returns: /etc/ssl/openssl.cnf.

We copy this file to our SSL directory:

cp /etc/ssl/openssl.cnf  ~/Server/opensslServer.cnf

Modify the opensslServer.cnf file for creating the server keys and CSRs

In this section we show a listing of the default openssl.cnf file on our system and how we modified it. The lines that we removed are shown commented out with ### (red) and the lines we added will be shown immediately following in green (green). We have also modified the default spacing to make the file easier to read.

Don’t forget that these changes are applied to ~/Server/opensslServer.cnf and not to the default file on your system.

We use names for our sample below and you will want to substitute your own values when you see the following:

  • Townsend Security, Inc. - your company name here

  • PTSSCA - your CA name here

  • CountryName - your country here

  • StateOrProvinceName - your state here

  • localityName - your city here

Note that it is beyond the scope of this manual to document all of the configuration options for OpenSSL. Please consult the OpenSSL documentation at www.openssl.org.

Sample modified opensslServer.cnf file

# OpenSSL example configuration file.
# This is mostly being used for generation of certificate requests.

# This definition stops the following lines choking if HOME isn’t
# defined.
HOME = .
RANDFILE = $ENV::HOME/.rnd

# Extra OBJECT IDENTIFIER info:
#oid_file   = $ENV::HOME/.oid
oid_section	= new_oids

# To use this configuration file with the “-extfile” option of the
# “openssl x509” utility, name here the section containing the
# X.509v3 extensions to use:
# extensions = 
# (Alternatively, use a configuration file that has only
# X.509v3 extensions in its main [= default] section.)

[ new_oids ]
# We can add new OIDs in here for use by ‘ca’ and ‘req’.
# Add a simple OID like this:
# testoid1=1.2.3.4
# Or use config file substitution like this:
# testoid2=${testoid1}.5.6

###################################################################
[ ca ]
default_ca = CA_default	# The default ca section

###################################################################
[ CA_default ]
dir 		 = ./demoCA	# Where everything is kept

certs	 = $dir/certs		# Where the issued certs are kept
crl_dir	 = $dir/crl		# Where the issued crl are kept
database = $dir/index.txt # database index file.
#unique_subject = no	# Set to ‘no’ to allow creation of
					    	# several ctificates with same subject.
new_certs_dir = $dir/newcerts	# default place for new certs.

certificate= $dir/cacert.pem 	# The CA certificate
serial		= $dir/serial 		# The current serial number
crlnumber	= $dir/crlnumber	# the current crl number
								# must be commented out to leave a V1 CRL
crl	= $dir/crl.pem 				# The current CRL

private_key = $dir/private/cakey.pem # The private key

RANDFILE = $dir/private/.rand	# private random number file

x509_extensions = usr_cert	# The extentions to add to the cert

# Comment out the following two lines for the “traditional”
# (and highly broken) format.
name_opt = ca_default	# Subject Name options
cert_opt = ca_default	# Certificate field options

# Extension copying option: use with caution.
# copy_extensions = copy

# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
# so this is commented out by default to leave a V1 CRL.
# crlnumber must also be commented out to leave a V1 CRL.
# crl_extensions = crl_ext

default_days = 9000 	# how long to certify for
default_crl_days = 30	# how long before next CRL
default_md = sha1		# which md to use.
preserve = no			# keep passed DN ordering

# A few difference way of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that :-)
policy	= policy_match

# For the CA policy
[ policy_match ]
countryName	= 			 match
stateOrProvinceName	= 	 match
organizationName = 		 match
organizationalUnitName =	optional
commonName = 			supplied
emailAddress =			 	optional

# For the ‘anything’ policy
# At this point in time, you must list all acceptable ‘object’
# types.

[ policy_anything ]
countryName = 			 	optional
stateOrProvinceName	= 	optional
localityName = 			 	optional
organizationName = 		optional
organizationalUnitName = 	optional
commonName = 			supplied
emailAddress = 			optional

###################################################################
[ req ]
###default_bits = 1024
default_bits = 2048
###default_keyfile = privkey.pem
default_keyfile = ServerPrivKey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
x509_extensions = v3_ca	# The extentions to add to the self signed cert

# Passwords for private keys if not present they will be prompted for
# input_password  = secret
# output_password = secret

# This sets a mask for permitted string types. There are several options. 
# default: PrintableString, T61String, BMPString.
# pkix	 : PrintableString, BMPString.
# utf8only: only UTF8Strings.
# nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
# MASK:XXXX a literal mask value.
# WARNING: current versions of Netscape crash on BMPStrings or UTF8Strings
# so use this option with caution!
string_mask = nombstr

# req_extensions = v3_req # The extensions to add to a certificate request

[ req_distinguished_name ]
###countryName= Country Name (2 letter code)
countryName= US (2 letter code)
###countryName_default = AU
countryName_default = US
countryName_min	= 2
countryName_max	= 2

###stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName = Washington
###stateOrProvinceName_default = Some-State
stateOrProvinceName_default = Washington

###localityName = Locality Name (eg, city)
localityName = Olympia (eg, city)

###0.organizationName	= Organization Name (eg, company)
0.organizationName	= Townsend Security, Inc. 

###0.organizationName_default = Internet Widgits Pty Ltd
0.organizationName_default	 = Townsend Security, Inc.

# we can do this but it is not needed normally :-)
#1.organizationName	    	= Second Organization Name (eg, company)
#1.organizationName_default	= World Wide Web Pty Ltd

###organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName = akm_server
#organizationalUnitName_default  =
organizationalUnitName_default = akm_server

commonName = Common Name (eg, YOUR name)
commonName_max = 64

emailAddress = Email Address
emailAddress_max = 64

# SET-ex3 = SET extension number 3

[ req_attributes ]
###challengePassword = A challenge password
###challengePassword_min = 4
###challengePassword_max = 20

###unstructuredName = An optional company name

[ usr_cert ]
# These extensions are added when ‘ca’ signs a request.
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints = CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.
# nsCertType = server

# For an object signing certificate this would be used.
# nsCertType = objsign

# For normal client use this is typical
# nsCertType = client, email

# and for everything including object signing:
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape’s comment listbox.
nsComment = “OpenSSL Generated Certificate”

# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash

authorityKeyIdentifier=keyid,issuer

# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren’t
# deprecated according to PKIX.
# subjectAltName=email:move

# Copy subject details
# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

[ v3_req ]
# Extensions to add to a certificate request
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ v3_ca ]
# Extensions for a typical CA
# PKIX recommendation.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always

# This is what PKIX recommends but some broken software chokes on critical
# extensions.
#basicConstraints = critical,CA:true
# So we do this instead.
basicConstraints = CA:true

# Key usage: this is typical for a CA certificate. However since it will
# prevent it being used as an test self-signed certificate it is best
# left out by default.
# keyUsage = cRLSign, keyCertSign

# Some might want this also
# nsCertType = sslCA, emailCA

# Include email address in subject alt name: another PKIX recommendation
# subjectAltName=email:copy
# Copy issuer details
# issuerAltName=issuer:copy

# DER hex encoding of an extension: beware experts only!
# obj=DER:02:03
# Where ‘obj’ is a standard or added object
# You can even override a supported extension:

# basicConstraints= critical, DER:30:03:01:01:FF

[ crl_ext ]
# CRL extensions.
# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.

# issuerAltName=issuer:copy
authorityKeyIdentifier=keyid:always,issuer:always

[ proxy_cert_ext ]
# These extensions should be added when creating a proxy certificate
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints=CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.
# nsCertType = server

# For an object signing certificate this would be used.
# nsCertType = objsign

# For normal client use this is typical
# nsCertType = client, email

# and for everything including object signing:
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape’s comment listbox.
nsComment = “OpenSSL Generated Certificate”

# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer:always

# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren’t
# deprecated according to PKIX.
# subjectAltName=email:move

# Copy subject details
# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl

#nsSslServerName

# This really needs to be in place for it to be a proxy certificate.
proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:3,policy:foo

Generate a new random file

OpenSSL uses a file containing random information. We recommend creating a new random file for each place you have changed the OpenSSL configuration file:

cd ~/Server
openssl rand -out randomServer.dat 1024

The server’s organizational unit name (OU)

AKM requires that the server certificates have the organizational unit (OU) set to akm_server.

The server’s common name (CN)

This value can be determined on Linux by opening a command line prompt and entering the command hostname.

Each AKM server will need a unique set of private keys and signed certificates.

Creating the server’s private key and CSR

Use the following command to create a new private key and a corresponding CSR for the server:

cd ~/Server

openssl req -new -newkey rsa:2048 -nodes -config ./opensslServer.cfg 

-rand ./randomServer.dat -keyout ServerPrivKey.pem  -out ServerCsr.pem 

You will see the following prompts:

user1@elara:~/SSL/Server> ./bServer.sh
Create server private key (ServerPrivKey.pem) and CSR (ServerCsr.pem)
Generating a 2048 bit RSA private key
...+++
.........................................+++
writing new private key to ‘ServerPrivKey.pem’
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ‘.’, the field will be left blank.
-----
US (2 letter code) [US]:
Washington [Washington]:
Olympia []:
Townsend Security, Inc. [Townsend Security, Inc.]:
akm_server [akm_server]:
Common Name (eg, server’s name) []:elara
Email Address []:server@ptss.com

This command will create the following files in your ~/Server directory:

ServerCsr.pem
ServerPrivKey.pem

This command will allow you to look at the new CSR in a text file:

openssl req -noout -text -in ServerCsr.pem -out ServerCsr.txt

Key sizes

RSA keys come in different sizes usually measured by the number of bits in the key. The bigger the key the more secure it is. It is also true that larger the key the longer it takes to encrypt.

AKM uses keys that are 2048 bits long. Some 1024-bit keys may be permitted for establishing connections.

Converting the server’s CSR to a signed certificate

Once you have created a certificate signing request you need to present it to a certificate authority to be signed.

You send this: ServerCsr.pem –> CA

You get this back: ServerSignedCert.pem <– CA

Do NOT send the private key file to the CA.

If you are using a public CA check with their policy documents to determine how to proceed. You will need to send them the CSR file and will get a signed certificate in return.

If you are creating and using your own CA follow the instructions in Chapter 11: Signing a CSR with Your Own CA.

Installing the server’s private key and certificate

Once the CA has signed the server’s certificate there will be two files that need to be installed on other machines:

ServerSignedCert.pem 
ServerPrivKey.pem 	

The ServerSignedCert.pem file is installed on the server’s machine. It is presented to the Crypto Officer, key client or mirror partner when the creating a TLS session.

Certificates and private keys are installed on the AKM server using a web browser session to the AKM server management interface.

 

Chapter 7: Creating a Key and CSR for the Crypto Officer

As mentioned earlier we will assume a directory /home/userName/SSL/Admin exists where we will put the files needed for the Crypto Officer. We will refer to this path as “~/Admin”.

Create a copy of openssl.cnf for the Crypto Officer

OpenSSL uses a configuration file named openssl.cnf.

We recommend making a copy of this file and modifying its contents to reflect the appropriate default values for your location. When you create private keys and CSRs you will be prompted for a lot of information and by initializing this file you can just hit the Enter key to get the correct values.

First you need to find the default configuration file on your system.

cd ~/SSL

sudo find / -name openssl.cnf

On our reference system this returns: /etc/ssl/openssl.cnf.

We copy this file to our SSL directory:

cp /etc/ssl/openssl.cnf  ~/Admin/opensslAdmin.cnf

Modify the opensslAdmin.cnf file for creating Crypto Officer keys and Certificate Signing Requests

In this section we show a listing of the default openssl.cnf file on our system and how we modified it. The lines that we removed are shown commented out with ### (red) and the lines we added will be shown immediately following in green (green). We have also modified the default spacing to make the file easier to read.

Don’t forget that these changes are applied to ~/Admin/opensslAdmin.cnf and not to the default file on your system.

We use names for our sample below and you will want to substitute your own values when you see the following:

  • Townsend Security, Inc. - your company name here

  • PTSSCA - your CA name here

  • CountryName - your country here

  • StateOrProvinceName - your state here

  • localityName - your city here

It is beyond the scope of this manual to document all of the configuration options for OpenSSL. Please consult the OpenSSL documentation at www.openssl.org.

Sample modified opensslAdmin.cnf file

# OpenSSL example configuration file.
# This is mostly being used for generation of certificate requests.

# This definition stops the following lines choking if HOME isn’t
# defined.
HOME = .
RANDFILE = $ENV::HOME/.rnd

# Extra OBJECT IDENTIFIER info:
#oid_file   = $ENV::HOME/.oid
oid_section	= new_oids

# To use this configuration file with the “-extfile” option of the
# “openssl x509” utility, name here the section containing the
# X.509v3 extensions to use:
# extensions = 
# (Alternatively, use a configuration file that has only
# X.509v3 extensions in its main [= default] section.)

[ new_oids ]
# We can add new OIDs in here for use by ‘ca’ and ‘req’.
# Add a simple OID like this:
# testoid1=1.2.3.4
# Or use config file substitution like this:
# testoid2=${testoid1}.5.6

###################################################################
[ ca ]
default_ca = CA_default	# The default ca section

###################################################################
[ CA_default ]
dir 		 = ./demoCA	# Where everything is kept
certs	 = $dir/certs		# Where the issued certs are kept
crl_dir	 = $dir/crl		# Where the issued crl are kept
database = $dir/index.txt # database index file.
#unique_subject = no	# Set to ‘no’ to allow creation of
					    	# several ctificates with same subject.
new_certs_dir = $dir/newcerts	# default place for new certs.


certificate= $dir/cacert.pem 	# The CA certificate
serial		= $dir/serial 		# The current serial number
crlnumber	= $dir/crlnumber	# the current crl number
								# must be commented out to leave a V1 CRL
crl	= $dir/crl.pem 				# The current CRL

private_key = $dir/private/cakey.pem # The private key

RANDFILE = $dir/private/.rand	# private random number file

x509_extensions = usr_cert	# The extentions to add to the cert

# Comment out the following two lines for the “traditional”
# (and highly broken) format.
name_opt = ca_default	# Subject Name options
cert_opt = ca_default	# Certificate field options

# Extension copying option: use with caution.
# copy_extensions = copy

# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
# so this is commented out by default to leave a V1 CRL.
# crlnumber must also be commented out to leave a V1 CRL.
# crl_extensions = crl_ext

default_days = 9000 	# how long to certify for
default_crl_days = 30	# how long before next CRL
default_md = sha1		# which md to use.
preserve = no			# keep passed DN ordering

# A few difference way of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that :-)
policy	= policy_match

# For the CA policy
[ policy_match ]
countryName	= 			 match
stateOrProvinceName	= 	 match
organizationName = 		 match
organizationalUnitName =	optional
commonName = 			supplied
emailAddress =			 	optional

# For the ‘anything’ policy
# At this point in time, you must list all acceptable ‘object’
# types.
[ policy_anything ]
countryName = 			 	optional
stateOrProvinceName	= 	optional
localityName = 			 	optional
organizationName = 		optional
organizationalUnitName = 	optional
commonName = 			supplied

emailAddress = 			optional

###################################################################
[ req ]
###default_bits = 1024
default_bits = 2048
###default_keyfile = privkey.pem
default_keyfile = AdminPrivKey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
x509_extensions = v3_ca	# The extentions to add to the self signed cert

# Passwords for private keys if not present they will be prompted for
# input_password  = secret
# output_password = secret

# This sets a mask for permitted string types. There are several options. 
# default: PrintableString, T61String, BMPString.
# pkix	 : PrintableString, BMPString.
# utf8only: only UTF8Strings.
# nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
# MASK:XXXX a literal mask value.
# WARNING: current versions of Netscape crash on BMPStrings or UTF8Strings
# so use this option with caution!
string_mask = nombstr

# req_extensions = v3_req # The extensions to add to a certificate request

[ req_distinguished_name ]
###countryName= Country Name (2 letter code)
countryName= US
###countryName_default = AU
countryName_default = US
countryName_min	= 2
countryName_max	= 2

###stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName = Washington
###stateOrProvinceName_default = Some-State
stateOrProvinceName_default = Washington

###localityName = Locality Name (eg, city)
localityName = Olympia

###0.organizationName	= Organization Name (eg, company)
0.organizationName	= Townsend Security, Inc.
###0.organizationName_default = Internet Widgits Pty Ltd
0.organizationName_default	 = Townsend Security, Inc.

# we can do this but it is not needed normally :-)
#1.organizationName	    	= Second Organization Name (eg, company)
#1.organizationName_default	= World Wide Web Pty Ltd


###organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName = akm_admin
#organizationalUnitName_default  =
organizationalUnitName_default = akm_admin

commonName = Common Name (eg, YOUR name)
commonName_max = 64

emailAddress = Email Address
emailAddress_max = 64

# SET-ex3 = SET extension number 3

[ req_attributes ]
###challengePassword = A challenge password
###challengePassword_min = 4
###challengePassword_max = 20

###unstructuredName = An optional company name

[ usr_cert ]
# These extensions are added when ‘ca’ signs a request.
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints = CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.
# nsCertType = server

# For an object signing certificate this would be used.
# nsCertType = objsign

# For normal client use this is typical
# nsCertType = client, email

# and for everything including object signing:
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape’s comment listbox.
nsComment = “OpenSSL Generated Certificate”

# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer

# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren’t
# deprecated according to PKIX.

# subjectAltName=email:move

# Copy subject details
# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

[ v3_req ]
# Extensions to add to a certificate request
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ v3_ca ]
# Extensions for a typical CA
# PKIX recommendation.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always

# This is what PKIX recommends but some broken software chokes on critical
# extensions.
#basicConstraints = critical,CA:true
# So we do this instead.
basicConstraints = CA:true

# Key usage: this is typical for a CA certificate. However since it will
# prevent it being used as an test self-signed certificate it is best
# left out by default.
# keyUsage = cRLSign, keyCertSign

# Some might want this also
# nsCertType = sslCA, emailCA

# Include email address in subject alt name: another PKIX recommendation
# subjectAltName=email:copy
# Copy issuer details
# issuerAltName=issuer:copy

# DER hex encoding of an extension: beware experts only!
# obj=DER:02:03
# Where ‘obj’ is a standard or added object
# You can even override a supported extension:
# basicConstraints= critical, DER:30:03:01:01:FF

[ crl_ext ]
# CRL extensions.
# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.


# issuerAltName=issuer:copy
authorityKeyIdentifier=keyid:always,issuer:always

[ proxy_cert_ext ]
# These extensions should be added when creating a proxy certificate
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints=CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.
# nsCertType = server

# For an object signing certificate this would be used.
# nsCertType = objsign

# For normal client use this is typical
# nsCertType = client, email

# and for everything including object signing:
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape’s comment listbox.
nsComment = “OpenSSL Generated Certificate”

# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer:always

# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren’t
# deprecated according to PKIX.
# subjectAltName=email:move

# Copy subject details
# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

# This really needs to be in place for it to be a proxy certificate.
proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:3,policy:foo

Generate a new random file

OpenSSL uses a file containing random information. We recommend creating a new random file for each place you have changed the OpenSSL configuration file.

cd ~/Admin

openssl rand -out randomAdmin.dat 1024

The Crypto Officer’s organizational unit name (OU)

AKM requires that Crypto Officer certificates have the organizational unit (OU) set to akm_admin.

The Crypto Officer’s common name (CN)

The CN value should be the host name of the computer the Crypto Officer will connect from. This value can be determined on Linux by opening a command line prompt and entering the command hostname.

For Windows system you can determine the host name by using the Control Panel. Click

Start, Control Panel, System, and Computer Name.

If you have multiple people performing the Crypto Officer’s function you will need to create a different key pair and certificate for each of them. On the distinguished name (DN) each one will need to have the organizational unit set as OU=akm_admin but a different common name (CN=Bill, CN=Jane).

NOTE: In this document we assume the file names AdminPrivKey, AdminCsr, AdminSignedCert etc. These names are generic and meant to help keep track of the function of each file. In practice you will need these to have unique names for each Crypto Officer.

Creating the Crypto Officer’s private key and CSR

Use the following command to create a new private key and a corresponding CSR for the Crypto Officer:

cd ~/Admin

openssl req -new -newkey rsa:2048 -nodes -config ./opensslAdmin.cfg 

-rand ./randomAdmin.dat -keyout AdminPrivKey.pem  -out AdminCsr.pem 

You will see the following prompts:

user1@elara:~/SSL/Admin> ./bAdmin.sh
Create administrator private key (AdminPrivKey.pem) and CSR (AdminCsr.pem)
Generating a 2048 bit RSA private key
...+++
.........................................+++
writing new private key to ‘AdminPrivKey.pem’
-----
You are about to be asked to enter information that will be incorporated 
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ‘.’, the field will be left blank.
-----
US (2 letter code) [US]:
Washington [Washington]:
Olympia []:
Townsend Security, Inc. [Townsend Security, Inc.]:
akm_admin [akm_admin]:
Common Name (eg, YOUR name) []:elara
Email Address []:admin@ptss.com

This command will create the following files in your ~/Admin directory:

  • AdminCsr.pem

  • AdminPrivKey.pem

This command will allow you to look at the new CSR in a text file.

openssl req -noout -text -in AdminCsr.pem -out AdminCsr.txt

Key sizes

RSA keys come in different sizes usually measured by the number of bits in the key. The bigger the key the more secure it is. It is also true that larger the key the longer it takes to encrypt.

AKM uses keys that are 2048 bits long. Some 1024-bit keys may be permitted for establishing connections.

Converting the Crypto Officer’s CSR to a signed certificate

Once you have created a certificate signing request you need to present it to a certificate authority to be signed.

You send this: AdminCsr.pem –> CA

You get this back: AdminSignedCert.pem <– CA

Do NOT send your private key file to the CA.

If you are using a public CA check with their policy documents to determine how to proceed. You will need to send them the CSR file and will get a signed certificate in return.

If you are creating and using your own CA follow the instructions in Chapter 11: Signing a CSR with Your Own CA.

Installing the Crypto Officer’s private key and certificate

Once the CA has signed the Crypto Officer’s certificate there will be two files that need to be installed on other machines:

AdminSignedCert.pem 
AdminPrivKey.pem 

The AdminSignedCert.pem file is installed on the Crypto Officer’s machine. It is presented to the AKM server when the Crypto Officer wants to create a TLS session to issue commands to the server.

If you are using the AKM Administrative Console, the certificate and private key will be installed in Java key store (.jks) files.

 

Chapter 8: Creating a Key and CSR for a Key Client

Create a copy of openssl.cnf for the key client

OpenSSL uses a configuration file named openssl.cnf.

We recommend making a copy of this file and modifying its contents to reflect the appropriate default values for your location. When you create private keys and CSRs you will be prompted for a lot of information and by initializing this file you can just hit the Enter key to get the correct values.

First you need to find the default configuration file on your system:

cd ~/Req
sudo find / -name openssl.cnf

On our reference system this returns: /etc/ssl/openssl.cnf.

We copy this file to our SSL directory:

cp /etc/ssl/openssl.cnf  ~/Req/opensslReq.cnf

Modify the opensslReq.cnf file for creating requestor keys and CSRs

In this section we show a listing of the default openssl.cnf file on our system and how we modified it. The lines that we removed are shown commented out with ### (red) and the lines we added will be shown immediately following in green (green). We have also modified the default spacing to make the file easier to read.

Don’t forget that these changes are applied to ~/SSL/opensslReq.cnf and not to the default file on your system.

We use names for our sample below and you will want to substitute your own values when you see the following:

  • Townsend Security, Inc. - your company name here

  • PTSSCA - your CA name here

  • CountryName - your country here

  • StateOrProvinceName - your state here

  • localityName - your city here

It is beyond the scope of this manual to document all of the configuration options for OpenSSL. Please consult the OpenSSL documentation at www.openssl.org.

Sample modified opensslReq.cnf file

# OpenSSL example configuration file.
# This is mostly being used for generation of certificate requests.
# This definition stops the following lines choking if HOME isn’t
# defined.
HOME = .
RANDFILE = $ENV::HOME/.rnd

# Extra OBJECT IDENTIFIER info:
#oid_file   = $ENV::HOME/.oid
oid_section	= new_oids

# To use this configuration file with the “-extfile” option of the
# “openssl x509” utility, name here the section containing the
# X.509v3 extensions to use:
# extensions = 
# (Alternatively, use a configuration file that has only
# X.509v3 extensions in its main [= default] section.)

[ new_oids ]
# We can add new OIDs in here for use by ‘ca’ and ‘req’.
# Add a simple OID like this:
# testoid1=1.2.3.4
# Or use config file substitution like this:
# testoid2=${testoid1}.5.6

###################################################################
[ ca ]
default_ca = CA_default	# The default ca section

###################################################################
[ CA_default ]
dir 		 = ./demoCA	# Where everything is kept
certs	 = $dir/certs		# Where the issued certs are kept
crl_dir	 = $dir/crl		# Where the issued crl are kept
database = $dir/index.txt # database index file.
#unique_subject = no	# Set to ‘no’ to allow creation of
					    	# several ctificates with same subject.
new_certs_dir = $dir/newcerts	# default place for new certs.

certificate= $dir/cacert.pem 	# The CA certificate
serial		= $dir/serial 		# The current serial number
crlnumber	= $dir/crlnumber	# the current crl number
								# must be commented out to leave a V1 CRL
crl	= $dir/crl.pem 				# The current CRL

private_key = $dir/private/cakey.pem # The private key

RANDFILE = $dir/private/.rand	# private random number file

x509_extensions = usr_cert	# The extentions to add to the cert

# Comment out the following two lines for the “traditional”
# (and highly broken) format.
name_opt = ca_default	# Subject Name options
cert_opt = ca_default	# Certificate field options

# Extension copying option: use with caution.
# copy_extensions = copy

# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
# so this is commented out by default to leave a V1 CRL.
# crlnumber must also be commented out to leave a V1 CRL.
# crl_extensions = crl_ext

default_days = 9000 	# how long to certify for
default_crl_days = 30	# how long before next CRL
default_md = sha1		# which md to use.
preserve = no			# keep passed DN ordering

# A few difference way of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that :-)
policy	= policy_match

# For the CA policy
[ policy_match ]
countryName	= 			 match
stateOrProvinceName	= 	 match
organizationName = 		 match
organizationalUnitName =	optional
commonName = 			supplied
emailAddress =			 	optional

# For the ‘anything’ policy
# At this point in time, you must list all acceptable ‘object’
# types.
[ policy_anything ]
countryName = 			 	optional
stateOrProvinceName	= 	optional
localityName = 			 	optional
organizationName = 		optional
organizationalUnitName = 	optional
commonName = 			supplied
emailAddress = 			optional

###################################################################
[ req ]
###default_bits = 1024
default_bits = 2048
###default_keyfile = privkey.pem
default_keyfile = ClientPrivKey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes

x509_extensions = v3_ca	# The extentions to add to the self signed cert

# Passwords for private keys if not present they will be prompted for
# input_password  = secret
# output_password = secret

# This sets a mask for permitted string types. There are several options. 
# default: PrintableString, T61String, BMPString.
# pkix	 : PrintableString, BMPString.
# utf8only: only UTF8Strings.
# nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
# MASK:XXXX a literal mask value.
# WARNING: current versions of Netscape crash on BMPStrings or UTF8Strings
# so use this option with caution!
string_mask = nombstr

# req_extensions = v3_req # The extensions to add to a certificate request

[ req_distinguished_name ]
###countryName= Country Name (2 letter code)
countryName= US
###countryName_default = AU
countryName_default = US
countryName_min	= 2
countryName_max	= 2

###stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName = Washington
###stateOrProvinceName_default = Some-State
stateOrProvinceName_default = Washington

###localityName = Locality Name (eg, city)
localityName = Olympia

###0.organizationName	= Organization Name (eg, company)
0.organizationName	= Townsend Security, Inc.
###0.organizationName_default = Internet Widgits Pty Ltd
0.organizationName_default	 = Townsend Security, Inc.

# we can do this but it is not needed normally 
#1.organizationName = Second Organization Name (eg, company)
#1.organizationName_default = World Wide Web Pty Ltd

organizationalUnitName = Organizational Unit Name (eg, section)
organizationalUnitName_default = youForgotTheOU

commonName = Common Name (eg, YOUR name)
commonName_max = 64

emailAddress = Email Address
emailAddress_max = 64

# SET-ex3 = SET extension number 3

[ req_attributes ]
###challengePassword = A challenge password
###challengePassword_min = 4
###challengePassword_max = 20

###unstructuredName = An optional company name

[ usr_cert ]
# These extensions are added when ‘ca’ signs a request.
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints = CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.
# nsCertType = server

# For an object signing certificate this would be used.
# nsCertType = objsign

# For normal client use this is typical
# nsCertType = client, email

# and for everything including object signing:
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape’s comment listbox.
nsComment = “OpenSSL Generated Certificate”

# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer

# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren’t
# deprecated according to PKIX.
# subjectAltName=email:move

# Copy subject details
# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

[ v3_req ]

# Extensions to add to a certificate request
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ v3_ca ]
# Extensions for a typical CA
# PKIX recommendation.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always

# This is what PKIX recommends but some broken software chokes on critical
# extensions.
#basicConstraints = critical,CA:true
# So we do this instead.
basicConstraints = CA:true

# Key usage: this is typical for a CA certificate. However since it will
# prevent it being used as an test self-signed certificate it is best
# left out by default.
# keyUsage = cRLSign, keyCertSign

# Some might want this also
# nsCertType = sslCA, emailCA

# Include email address in subject alt name: another PKIX recommendation
# subjectAltName=email:copy
# Copy issuer details
# issuerAltName=issuer:copy

# DER hex encoding of an extension: beware experts only!
# obj=DER:02:03
# Where ‘obj’ is a standard or added object
# You can even override a supported extension:
# basicConstraints= critical, DER:30:03:01:01:FF

[ crl_ext ]
# CRL extensions.
# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.

# issuerAltName=issuer:copy
authorityKeyIdentifier=keyid:always,issuer:always

[ proxy_cert_ext ]
# These extensions should be added when creating a proxy certificate
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints=CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.

# nsCertType = server

# For an object signing certificate this would be used.
# nsCertType = objsign

# For normal client use this is typical
# nsCertType = client, email

# and for everything including object signing:
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape’s comment listbox.
nsComment = “OpenSSL Generated Certificate”

# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer:always

# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren’t
# deprecated according to PKIX.
# subjectAltName=email:move

# Copy subject details
# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

# This really needs to be in place for it to be a proxy certificate.
proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:3,policy:foo

Generate a new random file

OpenSSL uses a file containing random information. We recommend creating a new random file for each place you have changed the OpenSSL configuration file:

cd ~/Admin

openssl rand -out randomReq.dat 1024

The requestor’s organizational unit (OU)

A key client certificate needs to have two fields in the distinguished name set in accordance with policy that the Crypto Officer has established.

These two fields are the requestor’s common name (CN) and organizational unit (OU).

The Crypto Officer may set requirements for accessing keys as follows:

  • Any requestor may access the key

  • Only a user defined to AKM may access the key

  • Only a member of a group defined to AKM may access the key

  • Only a defined user who is a member of a defined group may access the key (permissive access)

  • Only a defined user who is a member of a defined group and who is explicitly named as a member of that group in the Group Member Table may access the key (strict access)

For this reason you must be sure that key access requirements match requestor and group definitions within AKM. See the Alliance Key Manager User Guide for more information.

The requestor’s common name (CN)

The CN value should be the host name of the computer the requestor will connect from. This value can be determined on Linux by opening a command line prompt and entering the command hostname.

On Windows you can determine the host name from the Control Panel:

Click Start, Control Panel, System, and Computer Name.

If you have multiple key clients you will need to create a different key pair and certificate for each of them. On the distinguished name (DN) each one will need to have the organizational unit set to the appropriate group name and each one will need a different common name (CN=Bill, CN=Jane).

NOTE: In this document we assume the file names “ReqPrivKey”,” ReqCsr”, “ReqSignedCert” etc. These names are generic and meant to help keep track of the function of each file. In practice you will need these to have unique names for each requestor.

Creating the key client’s private key and CSR

Use the following command to create a new private key and a corresponding CSR for the key client:

openssl req -new -newkey rsa:2048 -nodes -config ./opensslReq.cnf 

-random ./randomReq.dat -keyout ReqPrivKey.pem -out ReqCsr.pem

You will see the following prompts:

user1@elara:~/SSL/Req> 
Create requestor private key (ReqPrivKey.pem) and CSR (ReqCsr.pem)
Generating a 2048 bit RSA private key
.............................................................+++
.......................................+++
writing new private key to ‘ReqPrivKey.pem’
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ‘.’, the field will be left blank.
-----
US (2 letter code) [US]:
Washington [Washington]:
Olympia []:
Townsend Security, Inc. [Townsend Security, Inc.]:
Organizational Unit Name (eg, section) [youForgotTheOU]:myOU
Common Name (eg, YOUR name) []:elara
Email Address []:elara@ptss.com

This command will create the following files in your ~/SSL directory:

ReqCsr.pem
ReqPrivKey.pem

This command will allow you to look at the new CSR in a text file:

openssl req -noout -text -in ReqCsr.pem -out ReqCsr.txt

Key sizes

It is recommended that RSA keys used for TLS session establishment be at least 2048 bits in length.

AKM will support 1024-bit keys for session establishment but this key size should only be used when performance is severely impacted due to legacy processors or networks.

Converting the requestor’s CSR to a signed certificate

Once you have created a certificate signing request you need to present it to a certificate authority to be signed.

You send this: ReqCsr.pem –> CA

You get this back: ReqSignedCert.pem <– CA

Do NOT send your private key file to the CA.

If you are using a public CA check with their policy documents to determine how to proceed. You will need to send them the CSR file and will get a signed certificate in return.

If you are creating and using your own CA follow the instructions in Chapter 11: Signing a CSR with Your Own CA.

Installing the requestors’s private key and certificate

Once the CA has signed the requestor’s certificate there will be two files that need to be installed on other machines:

ReqSignedCert.pem 
ReqPrivKey.pem 

The ReqSignedCert.pem file is installed on the requestor’s machine. It is presented to the AKM server when the requestor wants to create a TLS session to ask the server for encryption keys.

If you are using the AKM requestor shared object or DLL the name of this file will be entered in the akmclient.conf configuration file as follows:

[cert]
CientPrivateKey=/someDir/myReqPrivKey.pem
ClientSignedCert=/someDir/myReqSignedCert.pem

For Windows users, the certificate will be converted to a format supported by Windows, and stored in the Windows certificate manager.

For Java users, the certificates will be stored in a Java Key Store (.jks) file for use by the Java application.

On the IBM i platform, the certificates will be stored in the IBM Digital Certificate Manager key store (.KDB file).

On the IBM z mainframe platform, the certificates will be managed by RACF.

 

Chapter 9: Creating a Key and CSR for Exporting Symmetric Keys

One of the services that AKM provides is the ability to export a symmetric key. This is driven by the Export Symmetric Key command from the Crypto Officer using the AKM Administrative Console.

When this command is received the server reads the key value from the database, encrypts the key with an RSA public key and sends the encrypted value back to the Crypto Officer. The public key is located within a certificate that is stored on the server and referenced by name on the Export Symmetric Key command.

You can get a certificate in one of two ways:

  1. Get one from your trading partner

  2. Make your own

Get a certificate from your trading partner

If you are exporting a key to a partner company you will need to encrypt it with their RSA public key. That way only their private key can decrypt it.

They can send you their public key in the clear and you can use the “Import Certificate” command in the AKM Administrative Console to import this public key to the AKM server. To export the key, use the “Export Symmetric Key” command and specify the certificate name.

These tasks are usually performed by a Crypto Officer.

They can send you their public key in the clear and you should install it into the /etc/akm/Certs directory on your AMK server.

When the Crypto Officer wants to export the key they need to specify the certificate name used to encrypt the key the ExportSymKey command.

Key sizes

RSA keys used to encrypt files for storage must be at least 2048 bits.

Creating your own certificate

If you are going to be exporting the key to another part of your own company and need to create the certificate internally you can follow the procedures in Chapter 6: Creating a Key and CSR for the AKM Server.

You could use the server’s public key to sign exported keys but we recommend that it is a best practice to use a separate key for this purpose.

Creating the key export private key and CSR

Use the following command to create a new private key and a corresponding CSR for exporting keys:

cd ~/Server
openssl req -new -newkey rsa:2048 -nodes -config ./opensslServer.cfg 
-rand ./randomServer.dat -keyout ExportPrivKey.pem  -out ExportCsr.pem  

Note that we use the akm_export as the OU value. This name is used for clarity only and is not required. You will see the following prompts:

user1@elara:~/SSL/Server> 
Create server private key (ExportPrivKey.pem) and CSR (ExportCsr.pem)
Generating a 2048 bit RSA private key
...+++
.........................................+++
writing new private key to ‘ExportPrivKey.pem’
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ‘.’, the field will be left blank.
-----
US (2 letter code) [US]:
Washington [Washington]:
Olympia []:
Townsend Security, Inc. [Townsend Security, Inc.]:
akm_server [akm_server]: akm_export
Common Name (eg, server’s name) []:elara
Email Address []:server@ptss.com

This command will create the following files in your ~/Server directory:

ExportCsr.pem
ExportPrivKey.pem

This command will allow you to look at the new CSR in a text file:

openssl req -noout -text -in ExportCsr.pem -out ExportCsr.txt

Converting the key export CSR to a signed certificate

Once you have created a certificate signing request you need to present it to a certificate authority to be signed.

You send this: ExportCsr.pem –> CA

You get this back: ExportSignedCert.pem <– CA

Do NOT send the private key file to the CA.

If you are using a public CA check with their policy documents to determine how to proceed. You will need to send them the CSR file and will get a signed certificate in return.

If you are creating and using your own CA follow the instructions in Chapter 11: Signing a CSR with Your Own CA.

Installing the export private key and certificate

Once the CA has signed the export certificate there will be two files that need to be installed on other machines:

ExportSignedCert.pem 
ExportPrivKey.pem 

The ExportSignedCert.pem file is installed on the AKM server using the AKM Administrative Console.

 

Chapter 10: Creating a Key and CSR for Importing Symmetric Keys

One of the services that AKM provides is the ability to import a symmetric key. This is driven by the Import Symmetric Key command from the Crypto Officer.

Get a key from your trading partner

The partner who is sending the new key to the AKM server encrypts the binary key value with our public key and we will decrypt it with our private key once it arrives on the server.

Key sizes

RSA keys used to encrypt files for storage must be at least 2048 bits.

Creating your own certificate

If you are going to be importing keys you need to create the private key and certificate internally. You can follow the procedures in the Chapter 6: Creating a Key and CSR for the AKM Server.

You could give the server’s public key to the partner to use to sign keys but we recommend that it is a best practice to use a separate key and certificate for this purpose.

Creating the import private key and certificate

Use the following command to create a new private key and a corresponding CSR for exporting keys:

cd ~/Server
	openssl req -new -newkey rsa:2048 -nodes -config ./opensslServer.cfg 
-rand ./randomServer.dat -keyout ImportPrivKey.pem  -out ImportCsr.pem 

Note that we use the akm_import as the OU value. This name is used for clarity only and is not required. You will see the following prompts:

user1@elara:~/SSL/Server> 
Create server private key (ImportPrivKey.pem) and CSR (ImportCsr.pem)
Generating a 2048 bit RSA private key
...+++
.........................................+++
writing new private key to ‘ImportPrivKey.pem’
-----
You are about to be asked to enter information that will be incorporated

into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ‘.’, the field will be left blank.
-----
US (2 letter code) [US]:
Washington [Washington]:
Olympia []:
Townsend Security, Inc. [Townsend Security, Inc.]:
akm_server [akm_server]: akm_import
Common Name (eg, server’s name) []:elara
Email Address []:server@ptss.com

This command will create the following files in your ~/Server directory:

ImportCsr.pem
ImportPrivKey.pem

This command will allow you to look at the new CSR in a text file:

openssl req -noout -text -in ImportCsr.pem -out ImportCsr.txt

Converting the key export CSR to a signed certificate

Once you have created a certificate signing request you need to present it to a certificate authority to be signed.

You send this: ImportCsr.pem –> CA

You get this back: ImportSignedCert.pem <– CA

Do NOT send the private key file to the CA.

If you are using a public CA check with their policy documents to determine how to proceed. You will need to send them the CSR file and will get a signed certificate in return.

If you are creating and using your own CA follow the instructions in Chapter 11: Signing a CSR with Your Own CA.

Installing the import private key and certificate

Once the CA has signed the import certificate there will be two files that need to be installed on other machines:

ImportSignedCert.pem 
ImportPrivKey.pem 

The ImportSignedCert.pem file is given to your partner who will use it to encrypt the keys they send to you.

The ImportPrivKey.pem file will need to be installed in the AKM server using the AKM Administrative Console.

 

Chapter 11: Signing a CSR with Your Own CA

If you have set up your own certificate authority you will need to sign the CSRs to produce signed certificates for your users.

Copy the CSR file to your ~/CA directory and run the following command:

openssl ca -config ./opensslCA.cnf -policy policy_anything 
-infiles SomeCsr.pem -out SomeSignedCert.pem

To view the contents of the newly signed certificate use this command:

openssl x509 -text -in SomeSignedCert.pem -out SomeSignedCert.txt

After signing the CSR the newly created certificate will need to be placed in the appropriate place on the target system.

 

Chapter 12: Creating and Securing the Key Encryption Key (KEK)

The AKM server uses an internal symmetric key called the “key encryption key” or “KEK”. This key is used to protect the values of the symmetric keys stored in the database.

The KEK is created at the Initial setup time and must be in place before AKM can be used to create and access keys.

In order for the KEK to be created there must be a 2048-bit RSA private key and a corresponding certificate created and stored on the server.

To create the RSA private key and certificate you can follow the instructions in Chapter 6: Creating a Key and CSR for the AKM Server Instead of creating the files ServerPrivKey.pem, ServerCsr.pem and ServerSignedCert.pem, you will create the files KekPrivKey.pem, KekCsr.pem and KekSignedCert.pem.

Use this command:

openssl req -new -newkey rsa:2048 -nodes -config ./opensslServer.cfg 
-rand ./randomServer.dat -keyout KekPrivKey.pem  -out KekCsr.pem 

Your certificate authority should be instructed to use KekCsr.pem to create a certificate with the name KekSignedCert.pem.

The KekPrivKey.pem and KekSignedCert.pem files must be installed on the AKM server. You can use the AKM Configuration and Management tool to do this.

The KekCsr.pem file may be deleted after the certificate is created.

 

Chapter 13: Creating and Securing the Authentication Key (AK)

The authentication key is created at Initial Setup time and must be in place before AKM can be used to create and access keys.

In order for the create-auth-key program to run there must be a 2048-bit RSA private key and a corresponding certificate created and stored on the server.

To do this you can follow the instructions in Chapter 6: Creating a Key and CSR for the AKM Server Instead of creating the files ServerPrivKey.pem, ServerCsr.pem and ServerSignedCert.pem, you will create the files AuthPrivKey.pem, AuthCsr.pem and AuthSignedCert.pem.

Use this command:

openssl req -new -newkey rsa:2048 -nodes -config ./opensslServer.cfg 
-rand ./randomServer.dat -keyout AuthPrivKey.pem  -out AuthCsr.pem 

Your certificate authority should be instructed to use AuthCsr.pem to create a certificate with the name AuthSignedCert.pem.

The AuthPrivKey.pem and AuthSignedCert.pem files must be uploaded to the server using the AKM Configuration and Management tool.

The AuthCsr.pem file may be deleted after the certificate is created.

Chapter 14: Certificate Authority Compromise

The compromise of a Certificate Authority (CA), whether public or private, impacts all systems that depend on certificates and private keys generated by the Certificate Authority for authentication, privacy, and access control. Such systems might include web servers, virtual private networks (VPNs), secure FTP servers, and many other types of secure services. Alliance Key Manager uses certificates and private keys to authenticate and secure connections for encryption and key retrieval services, and would be affected by the compromise of a CA. In the event of a compromise of the CA that you use to create AKM server and client certificates, you should take prompt action to replace the certificates and private keys, in the same way that you would for any application or web service. The following steps should be helpful if you must perform this operation.

Root and Intermediate CA Certificates

Alliance Key Manager depends on the Root CA certificate and optionally an Intermediate CA certificate to authenticate client-side connections to the key server. In the event of a compromise of a Certificate Authority, you must create a new CA root certificate and you must install it on the Alliance Key Manager in the appropriate directory (see above chapters for information about installing the public CA on the key server). Remember to update the Alliance Key Manager configuration file akm.conf with the new names of the CA certificates.

Server certificate and private key

Alliance Key Manager contains one server certificate and associated private key. You must replace these files on the key server. Use the same procedure as described in this manual to install the new server certificate and private key.

Client-side certificates and private keys

Alliance Key Manager uses the client-side certificate presented during TLS negotiation to authenticate the user’s or application’s right to access the key server, and the client certificate must be signed by the Root CA and/or Intermediate CA. Therefore, all client-side certificates and private keys must be replaced. You will also need to add the new Root CA to client side key stores.

AKM administrative certificates and private keys

The AKM Administrative Console also uses a client-side certificate and private key to authenticate to the key server. The Organizational Unit (OU) of the administrative certificate has the value akm_admin and identifies the user for administrative operations. You must replace the administrative certificate, private key, and Root CA certificate in the Java Key Store used by the AKM Administrative Console application. See the previous chapters in this manual for information about administrative certificates.

AKM web service certificate and private key

By default Alliance Key Manager contains a self-signed certificate and associated private key for the key server web service. If you are using this default certificate, you do not need to replace the web service and private key. However, if you replaced the default certificate and private key with one signed by the compromised Certificate Authority, you must replace these with a new web server certificate and private key.

AUTH and KEK certificates and private keys

During the installation of Alliance Key Manager you installed a certificates and private keys that Alliance Key Manager uses to protect the symmetric Key Encryption Key and Authentication Key. These certificates and private keys are not validated against the Root CA certificate and you should not replace these files. If you are concerned about the possibility of a breach of the Alliance Key Manager appliance, you should use the key server web service to roll the KEK and AUTH keys. Alliance Key Manager will automatically generate new symmetric keys and re-encrypt all data encryption keys.

 

Appendix A: Setting Up a Certificate Authority on Linux

Overview

In earlier chapters of this document we talked about how to use OpenSSL to create RSA key pairs and certificate signing requests (CSRs). In this appendix we show you how to turn a CSR into a signed certificate by creating and using your own certificate authority.

Here is an overview of the procedure for setting up a CA:

  1. Create a directory for the CA on your system

  2. Create default subdirectories and files

  3. Create your own OpenSSL configuration file

  4. Generate a new random file for your CA

  5. Create the CA’s private key and self-signed certificate

Create a directory for the CA on your system.

In earlier chapters on how to set up OpenSSL we recommended you create a directory for your SSL needs under /home/userName/ssl (where “userName” is your Linux user ID). We will now create a directory under that one called CA and we will refer to this as your “CA directory”.

cd /home/userName/SSL
mkdir CA

In the remainder of this document we will refer to this directory as “~/CA". So, instead of saying “cd to /home/userName/SSL/CA” we will say “cd to ~/CA”.

SECURITY NOTE: Never create a certificate authority on the Alliance Key Manager appliance.

Create default subdirectories and files

Go to your CA directory and create the usual default subdirectories under it:

cd ~/CA
mkdir certs newcerts private

Each certificate that your CA creates will need to have a unique serial number. OpenSSL will keep track of this for you. To facilitate this you need to create and initialize a serial number file named serial in the CA directory:

echo “01” > serial

Create an empty index file for the CA’s internal use:

cd ~/CA
cp  /dev/null  index.txt

Create your own OpenSSL configuration file

OpenSSL uses a configuration file named openssl.cnf.

When creating your own CA we recommend making a copy of this file and modifying its contents to reflect the appropriate default values for your location. When you create certificates you will be prompted for a lot of information, and by initializing this file you can just hit the Enter key to get the correct values.

First you need to find the default configuration file on your system:

cd ~/CA
sudo find / -name openssl.cnf

On our reference system this returns: /etc/ssl/openssl.cnf.

We copy this file to our CA directory. We rename it to avoid confusion with the original:

cp /etc/ssl/opensslCA.cnf  ~/CA/opensslCA.cnf

Modify the opensslCA.cnf file for your CA

In this section we show a listing of the default openssl.cnf file on our system and how we modified it. The lines that we removed are shown commented out with ### (red) and the lines we added will be shown immediately following in green (green). We have also modified the default spacing to make the file easier to read.

Don’t forget that these changes are applied to ~/CA/opensslCA.cnf and not to the default file on your system.

We use names for our sample CA below and you will want to substitute your own values when you see the following:

  • Townsend Security, Inc. - your company name here

  • PTSSCA - your CA name here

  • CountryName - your country here

  • StateOrProvinceName - your state here

  • localityName - your city here

Note that it is beyond the scope of this manual to document all of the configuration options for OpenSSL. Please consult the OpenSSL documentation at www.openssl.org.

Sample modified opensslCA.cnf file

# OpenSSL example configuration file.
# This is mostly being used for generation of certificate requests.

# This definition stops the following lines choking if HOME isn’t
# defined.
###HOME = .
###RANDFILE = $ENV::HOME/.rnd
RANDFILE = ./private/.random.dat

# Extra OBJECT IDENTIFIER info:
#oid_file   = $ENV::HOME/.oid
oid_section	= new_oids

# To use this configuration file with the “-extfile” option of the
# “openssl x509” utility, name here the section containing the
# X.509v3 extensions to use:
# extensions = 
# (Alternatively, use a configuration file that has only
# X.509v3 extensions in its main [= default] section.)

[ new_oids ]
# We can add new OIDs in here for use by ‘ca’ and ‘req’.
# Add a simple OID like this:
# testoid1=1.2.3.4
# Or use config file substitution like this:
# testoid2=${testoid1}.5.6

###################################################################
[ ca ]
default_ca = CA_default	# The default ca section

###################################################################
[ CA_default ]
###dir = ./demoCA		# Where everything is kept
dir = .
certs	 = $dir/certs		# Where the issued certs are kept

crl_dir	 = $dir/crl		# Where the issued crl are kept
database = $dir/index.txt# database index file.
#unique_subject = no	# Set to ‘no’ to allow creation of
					    	# several ctificates with same subject.
new_certs_dir = $dir/newcerts	# default place for new certs.

###certificate= $dir/cacert.pem 	# The CA certificate
certificate	= $dir/CASelfSignedCert.pem
serial		= $dir/serial 		# The current serial number
crlnumber	= $dir/crlnumber	# the current crl number
								# must be commented out to leave a V1 CRL
crl	= $dir/crl.pem 				# The current CRL

###private_key = $dir/private/cakey.pem # The private key
private_key  = $dir/private/CAPrivateKey.pem

###RANDFILE	= $dir/private/.rand	# private random number file
RANDFILE	= $dir/private/.random.dat

x509_extensions	= usr_cert	# The extentions to add to the cert

# Comment out the following two lines for the “traditional”
# (and highly broken) format.
name_opt = ca_default	# Subject Name options
cert_opt = ca_default	# Certificate field options

# Extension copying option: use with caution.
# copy_extensions = copy

# Extensions to add to a CRL. Note: Netscape communicator chokes on V2 CRLs
# so this is commented out by default to leave a V1 CRL.
# crlnumber must also be commented out to leave a V1 CRL.
# crl_extensions = crl_ext

###default_days = 365  # how long to certify for
default_days = 9000
default_crl_days = 30	# how long before next CRL
default_md = sha1		# which md to use.
preserve = no			# keep passed DN ordering

# A few difference way of specifying how similar the request should look
# For type CA, the listed attributes must be the same, and the optional
# and supplied fields are just that :-)
policy	= policy_match

# For the CA policy
[ policy_match ]
countryName	= 			 match
stateOrProvinceName	= 	 match
organizationName = 		 match
organizationalUnitName =	optional
commonName = 			supplied
emailAddress =			 	optional


# For the ‘anything’ policy
# At this point in time, you must list all acceptable ‘object’
# types.
[ policy_anything ]
countryName = 			 	optional
stateOrProvinceName	= 	optional
localityName = 			 	optional
organizationName = 		optional
organizationalUnitName = 	optional
commonName = 			supplied
emailAddress = 			optional

###################################################################
[ req ]
###default_bits = 1024
default_bits  = 2048
###default_keyfile = privkey.pem
default_keyfile  = CAPrivateKey.pem
distinguished_name = req_distinguished_name
attributes = req_attributes
x509_extensions = v3_ca	# The extentions to add to the self signed cert

# Passwords for private keys if not present they will be prompted for
# input_password  = secret
# output_password = secret

# This sets a mask for permitted string types. There are several options. 
# default: PrintableString, T61String, BMPString.
# pkix	 : PrintableString, BMPString.
# utf8only: only UTF8Strings.
# nombstr : PrintableString, T61String (no BMPStrings or UTF8Strings).
# MASK:XXXX a literal mask value.
# WARNING: current versions of Netscape crash on BMPStrings or UTF8Strings
# so use this option with caution!
string_mask = nombstr

# req_extensions = v3_req # The extensions to add to a certificate request

[ req_distinguished_name ]
###countryName= Country Name (2 letter code)
countryName = US
###countryName_default = AU
countryName_default  = US
countryName_min	= 2
countryName_max	= 2

###stateOrProvinceName = State or Province Name (full name)
stateOrProvinceName   = Washington
###stateOrProvinceName_default = Some-State
stateOrProvinceName_default = Washington

###localityName = Locality Name (eg, city)
localityName  = Olympia

###0.organizationName	= Organization Name (eg, company)
0.organizationName	= Townsend Security, Inc.
###0.organizationName_default	= Internet Widgits Pty Ltd
0.organizationName_default	= Townsend Security, Inc.

# we can do this but it is not needed normally 
#1.organizationName	    	= Second Organization Name (eg, company)
#1.organizationName_default	= World Wide Web Pty Ltd

###organizationalUnitName	= Organizational Unit Name (eg, section)
organizationalUnitName = PTSSCA
#organizationalUnitName_default  =
organizationalUnitName_default  = PTSSCA

commonName = Common Name (eg, YOUR name)
commonName_max = 64

emailAddress = Email Address
emailAddress_max = 64

# SET-ex3 = SET extension number 3

[ req_attributes ]
challengePassword = A challenge password
challengePassword_min = 4
challengePassword_max = 20

unstructuredName = An optional company name

[ usr_cert ]
# These extensions are added when ‘ca’ signs a request.
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints = CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.
# nsCertType = server

# For an object signing certificate this would be used.
# nsCertType = objsign

# For normal client use this is typical
# nsCertType = client, email

# and for everything including object signing:
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape’s comment listbox.
nsComment = “OpenSSL Generated Certificate”

# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer

# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren’t
# deprecated according to PKIX.
# subjectAltName=email:move

# Copy subject details
# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

[ v3_req ]
# Extensions to add to a certificate request
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment

[ v3_ca ]
# Extensions for a typical CA
# PKIX recommendation.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always

# This is what PKIX recommends but some broken software chokes on critical
# extensions.
#basicConstraints = critical,CA:true
# So we do this instead.
basicConstraints = CA:true

# Key usage: this is typical for a CA certificate. However since it will
# prevent it being used as an test self-signed certificate it is best
# left out by default.
# keyUsage = cRLSign, keyCertSign

# Some might want this also
# nsCertType = sslCA, emailCA

# Include email address in subject alt name: another PKIX recommendation
# subjectAltName=email:copy
# Copy issuer details
# issuerAltName=issuer:copy

# DER hex encoding of an extension: beware experts only!
# obj=DER:02:03
# Where ‘obj’ is a standard or added object
# You can even override a supported extension:
# basicConstraints= critical, DER:30:03:01:01:FF

[ crl_ext ]
# CRL extensions.
# Only issuerAltName and authorityKeyIdentifier make any sense in a CRL.

# issuerAltName=issuer:copy
authorityKeyIdentifier=keyid:always,issuer:always

[ proxy_cert_ext ]
# These extensions should be added when creating a proxy certificate
# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.
basicConstraints=CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.
# This is OK for an SSL server.
# nsCertType = server

# For an object signing certificate this would be used.
# nsCertType = objsign

# For normal client use this is typical
# nsCertType = client, email

# and for everything including object signing:
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape’s comment listbox.
nsComment = “OpenSSL Generated Certificate”

# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer:always

# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren’t
# deprecated according to PKIX.
# subjectAltName=email:move

# Copy subject details
# issuerAltName=issuer:copy

#nsCaRevocationUrl = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

# This really needs to be in place for it to be a proxy certificate.
proxyCertInfo=critical,language:id-ppl-anyLanguage,pathlen:3,policy:foo

Generate a new random file for your CA

OpenSSL uses a file containing random information. We recommend creating a random file for use by your CA. Note that this file’s name and location should match the RANDFILE variable in your ~/CA/opensslCA.cnf file:

cd ~/CA
openssl rand -out ./private/randomCA.dat 1024

Create the CA’s private key and self-signed certificate

Before we run the command to create the CA’s private key and self-signed certificate let’s review a couple of ideas as they relate to our CA.

IMPORTANT: Alliance Key Manager allows for the use of CA certificates that are signed by a different certificate authority. Alliance Key Manager will only verify additional certificate authorities to a maximum depth of 3.

Certificate expiration dates

Your CA creates a self-signed certificate which contains the CA’s public key. This key is distributed to anyone who needs to use it to verify that you signed a particular certificate. In this case that would be the AKM server and the Crypto Officer and key clients. One of the steps in validating a server or client signed certificate will be to verify that the CA’s self-signed certificate has not expired. There are a couple of edits here so let us explain this in some detail.

When a client opens a TLS session with AKM the following steps are followed:

  1. The client presents its signed certificate to the server

  2. The server examines the certificate to determine which CA signed it

  3. The server sees if this CA has a self-signed certificate stored on the server

  4. The server inspects the self-signed certificate to see if it has expired

  5. If the CA’s certificate has expired, the session is not established

  6. The server inspects the client’s certificate to see if it has expired

  7. If the client’s certificate has expired, the session is not established

  8. The server uses the CA’s certificate to verify the signature in the client’s certificate

Note that if either the CA’s self-signed certificate or the client’s certificate has expired, the session will not be established. Thus an error will occur if the CA’s certificate has expired even though the client’s certificate has not.

Because of this restriction you must pay close attention to the dates for which you allow your CA’s self-signed certificate to be valid. If it expires you will need to generate a new one and distribute to all the systems that use it.

You can specify a large value for the number of days for a certificate to be valid but the maximum value is about 10,000 (almost 29 years). If you use a larger value than that, OpenSSL will wrap your date to December 1901 and all certificates will be expired and unusable. The AKM server will not run with expired certificates.

Key sizes

As previously mentioned RSA keys come in a variety of lengths measured in bits. Your CA’s RSA keys must be 2048 bits long.

Creating the CA’s private key and self-signed certificate

The following procedure will create a private key for your CA named CAPrivKey.pem. It will also create a self-signed certificate named CASelfSignedCert.pem.

The -days nnnn parameter can be left out in which case the default_days value specified in your opensslCA.cnf file will be used. Use -days if you want to override the value in the configuration file. This value will be the number of days for your CA’s self-signed certificate to be valid.

The -config parameter tells OpenSSL to use your CA’s opensslCA.cnf file instead of the default file located on the machine:

cd ~/CA

openssl req -new -newkey rsa:2048 -days 1095 -nodes -x509 -config ./opensslCA.cnf 

-rand ./randomCA.dat -keyout CAPrivKey.pem -out CASelfSignedCert.pem 

You will then be prompted for information as follows:

Generating a 2048 bit RSA private key
.............+++
................................................................+++
writing new private key to ‘CAPrivateKey.pem’
-----
You are about to be asked to enter information that will be incorporated
into your certificate request.

What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter ‘.’, the field will be left blank.
-----
Note: If you hit the Enter key the values will be taken from the opensslCA.cnf file.
Country Name (2 letter code) [US]:
Washington [Washington]:
Olympia []:
Townsend Security, Inc. [Townsend Security, Inc.]:
PTSSCA [PTSSCA]:

Note: These values will not be in your configuration file and must be entered. Replace the values shown below with your own information.
Common Name (eg, YOUR name): elara
Email Address: CA@PTSS.com

You can inspect the new certificate (which is in a binary format) by converting it to a text file:

openssl x509 -text -in CASelfSignedCert.pem -out CASelfSignedCert.txt

Installing your CA’s self-signed certificate on other systems

If you are going to sign your own certificates you need to install them onto the systems that will need to use them. Copy the CASelfSignedCert.pem file to the following locations:

AKM server

Installing the CA self-signed certificate on the AKM server is done through the AKM Configuration and Management tool.

Once the self-signed certificate is placed on the server in the CACerts directory you need to tell AKM to use the certificate. Place the name of the certificate in the AKM configuration file. You also use the AKM Configuration and Management tool to edit the configuration file.

Add the following entry to the conf file in the [cert] section (See the AKM Server Management Guide for more information on using the AKM configuration file):

TrustedCACert=CASelfSignedCert

Notes:

  • Do not put spaces around the “=“ sign

  • Do not use the “.pem” extension in the certificate name

  • Maximum of 64-character name which is case sensitive

  • You may enter multiple lines if you have multiple trusted CA certificates

Administration client

If you have used your own CA to sign the AKM server’s certificate you will need to install your self-signed certificate on the Crypto Officer’s machine.

This self-signed certificate will be used to validate the server’s signed certificate at session establishment.

Key client

If you have used your own CA to sign the AKM server’s certificate you will need to install your self-signed certificate on all key client machines.

This self-signed certificate will be used to validate the server’s signed certificate at session establishment.

If you are using the requestor client shared object on Linux provided by Townsend Security you will need to create a directory to hold the self-signed certificate and make an entry in the akmclient.conf file that identifies this directory under the [cert] section.

For example:

[cert]

TrusedCACertDir=~/.akm/CACerts

TrustedCACert=~/.akm/CACerts/CASelfSignedCert.pem

On Windows you can use the DLL or .NET Assembly provided by PTSS and the certificates are installed in the Windows Certificate Manager. On the IBM i the certificates are installed using IBM Digital Certificate Manager (DCM).

 

Appendix B: Setting Up a Certificate for Use on Windows

On a Windows system you must bundle the keys and certificates into a PKCS#12 formatted file which will have a .p12 extension. Use these commands to create the p12 bundle file.

Once you have a signed certificate for a Crypto Officer or key client you will need to bundle that certificate with the CA’s self-signed certificate in a single file.

To do this open a command prompt and issue the following command using your file names and in the order shown below (note the use of the “+” symbol):

Copy /B YourSignedCert.pem+CASelfSignedCert.pem YourBundledCerts.pem

openssl pkcs12 -in YourBundledCerts.pem -inkey YourPrivateKey.pem –export

-out YourBundledCerts.p12.

The YourBundledCerts.p12 file can be opened by double clicking on a Windows platform. You will be prompted for a pass phrase.

Appendix C: Converting to PEM Format

Key and certificate files occur in a variety of formats:

  • CER

  • CRT

  • DER

  • PEM

  • PKCS#7

  • PKCS#12

  • and more…

Alliance Key Manager requires that certificates be in PEM format.

We assume you have used OpenSSL, as shown in this document, to create your private keys and certificates. If so, they will be in PEM format. If you are given a certificate in a format other than PEM from a certificate authority or a trading partner, you can use OpenSSL to convert it to PEM format.

NOTE: The following examples show input file names with extensions like “.der” or “.p12” for clarity. However, the OpenSSL command does not rely on the value of this extension. In fact your file may not have an extension at all.

Convert from DER format to PEM:

openssl x509 –in CertName.der –inform DER –out CertName.pem –outform PEM

Convert from PKCS#12 to PEM:

openssl pkcs12 -in CertName.p12 -out CertName.pem

Appendix D: Glossary

The following terms are used in this manual:

Certificate Authority (CA)

A certificate authority is a security group with the tools needed to create public keys, private keys, and certificates. These keys and certificates are used for a variety of purposes including encryption, secure connections, digital signatures, and so forth. You can use a private certificate authority, or a public certificate authority such as VeriSign or Thawte. You can create more about certificate authorities and public/private key infrastructure here and here.

Certificate Authority (CA) certificate

Each certificate authority publishes a Certificate Authority certificate. This certificate is used to validate that a client certificate is valid and trusted. You will normally distribute the CA certificate to client applications with a client certificate.

Certificate signing request (CSR)

A certificate signing request is a template certificate created by a client system. The CSR is presented to a Certificate Authority for signing. The result is a certificate that can then be imported to the client key store. The IBM System I Digital Certificate Manager requires that certificates be created using a CSR. You can read more about certificate signing requests here.

Client certificate

A client certificate is an X.509 certificate that has been signed by the CA Certificate of the key server. In a TLS session, the client certificate is presented to the server for authentication and validation.

PEM format

There are several storage formats for X.509 certificates, and Privacy Enhanced Email (PEM) is one of the common ones. The PEM format is defined in a series of IETF RFCs including RFC1421, RFC1422, RFC1423, and RFC1424.

PKCS12 format

The Windows key store works with PKCS12 certificates and cannot import a PEM formatted certificate. You can convert a PEM certificate to PKCS12 format using the OpenSSL command line application.

Private key

A private key is one half of a public/private key pair. Private keys should not be shared with others and you should take care to protect a private key from loss.

Public key

A public key is one half of a public/private key pair. Public keys are often distributed to client end points that will connect to the server, or to remote mirror servers. Usually a public key is distributed in a public certificate. The standard used for these certificates is X.509 in PEM format.

X.509 certificate

A certificate contains an encryption key and other information describing attributes of the public key. The X.509 standard for certificates is used by Alliance Key Manager. You can read a good overview of X.509 here.