ALERT: Some images may not load properly within the Knowledge Base Article. If you see a broken image, please right-click and select 'Open image in a new tab'. We apologize for this inconvenience.

Secure Communications With Signed Certificates

book

Article ID: 10870

calendar_today

Updated On:

Products

CA Release Automation - Release Operations Center (Nolio) CA Release Automation - DataManagement Server (Nolio)

Issue/Introduction

First, an argument could be made that all certificates are signed. They are either signed by itself (self-signed) or signed by a CA. In this article when we refer to signed certificates it is assumed that the certificates are NOT self-signed but instead were signed by a CA (Certificate Authority). Some CA's include: Verisign, GoDaddy, or maybe even an internal CA used by your company. You can tell whether a certificate is self-signed by looking at the details of the certificate. If the details reveal that the owner and issuer are the same then it is self-signed. 

 

NOTE: It is worth mentioning that intermediate and root certificates are frequently referred to when talking about certificates being signed by a Certificate Authority. These are certificates that the CA have created on their end. They are used to sign your certificates. Many of the popular/reputable Certificate Authorities already have their intermediate and/or root certificates imported into the truststores used by operating systems, internet browsers and java. Sometimes you may see and need to do things with these certificates. For example: include them in your Java KeyStore. Don't be alarmed if you see an owner and issuer as the same. Root certificates are self-signed certificates (like described above). But those self-signed certificates are trusted because the CA is reputable. It's different than the self-signed certificates NOT created by by the CA which are untrustworthy. 

 

The Secure Communications page in the product documentation describes how to secure the various CA Release Automation components using self-signed SSL certificates. This technical article is meant to cover the commands used to secure the following components using signed certificates:

  • Datamanagement component (ROC/Rest API)
  • Automation Studio java application (ASAP)
  • JMX

 

The challenges doing this often relate to:

  • Uncertainty of the small yet important details of SSL.
  • The various file formats you may receive from your Certificate Authority.

We will approach this by:

  • Describing how certificates are received and the common file types used to store the certificates (in the Background section).
  • Outlining the various files that need to be updated to separately secure the components above (in the Instructions section)
  • Use the Additional Information section to:
    • Provide reference links that help clarify steps, terminology, commands, etc..
    • Highlight characteristics of public and private keys inside of Java KeyStores to assist assist in understanding what you have. 
    • Provide commands that can be used to view certificate details.
    • Highlight important details related to securing the datamanagement component. 
    • Highlight important details related to securing Automation Studio (ASAP).
    • Creating Private Keys With Keytool.
    • Creating Private Keys Without Keytool
    • Import PKCS7/P7B into Java KeyStore
    • Import X509 into Java KeyStore
    • Import PKCS12/P12 into Java KeyStore
    • CodeSigning Certificates
    • ServerAuth / TLS Web Server Authentication Certificates
    • Reply Chains

 

Note: The Instructions section separately secures datamanagement and automation studio. It is expected that each will be secured. Running with only a secured ROC or only a secured ASAP, etc.. has not been tested and is therefore not supported. 

This is not a replacement for the instructions given in the Product Documentation. It is supplemental. The information in this article is meant to:

  • Demystify some of the important pieces related to securing these CA Release Automation components.
  • Facilitate troubleshooting problems you may encounter while securing Datamanagement or ASAP by focusing on only the relevant components.
  • Provide a better understanding of certificates, keys, extensions, and the various file and encryption formats used.
  • Provide some commands that can be used to view the details of the different files you might have.
  • Provide some commands that can be used to help prepare the file(s) needed to secure these CA Release Automation components.


Most signed certificates are received in one of two ways:

  1. You don't create the key pair or CSR. You submit the necessary details to your CA and they provide you the private key  and  signed certificate.
  2. You generate the key pair and certificate signing request (CSR), send the CSR to your Certificate Authority (CA), and your CA sends you the signed certificate.
    • Note: Java's "keytool -genkeypair" command creates a private and public key (hence, key pair). Openssl can separately create private keys and public keys. The single "keytool -genkeypair" command effectively creates a self signed certificate. It is considered self-signed until you complete all of the following:
      • Generate the CSR
      • Send the CSR to your CA
      • Receive and import the signed certificate into the keystore created by the "keytool -genkeypair" command using the same alias as the PrivateKeyEntry. This replaces the public key. 

 

