Smart Suite SSL Certificates

Formats of Certificate Key Files

Two formats can be created for the server.key files. PKCS#1 and PKCS#8. 

The standard method, below, for creating a Certificate Request’s key file that is a PKCS#1 formatted file. There are two ways to tell if the key file is this format. 

1. Run “file server.key”
   It will respond with: “server.key:    PEM RSA private key”
2. Look at the first line of the file:
   It will be: “-----BEGIN RSA PRIVATE KEY-----”

In the old method, at the end of this page, for creating a Certificate Request, the key file will be in the PKCS#1 format. The same two methods can be used to determine the key file’s format:

1. Run “file server.key”
   It will respond with: “server.key:    PEM RSA private key”
2. Look at the first line of the file:It will be:
   “-----BEGIN RSA PRIVATE KEY-----” 

The reason it is important to know the format for the certificate key is for ORDS (Oracle REST Data Service), which is used on Smart Suite 8.1 and above. ORDS cannot use the PKCS#1 formatted files. The solution Oracle provides is to convert the PKCS#1 file to a server.der file (steps documented below) and in the ords standalone.properties file, that file is referenced as follows:

• ssl.cert.key=/opt/amcom/apache/conf/ssl.key/server.der

However, the DER formatted file is actually just a binary representation of a file in PKCS#8 format. 

The new standard method of Certificate Request creation creates the key file in PKCS#8 format to begin with. As amcom_httpd’s configuration does not have issue with either format, it is now the recommended method for creating the certificate.  This does require changing the ssl_cert_key line in standalone.properties  from server.der to server.key.    

Creating the Certificate Request 

1. Connect to the customer’s server and create a temporary folder in /tmp as the root user.
2. Create a file that holds all your certificate settings:
   [bash}$ vim csr_settings.txt 
   [req] 
   distinguished_name = req_distinguished_name 
   req_extensions = v3_req 
   prompt = no 
   [req_distinguished_name] 
   C = US 
   ST = MN 
   L = Eden Prairie 
   O = Spok Inc 
   OU = Smart Suite Support 
   CN = spok-test-71.spok.com
    
   [v3_req] 
   keyUsage = keyEncipherment, dataEncipherment 
   extendedKeyUsage = serverAuth 
   subjectAltName = @alt_names 
   [alt_names] 
   DNS.1 = spok-test-71.spok.com 
   DNS.2 = spokwb1-71.spok.com 
3. Note: To check if there are multiple alternative names, run this command: sudo openssl x509 -in /opt/amcom/apache/conf/ssl.crt/server.crt -text -noout 2>&1 | grep "Subject: \|DNS:\|Public-Key: "
   1. This will also show you the bit key. If it is 4096 (rather than 2048), the "keyUsage" line in the csr_settings.txt file should look like this: keyUsage = nonRepudiation, digitalSignature, keyEncipherment
4. Run the following command to create a new cert and key, which is a self-signed cert based on the settings in the file.
   [bash}$ openssl req -x509 -nodes -days 730 -newkey rsa:2048 -keyout server.key -out server.crt -config csr_settings.txt -extensions 'v3_req' 
5. Run the following to generate a CSR and key based on the settings file:
   [bash}$ openssl req -new -out server.csr -newkey rsa:2048 -nodes -sha256 -keyout server.key -config csr_settings.txt 
   1. If the bit key is 4096, run this command to generate CSR: openssl req -new -out server.csr -newkey rsa:4096 -nodes -sha256 -keyout server.key -config csr_settings.txt 

Proceed to the “Obtain the CA-Signed Certificate” steps below.

Alternate Method (old method)

1. Connect to the customer’s server and create a temporary folder in /tmp as the root user.
2. Navigate to that folder and run one of the following commands to create the server.key file:
   
   For standard security: 
   openssl genrsa -des3 -out server.key 2048
    
   For higher security:
   openssl genrsa -aes128 -out server.key 4096
   
   In most cases the standard security option will work.  There have been instances where a customer will need a stronger RSA keyfile encryption.  An example of an error the customer might receive if additional security is needed would be, "The CSR uses a key that is believed to have been compromised!"  

3. Next run the following command to generate the server.csr file:
   openssl req -new -key server.key -out server.csr
    
   When prompted, enter the password you created above.
4. Answer the questions when prompted using the following template OR match the previously entered values which can be checked by viewing the certificate in a web browser:

