Note: This article consists of a procedure description (this section) and an example scenario with step-by-step commands below.

Introduction

Many customers have a corporate Certificate Authority and a requirement that e.g. web server certificates are issued by this CA.

There may be multiple ways to get a host certificate from an external CA into BoKS. This article describes a method for doing so through a combination of existing tools and two custom utility scripts. The article first gives an overview as well as a summary of the procedure and after that shows an example with the involved commands.

Note:

The procedure outlined in this article makes use of two custom scripts: mkhostvc.sh and vcrenewbyextca.sh. These scripts are not currently installed with any FoxT products, but are attached to this article and can otherwise be obtained from FoxT Customer Services.

Overview

Basically what needs to be done is to create a Private Key with a supported key length. Then create the corresponding Public Key and wrap that up in a PKCS#10 Certificate Request (aka Certificate Signing Request or CSR).

The CSR can be sent to the corporate Certificate Authority and a signed certificate should then be returned along with the corresponding CA certificate chain (known as the issuer of the returned certificate). Sometimes there is only a Root CA used to sign the certificate (as we do for host certificates in BoKS) but more often a sub-ordinate CA is used to sign end entity certificates. In that case the chain will thus consist of two CA certificates - the root and the sub-ordinate CA.

The signed host certificate and the private key are then incorporated into a BoKS host Virtual Card file which can be stored in the BoKS database. From there on we can again export the host VC and import it along with the CA chain into the Java Keystore file used by the FCC Presentation Server part of the FoxT Control Center (aka BCCPS).

Summary of the steps involved

The method outlined here uses the host certificate in BoKS and a new private key to create a Certificate Request.

mkhostvc.sh - Create a new host certificate from BoKS internal CA

The current host certificate will be used as a template for the Certificate Request. The mkhostvc.sh script can be used to create a new host VC signed by the BoKS internal CA. It is optional and is only needed if the commonName certificate attribute needs to be tweaked in any way, e.g. to use the FQDN (when the BoKS host is registered with the non-qualified name) or some specific identifier defined and required by the corporate CA.

vcrenewbyextca.sh - Import a host certificate signed by an external CA

This script is used for two purposes:

1. With the -e option it will generate a private RSA key and store this in an encrypted file (in $BOKS_tmp). It will then create a Certificate Request and print this on stdout (the screen). The Certificate Request can then be sent to the CA.

2. When the Certificate Request has been signed and the corresponding host certificate has been returned, vcrenewbyextca.sh is again executed, this time with option -i. The host certificate and the private key will then be incorporated in a BoKS Virtual Card file and stored in the database.

There are a few caveats here:

- There is currently no verification that the private key and the certificate correspond to one another. The correct certificate must be supplied to the script or a corrupt VC will be created.

- The correct BoKS hostname must be entered or the VC may be associated with the wrong host entry in the database.

- If the host certificate will be used by FCC and the CA has defined the Extended Key-usage attribute in the new certificate, its value must include both serverAuth and clientAuth. ServerAuth is required for BCCAS to be authenticated to BCCPS (the presentation server) and clientAuth is required for BCCPS to be authenticated to BCCAS (the administration server). Host certificates issued by BoKS internal CA do not (by default) have the Extended Key-usage extension.

Import the Chain of CA Issuer Certificates to BoKS

As soon as the CA has returned the signed host certificate along with the CA certificate chain, the CA certificates should be imported to the BoKS database. This can be done by pasting the contents of the .cer file(s) directly in the Import CA Certificate menu in FCC (or the old BoKS Administration interface), or using the cacreds command line utility. Make sure to import the Root CA first.

Done?

At this point the new external host certificate is stored in BoKS. The BoKS daemons must be restarted for the new certificate to take effect. This may break the communication with FCC since the new issuer CA certificates are as yet unknown to BCCPS. However, the old TCL-based administration GUI should work and the new host certificate be in use.

bccgethostcert - Export the host certificate, private key and CA chain for FCC

This utility is located in $BOKS_sbin (/opt/boksm/sbin by default). This will create two files:

- A PKCS#12 file containing the private key and the host certificate.

- A file containing the external CA certificates.

This script will prompt for a password to use for encryption of the PKCS#12 file. It is important to use the same password as used for the Java Keystore file (trustfile.jks) in FCC. (The keystore password is stored in the bcc.properties file in the $BCCPS_etc directory, /etc/opt/bccps/bcc.properties by default).

createtrust.sh - Create the Java Keystore file in FCC

This utility is located in the $BCCPS_sbin directory (default /opt/bccps/sbin). It takes the files produced by bccgethostcert, the password of the PKCS#12 file and the password of the Java Keystore file (which must be identical) and creates the trustfile.jks.

Verify the communication