Common File Types

The various file extensions are suggestive. Renaming a file does not change what it is. For example, I could take a file named serverA.cer and rename it to serverA.jks. That doesn't make it a valid Java KeyStore file. Similarly, using Microsoft Windows certmgr to export a public certificate in DER encoded binary x509 format and then changing its extension .pem mean make it a Base-64 encoded X.509 formatted file. Trying to look at a DER encoded binary x509 file is like trying to look at any other binary (exe, dll, etc..) - you see a majority of strange characters. Whereas opening/viewing a Base-64 encoded file shows characters recognizable from an alphanumeric keyboard. However, opening a Base-64 encoded file will not list all of the details of the certificate because it is still encoded. You will need to use the various commands/tools made available to view details of the certificates.

  • PKCS#12 (.p12/.pfx): This file is often used to store private keys with their accompanying public key (signed certificates) as well as any certificates from the reply chain. This file is not clear text. It is binary so opening it in notepad should not present readable text. It is likely password protected.
  • PKCS#10 (.csr): This is a certificate signing request generated from a private key. The CSR is sent to a CA who is expected to sign a certificate based on the information in the CSR. Then they send the signed certificate back to you.
  • PKCS#7 (.p7b): This is often used to store certificates. It does not store private keys. This file is not clear text. It is binary so opening it in notepad should not present readable text. 
  • X509 (.der, .cer, .crt, .pem): x509 is a standard that defines the format public key certificates.  
  • Java KeyStore (.jks): This is a repository of security certificates. 

 

Environment

Release Automation Manager versions 6.x and above.Management server (aka NAC, aka datamanagement server) on Windows or Linux.

Resolution

Datamanagement (Release Operations Center (ROC) / Rest API):

CA Release Automation's datamanagement component is what makes the ROC and REST API available. The datamanagement component is a tomcat application and can be configured to use custom SSL certificates. The following topics, in the Additional Information section below, assist preparing the Java KeyStore to be used by the datamanagement component:

  • Public Certificates
  • Private Keys
  • Viewing Certificates
  • Securing Datamanagement
  • One of:
    • Creating Private Key With Keytool
    • Creating Private Key Without Keytool
  • One of:
    • Import PKCS7/P7B into Java KeyStore
    • Import X509 into Java KeyStore
    • Import PKCS12/P12 into Java KeyStore

 

