SSL Certificate Generation

Overview

For the purposes of a Client machine authenticating a Server and vice versa, a minimum of three x509 certificate/key pairs are needed:

• A certificate authority (CA)

• A Server certificate

• A Client certificate

Deadline Clients expect the Client certificate (+ private key) to be in PKCS#12 format (*.pfx or *.p12 file), which can be password-protected. Additionally, it is recommended that this PKCS#12 file contain a copy of the CA certificate (NOT its private key), allowing Deadline to validate the Server’s certificate without needing to add the CA to the OS’s list of trusted roots.

You could generate these certificates/keys manually using tools such as OpenSSL, but that topic is not covered in-depth here.

Using the utility script

For your convenience, we have hosted a Python utility script that can be used in conjunction with PyOpenSSL from the cryptography python module to create a basic set of certificates that can be used for Deadline authentication as described above. You can download this script from Thinkbox GitHub.

Requirements

1. Python

2. pyOpenSSL module

Usage

This section will go over how to generate each one of these using the utility script linked in the overview above.

NOTE: While the certificates themselves (*.crt) can be transported without much worry (they can be considered public knowledge), each generated certificate will have an associated private key (*.key) which is more sensitive in nature. Knowledge of any of the private keys would allow impersonation of a valid Client or Server (or both) in the system; as such, these files should be password-protected whenever possible, and always maintained with restrictive file permissions/ACLs. Note that sometimes, both the certificate and private key are combined into a single file for convenience (generally in *.pem, *.pfx, or *.p12 files).

1. Generating a new CA:

   The Certificate Authority (CA) is used to sign other certificates, indicating that they can be trusted as authentic.
   In this way, trusting a root CA in turns implies trust of all certificates that were (or will be) signed by that CA; this is the mechanism that Deadline leverages to authenticate clients and servers when negotiating secure communication.
   
   To generate a new CA, simply run the following command using the script provided above:
   
   >>> python ssl_gen.py --ca --cert-org <company/org name> --cert-ou <company/org unit>
   
   This will place a 'ca.crt' and 'ca.key' file in the 'keys' sub-directory.
   
   The public portion of this (the \*.crt file) will need to be distributed to the Client and Server machines, so that they can validate each other's certificates (that will be signed by this CA).
   This can be done easily by packaging the \*.crt in a PFX file (see last step).
   
   On the other hand, the private portion of this (the key) should be closely guarded.
   Access to the private key of a Certificate Authority allows creation of new client certificates, which would automatically be trusted by the server.
   

2. Generating the server certificate:

   This is the certificate that the Server will use for the purposes of identifying itself when negotiating TLS connections.
   It will be signed by the CA that was generated in Step 1.
   
   Simply run the following command using the provided script:
   
   >>> python ssl_gen.py --server --cert-name <server name>
   
   This will place a '<server name>.crt' and '<server name>.key' file in the 'keys' sub-directory.
   
   These files should be placed on the Server machine (and *only* on the Server machine), which restrictive file permissions granting read access only to the user(s) that will run the Server process.
   

3. Generate the client certificate(s):

   This is a certificate that will be used by Deadline clients to authenticate themselves, and you can create more than one.
   While they don't need to be signed by the same CA as the Server certificate, the Server will need to trust the root that *does* sign it (either by having it specified explicitly, or present in the OS-level trusted store).
   
   To generate a client certificate signed with the CA created in Step 1, use the following command:
   
   >>> python ssl_gen.py --client --cert-name <client name> --passphrase <password>
   
   This will place a '<client name>.crt' and '<client name>.key' file in the 'keys' sub-directory.
   The key file will be encrypted with the passphrase '<password>'.
   

4. Create a PKCS#12 container for use by Deadline clients:

   This step is not actually generating a new certificate, but just re-packaging the output of Step 1 and 3 in a Deadline-friendly format.
   More specifically, it will wrap the three following items in a single file:
   
     - CA certificate
     - Client certificate
     - Client private key
   
   Note that this file does contain a private key, and as such should be protected by a password.
   
   To do so, run the following command:
   
   >>> python ssl_gen.py --pfx --cert-name <client name> --passphrase <password>
   
   This will place a '<client name>.pfx' file in the 'keys' directory; this is the file that Deadline clients will need to connect to the remote server.