Requesting and creating certificates for OpenSSL

Follow the instructions in this section to obtain a certificate from a trusted certificate authority or to generate your own self-signed certificate for local use or testing purposes. These instructions apply to HTTPS applications and xfServer, xfServerPlus, and SQL OpenNet encryption.

Requesting a certificate from a certificate authority

Follow these instructions to obtain a certificate from a trusted certificate authority so your server or client can be authenticated. This procedure can be used when developing an HTTPS server (or authenticated client), as well as for xfServer, xfServerPlus, and SQL OpenNet encryption.

Use the openssl utility to create a certificate request and key file. The syntax is

openssl req -out cert_file [-keyout key_file] -newkey rsa:bits -config config_file [-nodes]

where cert_file is the name of the file to write the certificate request to, key_file is the name of the file to write the private key to, bits is the size in bits of the new RSA private key, and config_file is the name of your configuration file. (See Customizing the configuration files for more information.) If the -keyout option is not specified, the private key filename specified in the configuration file is used as key_file. If you are requesting this certificate for use with SQL OpenNet data packet encryption, you may need to include the -nodes option; else, omit it.

The example below creates a new certificate request file, testreq.pem, and a new private RSA key file, testkey.pem, using configuration file openssl.cfg (which is a sample distributed with OpenSSL). The new private key will be 2048 bits. The certificate request file will contain the country, state, city, organization, department, and common name and email address of the requester.

openssl req -out testreq.pem -keyout testkey.pem -newkey rsa:2048 -config openssl.cfg

Send the certificate request file generated in step 1 to a public certificate authority, such as VeriSign or Thawte, along with any necessary fees.

The certificate authority will send back a certificate that can be used to authenticate a server or client.

Exporting and importing certificates in Windows

One way to get a list of trusted Certificate Authorities is to export it from Microsoft Windows, which maintains its own list. For convenience, you can use this list as a CA file in the openssl utility or for the CA_file argument in the Synergy HTTP document transport API routines.

Exporting certificates

To export certificates for use with OpenSSL or the Synergy HTTP document transport API,

Open the Windows Control Panel and select Internet Options.

Select the Content tab and click the Certificates button.

Select the Trusted Root Certification Authorities tab.

Select all of the certificates in this dialog box and click the Export button.

Follow the Certificate Export Wizard to create a .p7b file.

Use the openssl utility to convert the file to PEM format:

openssl pkcs7 -inform DER -outform PEM -in file.p7b -out file.pem -print_certs

The file.pem file can now be specified in the openssl utility or as the CA_file argument in the Synergy HTTP document transport API.

Importing certificates

If you want to add trusted certificates to the list in Windows, you can import certificates as follows:

Open the Windows Control Panel and select Internet Options.

Select the Content tab and click the Certificates button.

Select the Trusted Root Certification Authorities tab.

Click the Import button.

Follow the Certificate Import Wizard and select the PEM file you want to include as a trusted CA.

Creating a local certificate authority

If you want to test your HTTPS, xfServerPlus, or SQL OpenNet application locally, without going through a public certificate authority, you can establish a local certificate authority. You’ll use the openssl utility to create a local CA and then use it to generate a certificate. (In the actual production world, of course, you would use a public CA, such as VeriSign or Thawte.) For xfServer, you may want to use a local certificate authority instead of a public certificate, since xfServer is a proprietary format.

On Windows, perform this procedure from an administrator command prompt. If you don’t, you may see the error “unable to write ‘random state’.”

These examples assume that the CA directory structure is already set up and the relevant files already exist. This is required if you use the “openssl ca” option in step 5. For the example configuration file (caopenssl.cfg), you would need subdirectories named certs, newcerts, and private; an empty index.txt file; and a file named serial containing “01”. This sample configuration file is included in Customizing the configuration files.

Before we can begin issuing certificates with our local CA, it needs a certificate of its own, so we’ll create a self-signed root certificate. The req command below is used to create the certificate request file rootreq.pem and private key file rootkey.pem. The key will be 2048 bits and the configuration file used will be caopenssl.cfg. If you are creating this certificate for use with SQL OpenNet data packet encryption, include the -nodes option; otherwise, omit it.

openssl req -out rootreq.pem -keyout rootkey.pem -newkey rsa:2048 -config caopenssl.cfg [-nodes]

(When prompted to “Enter Pem Pass Phrase,” enter the pass phrase, or password, that will later be required to access the certificate, and then enter it a second time to confirm when prompted. You can later remove this pass phrase if you don’t want to be prompted for it each time you access the certificate; see step 6. You may also be prompted for other information that will be incorporated into the certificate request; see Customizing the configuration files for more information. )

Next, the x509 command with the -req option is used to read the rootreq.pem file created above and create a root certificate in the rootcert.pem file. The -signkey option causes rootreq.pem to be self-signed using the private key rootkey.pem. The configuration file, caopenssl.cfg, contains certificate extensions to use. If -extfile is not specified, no extensions are added to the certificate.

openssl x509 -req –in rootreq.pem -out rootcert.pem -signkey rootkey.pem –extfile caopenssl.cfg

(Optional) The following cat command simplifies things for testing purposes. It concatenates the certificate file (rootcert.pem) and the key file (rootkey.pem) to yield a concatenated file called root.pem. This file will be used when signing certificates in step 5.

cat rootcert.pem rootkey.pem > root.pem

