Explorer Service Certificate Requirements and Generation

Explorer Service Server Certificate Minimum Requirements

The Explorer Service Certificate satisfies these requirements to be usable by the Explorer Service for Windows or Explorer for Linux.

The Explorer Service Certificate:

  • is an x509 certificate signed by a Root Certificate Authority that will be installed on the host server machine and on all Explorer Client machines using the service. This provides certificate trust chaining for the installed software.

  • is in (p12) pfx format.

  • is configured for keyUsage = critical,digitalSignature,keyEncipherment,keyAgreement.

  • is configured for extendedKeyUsage = serverAuth.

  • has a Subject (Common Name or /CN) value that matches the FQDN of the Hosting Server

    Common Name = “myserver.acme.com”

    OR

    has a subjectAltName comprising the DNS names that can be used to address the server.

    SubjectAltName = DNS:myserver.acme.com, DNS:localhost

    Note: When using a cert with subjectAltName containing DNS names for the server, the default service configuration assumes the service certificate has the Subject (Common Name or /CN) value ‘ExplorerServiceCert’.

Explorer Service installations on windows and linux scripts to support Explorer Server certificate generation.

  • Windows powershell script : <service_installation_folder>\TIDAL\Explorer\scripts\create-explorer-service-cert.ps1

  • Linux bash script : <service_installation_folder>/TIDAL/explorer/exp-cert.sh

Root Certificate Authority Certificate

There are several options for using the Root Certificate Authority. Use an existing Root Certificate Authority used by your Organization.

In this case, your organization already has a Root signing certificate that it wishes to use to sign the service certificate.

Creating Root and Server Certificates on Windows

Create a Self-Signed Root CA Certificate on windows.

You can create a new self-signed Root CA signing certificate using ‘openssl for windows’.

To open openssl for windows:

  • openssl for windows can be downloaded from slproweb portal.

  • openssl for windows must be installed on the Windows machine and must be on the PATH system environment variable.

Create a new self-signed Root CA signing certificate using these commands.

Create a Root CA key file and save it to the file named ‘rootCA.key’.

openssl genrsa -out rootCA.key 2048Create a Root CA certificate using the rootCA.key file and having CommonName=-MyRootCA. Let the certificate expire in 2000 days and save the output file to the file named ‘rootCA.crt’.
openssl req -new -x509 -days 2000 -key rootCA.key -subj "/CN=MyRootCA" -out rootCA.crt

Note: Self-signed certificates are typically used only in dev/test environments.

Generating Your Explorer Server Certificate on window

You can create an Explorer Server Certificate signed by your root CA certificate using the powershell script located in the explorer installation in scripts\create-explorer-service-cert.ps1.

Getting Help for the create-explorer-service-cert.ps1 powershell script.

To access help information pertaining to the create-explorer-service-cert.ps1, execute these commands in a Windows Command Shell:

cd C:\Program Files\TIDAL\Explorer\scripts
powershell
get-help .\create-explorer-service-cert.ps1
get-help .\create-explorer-service-cert.ps1 -examples
get-help .\create-explorer-service-cert.ps1 -detailed

Powershell Scripts Execution Pre-Requisites

  • openssl for windows must be installed on the Windows machine running the powershell script and must be on the PATH system environment variable.

  • openssl for windows must be installed on the Windows machine running the powershell script and must be on the PATH system environment variable.

  • openssl for windows can be downloaded from slproweb portal.

You will also require these information before running the script to generate the server certificate.

Inputs

Description

rootCA.key

Filename of the key file of your root CA certificate

rootCA.crt

Filename of your x509 root CA certificate (associated with rootCA.key)

passphrase for rootCA.key

If rootCA.key is passphrase protected.

In the example Create a Self-Signed Root CA Certificate, the rootCA.key is generated with no passphrase. If you create a rootCA.key with a passphrase, you must enter the correct passphrase for the rootCA.key at various points during the execution of the scripts described below

dnsNames

One or more DNS names that identify the server to host the explorer service

Note: Wildcard names such as *.acme.com are not supported.

emailAddress

webmaster@acme.com

Org

Your organization name

Loc

Your location

cntryCode

Your zip code or country code [default US]

expiry in days

The number of days until the generated service cert expires

preferred pfx password

A password to use for the generated pfx formatted certificate. Note the password as it will be required when the pfx cert is installed onto the Explorer host server

Example Certificate Generation Using the Powershell Script