• Country Name: US
• State: Enter the state: (i.e. Minnesota)
• Organization Name: Enter the name of the organization (i.e. Park Nicollet Health Services)
• Organizational Unit: Enter the name of the organization (i.e. Park Nicollet Health Services)
• Email Address: Enter a period only which will leave the field blank
• Common Name: This is the name the customer wants the certificate to answer for (not necessarily -- or ideally not at all -- the server’s host name).
• For example, Park Nicollet has a server name of spokwb.parknicollet.com but they want the certificate to answer for smartweb.parknicollet.com.  Therefore, the entry into the Common Name field would be smartweb.parknicollet.com
• Challenge password: Enter a period only which will leave the field blank
• Optional Company Name: Enter a period only which will leave the field blank

5. Now remove the passphrase from the server.key file:
   cp server.key server.key.org
   openssl rsa -in server.key.org -out server.key.nopass
   
   For example:
    openssl rsa -in /opt/amcom/apache/conf/ssl.key/server.key -out /opt/amcom/apache/conf/ssl.key/server.key.nopass
    
   Enter pass phrase for /opt/amcom/apache/conf/ssl.key/server.key:
   writing RSA key
   
   Re-name the new server.key.nopass to server.key

Obtain the CA-Signed Certificate

Configure the server to use the new server.crt and server.key files

1. Make a backup of the /opt/amcom/apache/conf/ssl.crt and /opt/amcom/apache/conf/ssl.key directories.
   1. cd /opt/amcom/apache/conf/ssl.crt
   2. cp server.crt server.crt.old
   3. cd /opt/amcom/apache/conf/ssl.keys
   4. cp server.key server.key.old
   5. cp server.der server.der.old (if applicable)
2. Copy the server.key file from /tmp/<your directory you created in step 1> to /opt/amcom/apache/conf/ssl.key.
   cp /tmp/server.key /opt/amcom/apache/conf/ssl.key
3. Copy the server.crt file the customer sent you into the /opt/amcom/apache/conf/ssl.crt directory.
   For 8.0-1 and below:
   The customer may send the .crt file in .pem form.  The .pem formatted file includes the cert, CA, and chain certificates.  Simply rename the .pem file to server.crt. 
   
   For 8.1 and above:
   The customer may send the .crt file in .pem form. The .pem formatted file includes the cert, CA, chain certificates, and private key.
   ORDS (Oracle REST Data Service) cannot use a full .pem file. Copy the .pem file to server.crt, then edit and remove the private key section from the .crt file.  This includes the '-----BEGIN RSA PRIVATE KEY-----' and '-----END RSA PRIVATE KEY-----' lines. 
                                   
   Additionally, ORDS requires a PKCS#8 formatted private key file, so if you have  the PKCS#1 formated server.key file used by apache, must be converted to .der format:

• cd /opt/amcom/apache/conf/ssl.key
• openssl pkcs8 -topk8 -inform PEM -outform DER -in server.key -out server.der -nocrypt

4. If the server.key file is already in PKCS#8 format, modify the /etc/ords/standalone/standalone.properties file from:
ssl.cert.key=/opt/amcom/apache/conf/ssl.key/server.der

TO

ssl.cert.key=/opt/amcom/apache/conf/ssl.key/server.key

Restart the amcom_httpd and ORDS services

1. For 7.x and 8.x:
   systemctl restart amcom_httpd.service
   
   For 8.1 and above restart the httpd and ords-standalone service:
2. systemctl restart amcom_httpd.service
3. systemctl restart ords-standalone.service
4. Verify the ORDS restarted:
   systemctl status ords-standalone.service
   Or
   journalctl -f -u ords-standalone.service
5. There will be a large amount of content; the key lines are:
   Feb 20 11:58:13 ss810app1 ords-standalone.sh[2791612]: 2024-02-20T17:58:13.017Z INFO    Oracle REST    Data Services initialized
       Feb 20 11:58:13 ss810app1 ords-standalone.sh[2791612]: Oracle REST Data Services version : 21.4.3.r1170405
       Feb 20 11:58:13 ss810app1 ords-standalone.sh[2791612]: Oracle REST Data Services server info:                            jetty/9.4.44.v20210927
       Feb 20 11:58:21 ss810app1 ords-standalone.sh[2791496]: Ords Standalone is ready
6. Verify that the new certificate was applied in apache as well.

Converting SSL Certs