On Windows, use the type command instead:

type rootcert.pem rootkey.pem > root.pem

Create a certificate request and key file for your test program. This uses the same openssl req syntax as above. We name the certificate request testreq.pem and the key file testkey.pem. Once again, you may be prompted for additional information.

openssl req -out testreq.pem -keyout testkey.pem -newkey rsa:2048 -config caopenssl.cfg

Create the certificate requested in the previous step and sign it using your local CA. In most cases, you can use either the openssl ca command or the openssl x509 command, but for xfServerPlus encryption, you must use x509.

The ca command is a minimal CA application. In the example below, testreq.pem is the file containing the certificate request to be signed by the local CA, testcert.pem is the file to return signed certificates to, and caopenssl.cfg is the configuration file.

openssl ca -in testreq.pem -out testcert.pem -config caopenssl.cfg

Alternatively, you could use the x509 command, which is a multi-purpose certificate utility. When the -CA option is present, the x509 command behaves like a minimal CA application. In the example below, testreq.pem is the file containing the certificate request to be signed by the local CA, -extfile adds certificate extensions from the configuration file caopenssl.cfg, root.pem is the CA certificate to be used for signing, CAkey is the private key to sign the certificate with, and testcert.pem is the file to return signed certificates to. (If the -CAkey option is not specified, it is assumed that the CA private key is present in the CA certificate file.) The -CAcreateserial option creates the CA serial number file if it does not exist. Future signing requests for this local CA should use -CAserial root.srl so the serial number can be incremented.

openssl x509 -req -in testreq.pem -extfile caopenssl.cfg -CA root.pem -CAkey root.pem 
-out testcert.pem -CAcreateserial

If any encryption options are set, a pass phrase will be prompted for whenever the key file is accessed. If you want to remove the pass phrase from an RSA private key, use the openssl rsa command. For example,

openssl rsa -in testkey.pem -out testkeyout.pem

where testkey.pem is the file containing the private key and testkeyout.pem is the file to write the updated key to. If you are using a concatenated certificate and key file, after removing the pass phrase, you must reconcatenate the two files.

Step 6 is a security risk on a public certificate, but it is convenient for local testing and is required for creating an xfServer/xfServerPlus certificate on Windows or OpenVMS and for data packet encryption with SQL OpenNet.

Concatenate the certificate (testcert.pem) and key file (testkeyout.pem, assuming you removed the pass key in step 6; otherwise, this would be testkey.pem). This step is required for xfServer and xfServerPlus encryption but optional for HTTPS. Do not do this for SQL OpenNet, where these files must remain separate. (For xfServer and xfServerPlus, you may want to name this file rsynd.pem; if you then put it in DBLDIR, it will be used by default.) For example,

cat testcert.pem testkeyout.pem > certkey.pem

On Windows, use the type command instead:

type testcert.pem testkeyout.pem > certkey.pem

When you are done creating the files, put them in the appropriate places for your application. Typically, clients validate the server, so you would put the certificate and key files (or the concatenated certkey.pem file) on the server and the rootcert.pem file on the client.

Customizing the configuration files

You’ll want to customize your own configuration file (for example, with your own company name and email address, number of days to certify for, etc.) and use that file to to create the certificate or certificate request. To specify a configuration file in the openssl utility, use the -config option.

If “prompt = yes” is set in the configuration file, you'll be prompted for information such as the common name, state or province, etc. These fields will be left blank if you do not enter a value. (You must enter a value in at least one of them, or the file will not be created.) You may find it more efficient to include the prompted information in the configuration file (in the section labeled “[ root_ca_distinguished_name ]”) and then set “prompt = no” (just above that section).

If you are using this configuration file with an xfNetLink .NET application, commonName must match the xfServerPlus host name as it is passed in the connect() method. If it does not, you’ll see the error “The remote certificate is invalid according to the validation procedure” at runtime. See Synergex KnowledgeBase article 2375 for additional information.

The following caopenssl.cfg file is used in the examples in Creating a local certificate authority.

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

####################################################################
[ CA_default ]
dir             = . # 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
new_certs_dir   = $dir/newcerts # Default place for new certs
certificate     = $dir/rootcert.pem # The CA certificate
serial          = $dir/serial # The current serial number
crl             = $dir/crl.pem # The current CRL
private_key     = $dir/root.pem # The private key
RANDFILE = $dir/private/.rand # Private random number file

x509_extensions = certificate_extensions # Extensions to add to the cert

# 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.
# crl_extensions = crl_ext

default_days     = 365 # How long to certify for
default_crl_days = 180 # How long before next CRL
default_md       = md5 # which md to use
preserve         = no # keep passed DN ordering

# A few different ways 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 ]
commonName      = supplied
stateOrProvinceName = supplied
countryName     = supplied
emailAddress    = supplied
organizationName = supplied
organizationalUnitName = optional

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

[ certificate_extensions ]
basicConstraints = CA:false

[ req ]
default_bits    = 2048
default_keyfile = rootkey.pem
default_md      = md5

prompt = yes 
distinguished_name = root_ca_distinguished_name
x509_extensions = root_ca_extensions

[ root_ca_distinguished_name ]
commonName = localhost
stateOrProvinceName = California
countryName = US
emailAddress = jane.smith@MyCompany.com
organizationName = MyCompany

[ root_ca_extensions ]
basicConstraints = CA:true