The datamanagement component is secured by:

  • Preparing a Java KeyStore (we'll call it custom-keystore.jks) file with the private key and its signed certificate and copy it to the RAInstallDir/conf directory. 
  • Update the appropriate fields (keyAlias, keystoreFile, keystorePass) in the conf/server.xml file on the datamanagement server. 
  • If you don't want the server.xml file to use a clear text value for keystorePass then you can:
    • Update the server.xml keystorePass to use the following value (quotation marks too): "${keystorePass}"
    • Run the command: scripts/encrypt_password <jks password>
    • Update the conf/catalina.properties file with these entries and replace the <encrypted password> in the second line with the encrypted value provided by the output of the scripts/encrypted_password command:
      • org.apache.tomcat.util.digester.PROPERTY_SOURCE=com.nolio.tomcat.utils.PropertyDecoder
      • keystorePass=<encrypted password>
  • Restart NolioServer service.

 

Automation Studio (ASAP):

The Automation Studio (ASAP) java application can be secured using custom SSL certificates. The following topics, in the Additional Information section below, assists with preparing the files necessary to do this:

  • Public Certificates
  • Private Keys
  • Viewing Certificates
  • Securing Automation Studio (ASAP)
  • CodeSigning

 

Automation Studio is secured by:

  • Preparing:
    • Create nolio.jks Java KeyStore
    • Create the custom-truststore.jar file
    • Preparing a codeSigning Java KeyStore.
    • Sign custom-truststore.jar
  • Move the custom-truststore.jar file to RA_HOME\webapps\nolio-app\apps\v2.0.0\lib
  • Restart NolioServer service.

 

JMX: 

By default the JMX console does not use HTTPS|SSL. The webapps/datamanagement/WEB-INF/distributed.properties has entries that allow you to make changes to it. These are the settings that are related to configuring HTTPS|SSL for the JMX console:

 

  • jmx.web.console.ssl.enabled=false

Set this to true to use JMX over HTTPS|SSL.

 

  • jmx.web.console.ssl.keystore.path=conf//nolio.jks

This is the default Java KeyStore used for JMX. The reference to "conf" is pointing to the <MgmtServerInstallDirectory>/conf folder. If you're implementing your own certificates for the ROC and ASAP, and you want to configure JMX to use HTTPS|SSL, then you should point this to use the same Java KeyStore being used by the Datamanagement component as specified in the conf/server.xml. 

 

  • jmx.web.console.ssl.keystore.password=A30B6F1F8F7A0E456311C3142AE07D7A

This is the encrypted version of the Java KeyStore's password. To encrypt the password use the scripts/encrypt_password.sh|bat.

 

Changes to any/all of these settings require a restart of the nolio server service for the changes to be recognized. 

 

 

 

Additional Information

Helpful URLs:

CA Release Automation Product Documentation: Secure Communications

Java 8 Keytool Documentation

X.509 v3 Standard (aka X.509, aka PKIX)

RFC 5280: The RFC for X.509

Public-key cryptography

Certificate vs Key

 

Public Certificates:

Understanding characteristics of a public certificate can be helpful while preparing the files used to secure CA Release Automation. 

  • Java KeyStore:
    • A certificate inside of a keystore will have an "Entry type" value of trustedCertEntry when:
      • its corresponding private key is not in that same keystore; or
      • the public certificate is imported using an alias that is different than the alias used by its private key.
    • Importing a public certificate into the same keystore as its private key using the same alias as its corresponding private key will have an "Entry type" value of PrivateKeyEntry. 
    • See the section "Viewing Certificates" for the command used to view certificates in a Java KeyStore. 

  

Private Keys: 

Understanding the characteristics of a private key is important because it could present a major security risk. Here are some of the ways you can identify whether the file you have includes your private key. This 

  • Java KeyStore:
    • A certificate in a keystore with an "Entry type" value of "PrivateKeyEntry" means that it is a private key.
    • If the key is not intended to be a self-signed then the Owner and Issuer of this key should not be the same. If it is then it suggests that its signed public certificate has not been imported yet. 
    • See the section "Viewing Certificates" for the command used to view certificates in a Java KeyStore. 

 

Viewing Certificates:

These commands can be used to better understand the certificates stored in the various certificate files you might have. 

  • Java Keystore: 
    • keytool -v -list -keystore <your keystore filename>
  • Certificates Exported From A Java KeyStore (using keytool -exportcert):
    • openssl x509 -inform der -in <filename> -text -noout
  • Check the details of a Certificate Signing Request (CSR):
    • openssl req -text -noout -verify -in <your csr filename>
  • Check the details of a Base-64 encoded Public Certificate file:
    • openssl x509 -in <your public certificate filename> -text -noout
  • Check the details of a DER encoded Public Certificate file: 
    • openssl x509 -inform der -in <your public certificate filename> -text -noout
  • Check the details of a PKCS#12 file (.pfx or .p12)
    • openssl pkcs12 -info -in <your pkcs12 filename>
  • Check the details of a PKCS#7 file (.p7b):
    • openssl pkcs7 -in <your .p7b file> -inform der -print_certs -text
  • Certificates on Microsoft Windows:
    • Most of the various certificate formats (cer, .crt, .der, .p7b) can be viewed by double clicking the certificate while in Windows. If not then you can run the command "certmgr" and import it to view its content. 

 

Securing Datamanagement:

To secure the datamanagement component with a signed certificate it's Java KeyStore needs:

  • Private key
  • Public key - signed with serverAuth EKU (see "ServerAuth / TLS Web Server Authentication Certificates" below).
  • The reply chain (see "Reply Chains" below). 

For the purpose of securing the datamanagement component the private key is generated in one of two ways:

  1. Creating the private key with keytool. See "Creating Private Key With Keytool" section below.
  2. Creating the private key with something other than keytool. See "Creating Private Key Without Keytool" section below. 

This is important because the subsequent commands used to get everything into the keystore will vary depending on whether the private key is generated with keytool or not. 

 

Securing Automation Studio (ASAP):

To secure ASAP you need to:

  • Create nolio.jks
    • WARNING: It is important that this nolio.jks NOT replace/overwrite the conf/nolio.jks file.
    • WARNING: The filename must be nolio.jks
    • WARNING: You might be tempted to copy the custom-keystore.jks created for and used by the ROC/REST API. This would be a mistake because it includes the private key. This nolio.jks should not have any certificates with an "Entry type" value: PrivateKeyEntry
  • Create custom-truststore.jar
    • WARNING: The filename must be custom-truststore.jar
  • Prepare codeSigning Java KeyStore
  • Sign custom-truststore.jar

 

Create nolio.jks

This nolio.jks Java KeyStore file should have one certificate - the signed certificate you receive from your CA. It should not have the private key. If it does then it presents a security risk since people will have access to this nolio.jks via the custom-truststore.jar file downloaded to workstations running ASAP. The two most common ways to create nolio.jks are:

  1. After the custom-keystore.jks (used by the datamanagement component) is read, run these commands:
    • keytool -exportcert -alias stegr04-e7328 -keystore z-p12.jks -file nolio.crt
    • keytool -importcert -alias stegr04-e7328 -file nolio.crt -keystore nolio.jks
  2. When your CA sends you the file(s) with your signed certificate - use them to create the nolio.jks. Some notes:
    • If you're dealing with .p12 files then you'll need pull out the signed certificate out from it and then get it into a nolio.jks. It is probably easier to use method #1 (getting it from custom-keystore.jks).
    • If you're dealing with .p7b files then see the "Import PKCS7/P7B into Java KeyStore" section below.
    • If you're dealing with X509 files then see the "Import X509 into Java KeyStore" section below.

 

Create custom-truststore.jar

Once your nolio.jks Java KeyStore has been set up, run the command below to archive it into a file named: custom-truststore.jar

Command: jar cvf custom-truststore.jar nolio.jks

 

Prepare codeSigning Java KeyStore

The custom-truststore.jar file gets transferred to the workstations running Automation Studio. ASAP checks for the custom-truststore.jar and uses it (if found) to get the nolio.jks. The nolio.jks file is then used to establish a secure connection and  encrypt data sent between the java application and the management server. The custom-truststore.jar file needs to be signed by trusted certificate. Otherwise, the java settings prevent the application from running or at least prevent block access to that file (not sure which).

The KeyStore used by jarsigner (to sign the jar) needs:

  • Private key
  • Public key - signed with codeSigning EKU (see "CodeSigning Certificates" below).
  • The reply chain (see "Reply Chains" below). 

For the purpose of securing Automation Studio the private key is generated in one of two ways:

  1. Creating the private key with keytool. See "Creating Private Key With Keytool" section below.
  2. Creating the private key with something other than keytool. See "Creating Private Key Without Keytool" section below.

This is important because the subsequent commands used to get everything into the keystore will vary depending on whether the private key is generated with keytool or not. 

 

Sign custom-truststore.jar

Once your codeSigning KeyStore is ready, run the following command to sign the jar:

jarsigner -keystore <the keystore file with your codeSigning certificate> -verbose custom-truststore <alias of your codeSigning certificate>

 

 

Creating Private Key With Keytool:

If keytool is used to create the private key and you want/need a signed certificate then you'll need to run commands similar to the following:

  • Generate Key Command: 
    keytool -genkeypair -keystore yourkeystorefilename.jks -dname "CN=usuallyNameOfServer, OU=yourOrgUnit, O=yourOrg, L=yourServersCity, ST=yourServersState, C=yourServersCountry" -storepass ******* -keyalg RSA -keysize 2048 -keypass ****** -alias aUniqueIdentifier
    • NOTE: At this point, without doing anything more, this is considered a self-signed certificate. It has a private key and a public certificate. 
    • NOTE: You can take out the -dname argument and its values to be prompted for the values. 
  • Generate CSR Command:
    keytool -certreq -storepass ******* -alias theUniqueIdentifier -keypass ***** -file yourCsrFilename.csr -keystore yourkeystorefilename.jks

Once the CSR file is created you need to send it to your Certificate Authority (CA). 

Notes:

  1. The certificate being used to secure the datamanagement component needs the "serverAuth" EKU.
  2. The certificate being used to secure ASAP needs the "codeSigning" EKU. 

 

When your CA has signed the CSR you provided, you will receive one or more files. The next set of commands will depend on the file(s) that your CA sends you. It is unlikely that your CA will send you a pkcs12/.p12 file. One of the following sections below should be able to assist with importing the signed certificate into the Java KeyStore you just created here:

  • Import PKCS7/P7B into Java KeyStore
  • Import X509 into Java KeyStore

If your CA does send you a PKCS12/.P12 file then the Java KeyStore above can probably be discarded. Check the section "Import PKCS12/P12 into Java KeyStore" below and

 

Regardless of what kind of files you receive from your CA it is a good idea to make sure you have the expected keys and/or certificates in the KeyStore. Remember that the KeyStores used by Datamanagement and ASAP are different. See their respective sections for information on what's expected in each KeyStore. To help view and understand what is inside of the KeyStore you can use these sections:

  • Public Certificates
  • Private Keys
  • Viewing Certificates
  • ServerAuth / TLS Web Server Authentication Certificates
  • CodeSigning Certificates

 

Creating Private Key Without Keytool:

You could create the private key and generate the CSR with openssl and then send the CSR to your CA (Certificate Authority) to be signed. I don't think this will happen as often as submitting all of the necessary information to your CA who will then give you the private key and signed certificate. This section assumes you are submitting all of the necessary information to your CA who will then send you the private key and signed certificate.

When your CA has signed the CSR you provided, you will receive one or more files. The next set of commands will depend on the file(s) that your CA sends you. One of these sections below should be able to assist with importing the private key and signed certificate into a Java KeyStore:

  • Import X509 into Java KeyStore
  • Import PKCS12/P12 into Java KeyStore

 

Regardless of what kind of files you receive from your CA it is a good idea to make sure you have the expected keys and/or certificates in the KeyStore. Remember that the KeyStores used by Datamanagement and ASAP are different. See their respective sections for information on what's expected in each KeyStore. To help view and understand what is inside of the KeyStore you can use these sections:

  • Public Certificates
  • Private Keys
  • Viewing Certificates
  • ServerAuth / TLS Web Server Authentication Certificates
  • CodeSigning Certificates

 

Import PKCS7/P7B into Java KeyStore:

It is common for PKCS7 files to contain the signed certificate and its reply chain (see "Reply Chain" below). It is a good idea to verify that the p7b file that you have received is in a format that keytool will understand. Try opening your p7b file in notepad. If it looks like you tried opening a binary file then keytool will not be able to import this file. Instead, use the following command to convert it into a format that keytool will accept:

openssl pkcs7 -in <your p7b filename> -inform der -text > myNew.p7b

 

If you open your P7B file in notepad and are able to see that it starts with: 

-----BEGIN PKCS7-----

 

and ends with: 

-----END PKCS7-----

 

then keytool will be able to use this file and you can run the following command to import the certificate:

keytool -importcert -file <your p7b filename> -keystore <your keystore filename> -alias <the alias of your private key in the JKS> 

 

Respond "yes" if the command returns with the message: ... is not trusted. Install reply anyway? 

Note: The "... is not trusted, Install reply anyway" message may or may not be resolved with adding "-trustcacerts" to the command. If it is not solved by this then you might be importing a certificate that was signed by a Certificate Authority that is not already included in the default java truststore (lib/security/cacerts). If this is the case then you may need (at a minimum) the intermediate certificate imported into your internet browsers truststore before it considers it a secure/trusted site. 

 

If you are importing the certificate into a KeyStore with a private key (as should be done for the datamanagement component, but not ASAP) then the alias is important. If it is not the alias of your private key then it will not properly link the signed certificate to the private key and it will not work. See keytool's importcert details regarding alias here: 
https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html#keytool_option_importcert

When you properly import and link the signed certificate into a keystore with its private key the keytool command should return the following response: Certificate reply was installed in keystore

 

Import X509 into Java KeyStore:

See "Reply Chains" section below regarding the need to import the appropriate intermediate and root certificates. If the intermediate(s) and root certificates are x509 then the same command can be used to import them to - just with a different alias. The command to import these certificates (regardless of whether its DER encoded binary Base-64 encoded ASCII) is:

keytool -importcert -file <your x509 certificate file> -keystore <your jks file> -alias <an alias>

If you are importing the certificate into a KeyStore with a private key (as should be done for the datamanagement component, but not ASAP) then the alias is important. If it is not the alias of your private key then it will not properly link the signed certificate to the private key and it will not work. See keytool's importcert details regarding alias here: 
https://docs.oracle.com/javase/8/docs/technotes/tools/unix/keytool.html#keytool_option_importcert

When you properly import and link the signed certificate into a keystore with its private key the keytool command should return the following response: Certificate reply was installed in keystore

 

Import PKCS12/P12 into Java KeyStore:

If you have a PKCS12/P12 file from your CA then it is possible that it has everything you need (private key, signed certificate, and reply chain). You can use this command to import everything from the .p12 file into a new Java KeyStore file using this command:

keytool -importkeystore -srckeystore <your p12 filename> -srcstoretype PKCS12 -destkeystore <new jks filename> -deststoretype JKS

 

ServerAuth / TLS Web Server Authentication Certificates:

 

As documented in RFC5280 the serverAuth EKU (Extended Key Usage) is for: TLS WWW server authentication

A certificate that has been signed with this EKU can be verified by viewing the details of the certificate (see "Viewing Certificates" section above). 

To verify if a KeyStore's certificate has the serverAuth EKU look for this:

ObjectId: 2.5.29.37 Criticality=false
ExtendedKeyUsages [
  serverAuth
]

To verify if a signed certificate's x509, pkcs7/p7b or pkcs12/p12  file has the serverAuth EKU look for this:

X509v3 Extended Key Usage: 
    TLS Web Server Authentication

 

Note: Securing the datamanagement component needs a certificate signed with this EKU.

 

CodeSigning Certificates:

As documented in RFC5280 the codeSigning EKU (Extended Key Usage) is for: Signing of downloadable executable code

A certificate that has been signed with this EKU can be verified by viewing the details of the certificate (see "Viewing Certificates" section above). 

To verify if a KeyStore's certificate has the codeSigning EKU look for this:

ObjectId: 2.5.29.37 Criticality=false
ExtendedKeyUsages [
  codeSigning
]

To verify if a signed certificate's x509, pkcs7/p7b or pkcs12/p12  file has the serverAuth EKU look for this:

X509v3 Extended Key Usage: 
    Code Signing

 

Note: Securing the ASAP needs a certificate signed with this EKU.

 

 

Reply Chains:

Reply chains refer to the intermediate(s) and root certificates involved in signing your certificate. For example:

You send a CSR to your CA who signs the certificate. We'll call it certC. CertC was signed by a intermediate certificate (we'll call it intCertA). IntCertB was signed by a root certificate (we'll call it RootCertA). RootCertA was signed by itself.  

If you're certificate was signed by a trusted CA (ex: Verisign) then you can probably add the -trustcacerts to the keytool -importcerts command you use to import CertC into your Java KeyStore. The -trustcacerts instructs keytool to look at its /path/to/jre's/lib/security/cacerts truststore to look for the reply chain's certificates. If it finds it then it will import them into the Java KeyStore along with CertC. If it doesn't find them and:

  • Your reply chain's certificates are not already in your Java KeyStore; AND
  • Your referencing the correct -alias of the PrivateKeyEntry while running "keytool -importcert" to import CertC

then keytool will return the error: keytool error: java.lang.Exception: Failed to establish chain from reply

But this also depends on the file you're using to import CertC. For example, it is not uncommon for pkcs12/p12 and pkcs7/p7b files to have the reply chain included. 

 

 

 

Powered by Wolken Software