The communication from the FCC Presentation Server to the bccasd server in BoKS can be verified by running $BCCPS/sbin/pingbccas.sh.

If the Presentation Server is run as a functional user, it is important that the trustfile.jks is owned by that user for the communication to work.

If all is functioning correctly, FCC must be restarted to pick up the new Java Keystore and start using the new certificate.

Note:

It is hard to guarantee that the certificate returned by the CA is accurate and will work in the BoKS environment. Problems with the included attributes and extensions may potentionally arise. As a last resort should it be impossible to make it work, a new certificate can again be issued using the BoKS internal CA (e.g. using the mkhostvc.sh utility).

See also the standards document RFC 5280 "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile" that specifies a profile for X.509v3 certificates used on the Internet.


Example Scenario: Renew the BoKS Master host certificate by an external CA

In the following scenario it is assumed that the new host certificate should be issued for the BoKS Master. The same scenario can be applied for a BoKS Replica or other host. In this particular case the symbol $(hostname) can be used in Korn Shell and Bash and will be substituted by the hostname of the current host (i.e the BoKS Master itself).

Note: If you haven't initialized the BoKS CA yet you should run fccsetup first.

mkhostvc.sh - create a new host certificate signed by BoKS internal CA

Note: This script is currently not distributed with BoKS Manager nor FCC but is attached to this article and can otherwise be obtained from FoxT Customer Services.

Note: You only need to use mkhostvc.sh if the current host certificate doesn't have the FQDN set in the commonName attribute or if your CA has some special demands on the commonName attribute (like an identification number or similar). See below for how to use the usrcreds and certinfo commands to view the contents of the current host certificate.

Run mkhostvc.sh to get a new host certificate with the FQDN in the commonName certificate attribute. Use your BoKS root CA to sign the certificate. If you have choosen to save the CA password to file when you created the CA (by e.g. fccsetup), it is available in $BOKS_data/sso_creds/ca_creds/keypkgs/;.pin

To get a list of the BoKS CAs, either list (with the ls command) $BOKS_data/sso_creds/ca_creds/keypkgs or run cacreds list -v. Note that you can identify a Root CA by looking at the issuer- and subject distinguished names - these are always equal for Root CAs. (Likewise the Subject- and Authority Key Identifier extensions are equal for Root CAs, when present in the certificate).

Usage: mkhostvc.sh -h host -n CADname [-p CApwfile][-c commonName][-v years][-o][-q]

# mkhostvc.sh -h $(hostname) -n 'CN=Admin Root CA,O=FoxT Labs,C=SE' -p $BOKS_data/sso_creds/ca_creds/keypkgs/'CN=Admin Root CA,O=FoxT Labs,C=SE;'*.pin -c $(hostname).demo.local -v 5 -o

View the contents of the host certificate
If you would like to view the new certificate, you can retrieve it from the BoKS database with the usrcreds command and view it with certinfo:

# usrcreds get -c -k $(lh -I $(hostname)) > $(hostname).crt
# certinfo -c $(hostname).crt

vcrenewbyextca.sh - create a Certificate Request to be signed by the corporate CA

Note: This script is currently not distributed with BoKS Manager nor FCC, but is attached to this article and can otherwise be obtained from FoxT Customer Services.

Usage: vcrenewbyextca.sh -h host {-e [-l keylength]| -i -c certfile}[-v]

Run vcrenewbyextca.sh -e to create a private key and export a certificate request. The default key length is currently 2048.

# vcrenewbyextca.sh -h $(hostname) -e -v

The certificate request will be printed on STDOUT. Copy and paste the request in to an e-mail or send it to your corporate CA by other means.

Once the certificate request has been signed by the CA you should receive the following files in return:
- The signed host certificate.
- A file containing the chain of CA issuer certificates that signed the host certificate.

Import the CA chain to BoKS
If you haven't done so already, you should import the CA certificates of your corporate CA into BoKS at this point. You can do that using any of the following three methods:
- The FCC Web Administration: Domain -> Certificates -> Import CA
- Old BoKS Web Administration interface: Certificate Authority Administration -> Import CA
- The cacreds set command.

You must start with the Root CA certificate and continue with any sub-ordinate CA in order to import the full CA chain. (If the host certificate was signed by the corporate Root CA, only the Root CA certificate needs to be imported). Classify the CAs as VERIFY in BoKS.

Note: If you use the old BoKS Administration interface to import the CA certificates, you must not include the PEM header/footer. I.e. only paste the Base64 code in the input field in this menu.

Verify the contents of the new host certificate
- You can view the certificate in MS Windows. Simply double-click the certificate file (if it has extension .crt or .cer).

- The BoKS certinfo utility can also be used to view the certificate, although it may not be able to display all certificate extensions properly. The certinfo utility understands both raw Base64 encoded certificates and fully PEM-formatted files (but not binary encoded certificates).

