OmicSoft Server TLS Certificate Generation

From Array Suite Wiki

Introduction

These steps will walk through how to generate, install, and configure OmicSoft Server-compatible TLS 1.2 certificates for OmicSoft Server v12. Please follow these steps closely.

1. You will generate a Certificate Signing Request from a commercial Certificate Authority.
2. You will convert the certificate to PFX format (.PFX)
3. You will obtain the intermediate certificates (.CER)
4. You will update your server's certificate stores
5. You will configure the OmicSoft Server configuration (ArrayServer.cfg) with the certificate signature

0. Prerequisites

note:From Template:CertificatePrerequisites

  • DNS name
    • DNS must point to the OmicSoft Server machine (ex.: omicsoftserver.example.com)
    • DNS must be reachable from all machines where OmicSoft Studio/Land Explorer/Oshell and (if applicable) Analytic servers will be installed
    • DNS name must point to a static/fixed IP
    • DNS must have a valid TLS >= 1.2 signed server certificate (including the associated private key)

Make sure that the server is reachable using the DNS name, both from outside the server network, but also from the server machine itself: 

ping omicsoftserver.example.com
Pinging omicsoftserver.example.com [X.XXX.XX.XX] with 32 bytes of data:
Reply from X.XXX.XX.XX: bytes=32 time=230ms TTL=37
...
Ping statistics for 3.128.81.13:
   Packets: Sent = 4, Received = 4, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
   Minimum = 230ms, Maximum = 231ms, Average = 230ms
  • TLS certificate
    • The certificate must be signed by a public certificate authority (no self-signed certificates can be used).
    • The certificate should be in .pfx (PKCS #12) format, containing the entire certificate chain and the private key.
    • You also need the intermediate CA certificates in separate files, so you can import them in the Mono store.

Note: On Windows, if using the MMC / Manage Computer Certificates add-in to generate a custom certificate request (CRS), the ‘classic’ cryptographic service provider like ‘Microsoft Enhanced Cryptographic Provider v1.0’ (CryptoAPI provider) must be used instead of a newer Cryptography Next Generation (CNG / CAPI2) provider, like ‘Microsoft Software Key Storage Provider’. In MMC / Manage Computer Certificate add-in, when generating the custom certificate request (CRS), the Template should be: '(No template) Legacy key' (instead of '(No template) CNG Key')

Information on how to obtain all the required files can be found Certificates Setup page.

1. Request your server certificate

On Linux

These steps demonstrate an example of creating a Certificate Signing Request (CSR) for your.servername.com.

The actual process to obtain a signed certificate can be different, depending on your company policies. Please consult with your System Administrator about any steps that may deviate from these recommendations.

a. Create a private key 

$ openssl genrsa -out cert.key 4096

b. Create a CSR (you’ll have to answer a few questions) 

$ openssl req -new -out cert.csr -key cert.key

c. Verify that the CSR is correct 

$ openssl req -text -noout -in cert.csr | less

d. Send the file cert.csr to your preferred commercial Certificate Authority in order to receive the server certificate. According to the rules in your organization, you may have different steps to request a server certificate.

On Windows

On Windows, if using the MMC / Manage Computer Certificates add-in to generate a custom certificate request (CRS), the ‘classic’ cryptographic service provider like ‘Microsoft Enhanced Cryptographic Provider v1.0’ (CryptoAPI provider) must be used instead of a newer Cryptography Next Generation (CNG / CAPI2) provider, like ‘Microsoft Software Key Storage Provider’. In MMC / Manage Computer Certificate add-in, when generating the custom certificate request (CRS), the Template should be: '(No template) Legacy key' (instead of '(No template) CNG Key'):

CSR Template

At 'Certificate information' step, expand Details / Properties, in the 'Private key' tab, select Microsoft Enhanced Cryptographic Provider v1.0 as CSP:

CSP

To verify the certificate request, you can run the following command: 

> certutil -dump server_example.csr
PKCS10 Certificate Request:
Version: 1
Subject:
{ CN=...}
... ...
...
{ Attribute[2]: 1.3.6.1.4.1.311.13.2.2 (Enrollment CSP)}
{ Value[2][0], Length = 66}
{ CSP Provider Info}
{ KeySpec = 2}
{ Provider = Microsoft Enhanced Cryptographic Provider v1.0}
...
...

2. Convert your server certificate to the proper format

If you do not have the certificate in PFX format

Most of the times the certificate is delivered by the signing authority in another format (like .PEM or .CRT), and the private key and the intermediate CA certs are in separate files. a. Make sure you have a .PEM or .CRT file in addition to server cert file. b. Convert these other formats to .PFX file with a command like this: 

$ openssl pkcs12 -export -out testserver.pfx -inkey privatekey.pem -in servercert.pem -certfile ca_chain.pem -password pass:....

where:

  • privatekey.pem the private key in PEM format (Base64 encoded DER certificate)
  • servercert.pem - the signed server certificate in PEM format
  • ca_chain.pem - the additional intermediate CA certs chain in PEM format

c. the output should be testserver.pfx

If you have the certificate in PFX format

a. Verify if the .pfx contains the private key: 

$ openssl pkcs12 -info -nocerts -in testserver.pfx
...
Shrouded Keybag: ...
Bag Attributes
localKeyID: ...
Key Attributes: <No Attributes>
b. Enter PEM pass phrase:

Output should look like 
Verifying - Enter PEM pass phrase:
-----BEGIN ENCRYPTED PRIVATE KEY-----
....

where testserver.pfx should be replaced with the actual PFX file name.

3. Obtain the intermediate CA certificates

Overview

On Linux, by default the Mono certificate stores are empty, so we have to import the required CA and server certificates, including the intermediate CA certificates.

Possible scenarios after receiving the server certificate

You have the certificate in CRT/PEM/CER format

You have received the intermediate CA certificates from the signing authority

In this scenario you already have the intermediate CA certificates in separate files, so you can import them in the Mono store. Usually the certificate authority who signed the server certificate should be able to provide the intermediate certificates on request.

You haven't received the intermediate CA certificates from the signing authority

In this scenario use these steps:

  • Get detailed information about the certificate, on Linux, using OpenSSL (example):
$ openssl x509 -noout -text -in testserver.crt
  • In the output, search for information on the issuer CA, like (example):
Authority Information Access:
CA Issuers - URI:http://crt.sectigo.com/SectigoRSAOrganizationValidationSecureServerCA.crt
  • download the CA chain from there
  • Otherwise, look for the issuer information:
Issuer: C=GB, ST=Greater Manchester, L=Salford, O=Sectigo Limited, CN=Sectigo RSA Organization Validation Secure Server CA

You have the certificate in PFX format

In this scenario you can export the Intermediate CA certs from the PFX file using these steps:

  • On a Windows device, import the PFX file (double-click and select the default store - that will usually be the 'Current User'/'Personal' store); the private key password will be needed
  • Open 'Manage User Certificates' from Start menu, search for the newly imported certificate in Certificates - Current User / Personal store. Double click the certificate, select an intermediate CA and export it from the Details tab / Copy to file. Select 'Base-64 encoded X.509 (.CER)' format.
  • Copy the .cer files on the Linux server.

3. Install intermediate (.CER) and server (.PFX) certificates

Note: From template:CertificateSetup

If you don't have all the required files, please review the Certificates Setup page.

Install the intermediate CA certificate(s)

Intermediate CA can be in the following formats: .PEM, .CRT, .CER.

Import the intermediate CA certificates:

  • the current user intermediate CA store
$ certmgr -add -c -v CA IntermediateCA1.cer
  • the machine intermediate CA store
$ sudo /opt/mono-6.12.0/bin/certmgr -add -c -v -m CA IntermediateCA1.cer

Verify certificates installation with: 

$ certmgr -list -c CA
$ sudo /opt/mono-6.12.0/bin/certmgr -list -c -m CA
Install the server certificate(s)

Import the server certificate in the machine-level ( -m param. ), personal ('My') store, from the PFX file (that must have also the private key included). The private key password might be needed for this step: 

$ sudo /opt/mono-6.12.0/bin/certmgr -add -c -v -p privatekeypassword -m My cert.pfx

Verify if the certificate was properly imported with: 

$ sudo /opt/mono-6.12.0/bin/certmgr -list -c -m My

Update Omicsoft server configuration file

Get the server certificate thumbprint that must be set in ArrayServer.cfg using the PFX file: 

$ openssl pkcs12 -in cert.pfx -nodes -passin pass:privatekeypassword | openssl x509 -noout -fingerprint | cut -f2 -d'='

Set/Update the thumbprint in ArrayServer.cfg 

Port2=8065
CertificateThumbprint=B1:9A:...:6D:71
MasterServerUrl=omicsoft.example.com:8065

Start OmicSoft Server 

$ cd /opt/arrayserver/
$ mono ./OmicSoftServer.exe >> ./run.log &
$ & disown -h

4. Update Certificate Stores

Note: from template:UpdateCertificateStores Update certificate stores: 

$ sudo {{{updatecmd}}}

Import certificates from the Linux store into the Mono root CA stores: 

$ cert-sync --user {{{certpath}}}
$ sudo cert-sync {{{certpath}}}

Configure intermediate CA certificates for https://resources.omicsoft.com: 

$ certmgr --ssl https://resources.omicsoft.com
$ sudo certmgr --ssl -m https://resources.omicsoft.com

Verify if the machine and user root CA stores have been populated: 

$ certmgr -list -c -m Trust
$ sudo certmgr -list -c -m Trust

5. Configure OmicSoft Server with the server certificate

Update Omicsoft server configuration file

Get the server certificate thumbprint that must be set in ArrayServer.cfg using the PFX file: 

$ openssl pkcs12 -in cert.pfx -nodes -passin pass:privatekeypassword | openssl x509 -noout -fingerprint | cut -f2 -d'='

Set/Update the thumbprint in ArrayServer.cfg 

Port2=8065
CertificateThumbprint=B1:9A:...:6D:71
MasterServerUrl=omicsoft.example.com:8065

Start OmicSoft Server 

$ cd /opt/arrayserver/
$ mono ./OmicSoftServer.exe >> ./run.log &
$ & disown -h
Retrieved from "https://wiki.arrayserver.com/wiki/index.php?title=OmicSoft_Server_TLS_Certificate_Generation&oldid=31499"