These example creates an Explorer service certificate signed with a supplied rootCA using parameters.

Parameter

Description

-CA <rootCAFileName>

RootCA file (.crt)

-CAkey <rootCAKeyFileName>

RootCA key file

-dns “myserver.acme.com, localhost”

FQDN Domain names for the target server to host the service comma separated.

  • To access the FQDN of a windows machine, run the command in a Windows command shell on the machine.

    ping -a localhost

  • To output the FQDN name such as myserver01.dv.local.

  • To access the FQDN of a Linux Machine, run the console command.

    $ hostname -f

-email webmaster@acme.com

Email address

-org “Acme Inc“

Organization name

-loc Chicago

Organization location

-cntryCode US

Country Code

-expiresInDays 2000

The number of days until the service cert expires

-dir “D:\temp\myserver-cert”

The name of folder to be created or recreated to hold outputs. Note that the folder must not already exist

-out myserver-cert

The filename portion of output files (excluding extension)

The commands would be run in a Windows command shell on the service host server to create the required service certificate signed by the rootCA certificate.

cd C:\Program Files\TIDAL\Explorer\Scripts
powershell -ExecutionPolicy Bypass -file create-explorer-service-cert.ps1 -CA rootCA.crt -CAKey rootCA.key -dns "myserver.acme.com,localhost" -email webmaster@acme.com -org "Acme Inc" -loc Chicago -cCode US -expiresInDays 2000 -dir D:\temp\myserver-cert -out myserver-cert

The script creates the ‘myserver-cert’ folder and produces these outputs in that folder:

Output File

 Description

myserver-cert.csr

Certificate Signing Request file

myserver-cert.key

Key file for the Server Cert

myserver-cert.crt

Certificate file for the Server Cert

myserver-cert.pfx

Password-protected pfx format certificate file to be installed on the Explorer Service host machine identified by the DNA name ‘myserver.acme.com’

Creating Root and Server Certificates on Linux

  • Create a Self-Signed Root CA Certificate on Linux

  • Create a new self-signed Root CA signing certificate using the command

    ./exp-cert.sh createCA <commonName> <days> <rootCaFileName> <outputdir>

    Where the parameters are:

    createCA specifies a create root CA certificate operation <commonName> the common name to be given to the rootCA : example MyRootCA;

    <days>  no of days before rootCA expires : example 3000;

    <rootCAFileName> is the name to be given to the created key and crt files

    <outputdir> is path to a folder to contain the outputs : example /home/tidal/TIDAL/explorer/cert-out

Example: Create a rootCA certificate using common name 'MyRootCA', expiring in 3000 days and using the filename rootCA and saving outputs to folder ~/cert-out
./exp-cert.sh createCA MyRootCA 3000 rootCA ~/cert-out

These rootCA files are created:

  • Key File: ~/cert-out/rootCA.key

  • Crt File: ~/cert-out/rootCA.crt

Generating Your Explorer Server Certificate on Linux

Create a pfx server certificate signed by the rootCA certificate using the command

./exp-cert.sh server <servername> <admin email address> <organisation name> <location> 
<country> <days> <pfx_pw> <rootCA.key path> <rootCA.crt path> <outputdir>

Where the parameters are:

  • server specifies a create server certificate operation

  • <servername> is the fully qualified domain name of the server:

    Example: myserver.acme.com.

  • <admin email address> is a contact email address

    Example: admin@acme.com.

  • <organisation name> 

    Example: acme

  • <location> 

    Example: e.g., chicago

  • <country>

    Example: us

  • <days>  is the no of days before the server certificate expires

    Example: 3000

  • <pfx_pw> is the password used by the created server pfx certificate file

  • <rootCA.key path> is the path to the rootCA.key file

    Example: ~/cert-out/rootCA.key

  • <rootCA.crt path> is the path to the rootCA.crt file

    Example: ~/cert-out/rootCA.crt

  • <outputdir> folder path contain the outputs:

    Example: ~/cert-out (created if not found)

Example: Create a server certificate for the explorer server myserver.acme.com with password 'test', signed by a rootCA certificate with outputs saved to cert-out folder: ./exp-cert.sh server myserver.acme.com admin@acme.com acme chicago us 3000 test ~/cert-
out/rootCA.key ~/cert-out/rootCA.crt ~/cert-out

The signed server PFX format certificate will be created:

 ~/cert-out/myserver.acm.com-cert.pfx