- The openssl x509 command can be used, but requires that the Base64 encoded certificate file is PEM-formatted.

A PEM-formatted certificate is a Base64-encoded text file where the lines have been folded to 64 characters' length and with a header and footer in the form:

-----BEGIN/END CERTIFICATE-----


# openssl x509 -text -in

Note: If the Extended Key Usage certificate extension is present it must have both clientAuth and serverAuth set. If it has serverAuth set only it will serve as a host certificate in BoKS but will not be accepted as a Web server certificate in the FCC Presentation Server since it is used by BCCPS (the presentation server) as a client certificate against BCCAS (the administration server in BoKS).

Check also that:

- the host certificate has the Authority Key Identifier extension

- the Root CA certificate has the Subject Key Identifier extension and

- any sub-ordinate CA certificate has both AKI and SKI.

If this is not the case the bccgethostcert utility will not be able to extract the CA certificates from the BoKS database. However this can be worked around (see bccgethostcert below).

vcrenewbyextca.sh - Import the signed Host Certificate

Usage: vcrenewbyextca.sh -h host {-e [-l keylength]| -i -c certfile}[-v]

# vcrenewbyextca.sh -h $(hostname) -i -c -v

Note: It is important that the correct host certificate is entered here. The vcrenewbyextca.sh script does currently not check that the public key in the certificate corresponds to the cached private key. If another certificate is entered, a corrupt Virtual Card will be created and stored in BoKS database for this host and thus the services that depend on that Virtual Card will not function correctly.

Note: BoKS daemons must be restarted at this point. The old BoKS Administration interface should still be working. However FCC will not work since it will not yet recognize the new host certificate as the CA issuer is as yet unknown (has not been imported to the Java Key-store file).

bccgethostcert - Export the Host Certificate, Private Key and CA Chain for FCC

Usage: bccgethostcert [-c ] [-p ]

Note: When running the bccgethostcert command you will be prompted to enter a password for the PKCS#12 file. It is important to enter the same password as used for the Java Keystore file. The keystore password is avaliable in $BCCPS_etc/bcc.properties.

If you would like to set a new password for the keystore you can do so at this point (requires changing the password in bcc.properties).

# bccgethostcert -c ca-chain.out -p $(hostname).p12 $(hostname)

Note: bccgethostcert will fail to create the ca-chain.out file if the certificates in the chain do not have the Subject- and Authority Key Identifier extensions (SKI/AKI).

However if the CA certificates provided from the corporate CA are in PEM format you can manually create the ca-chain.out file by concatenating the certificates in the CA chain into a single file:

# cat ca1cer ca2.cer ... > ca-chain.out

Note that the host certificate should not be included in this file, only the CA certificates.

createtrust.sh - Create the Java Keystore file in FCC

This utility comes with FCC and is located in the $BCCPS_sbin directory, /opt/bccps/sbin by default.

Usage: createtrust.sh -c -h -j [-p ] [-P ]

Note: You should rename the current keystore file before running this command. The trustfile is located in $BCCPS_etc, /etc/opt/bccps by default.

# mv /etc/opt/bccps/trustfile.jks /etc/opt/bccps/trustfile.jks.$(date +%y%m%d-%H%M%S)

Run createtrust.sh. It will create a new Java Keystore. Input are the output files from the bccgethostcert command as well as the password of the PKCS#12 and the Java Keystore files.

# /opt/bccps/sbin/createtrust.sh -c ca-chain.out -h $(hostname).p12 -j /etc/opt/bccps/trustfile.jks [-p "keystore-password"] [-P "keystore-password"]

You will be prompted for the keystore password and the PKCS#12 password if you don't provide them via the -p and -P options. Again, the PKCS#12 password must be the same as the keystore password.

Check that the owner and permissions of the keystore are correctly set to the functional user account used for the FCC Presentation Server (java process). E.g.

# chown fcc /etc/opt/bccps/trustfile.jks

Run pingbccasd.sh to verify that the communication from BCCPS to BCCAS is now functioning correctly with the certificates from the new keystore.

# /opt/bccps/sbin/pingbccas.sh

Now, FCC must be restarted.

# /etc/init.d/bccps stop
# /etc/init.d/bccps start

Attachments

Attachment Details

mkhostvc.sh
Version 1.9, Mar 10, 2015
MD5 (mkhostvc.sh) = 3472525c5cfdafde8ab870f97f836ffe
vcrenewbyextca.sh
Version 1.6, Mar 10, 2015
MD5 (vcrenewbyextca.sh) = 947644db9381a12a0891cebcac6e2aa9

Still have questions? We can help. Submit a case to Technical Support.

Last Modified On: May 25, 2018