• Overview
  • Note about “strict mode” & transport communication
• Step 1: Obtaining TLS certificates
  • Option A: Obtaining via a public or internal Certificate Authority (CA)
  • Option B: Generating self-signed certificates using an NS1 provided script
  • Option C: Downloading self-signed, auto-generated certificates during the initial setup wizard
• Step 2: Add the certificates to the NS1 DDI platform
  • Option A: Upload via the container’s configuration web interface
  • Option B: Add the certificates directly to the node

Overview

An NS1 Enterprise DDI deployment is made up of control and edge services communicating securely using TLS encryption. TLS certificates ensure that only authorized nodes (sometimes referred to as containers or services) can communicate with each other. In the context of NS1 DDI, certificates are used for:

• Inter-node communication
• Accessing the NS1 portal and API
• Accessing the container management web interface (supd)

It is possible to use custom certificates for any or all of these. During deployment, users can download auto-generated, self-signed certificates in order to get the system up and running quickly. When deploying production environments, however, NS1 highly recommends generating and uploading your own TLS certificates.

Note about “strict mode” & transport communication

If “strict mode” is enabled on a container, NS1 DDI secures communication in a mutually-authenticated manner. This means that for the portal and container configuration web interface, clients must present a certificate with a matching Certificate Authority (CA) and Common Name (CN); and all of the installed transport certificates on each of the nodes must share a common Certificate Authority (CA) and Common Name (CN). Additionally, the security model requires the transport certificates to use a wildcard subdomain as the Common Name. It is highly recommended that the certificates be of the ECDSA type, for security and performance reasons.

This article provides instructions for generating TLS certificates and then uploading them to the NS1 DDI platform.

Step 1: Obtaining TLS certificates

There are three methods to obtain TLS certificates for use with NS1 DDI:

• Obtaining via a public or internal Certificate Authority (CA)
• Generating self-signed certificates using an NS1 provided script
• Downloading self-signed, auto-generated certificates during the initial setup wizard

Option A: Obtaining via a public or internal Certificate Authority (CA)

Requirements

Certificate requirements for accessing the portal/API and container management web interface:

• CA and any intermediate certificates
• Private key
• Certificate that chains back to the CA certs with a Common Name set to the FQDN of the portal/API or container management web interface
• (optional) Matching Client certificate if using Strict Verification for use in your browser

Certificate requirements for transport:

• CA and any intermediate certificates
• Private key
• Certificate that chains back to the CA certs with a wildcard Common Name under the domain that was set as the zone specified in --manual_transport_tls_sni_zone (Strict Mode only)
  • Example: *.ns1.com

Certificate and key recommendations:

• Use Elliptic Curve Keys (minimum 224-bit key length) and Certificates (ECDSA) for best performance and security
• Set a maximum expiration period of 1-2 years for the certificates

Instructions

1. Create a private key

Using an appropriate tool, generate a private key based on the above recommendations. The example below uses OpenSSL to create an Elliptic Curve key with the P-256 curve and stores it in a file named ddi.key:

openssl ecparam -genkey -name prime256v1 -out ddi.key

2. Create a certificate signing request (CSR)

Create a CSR based on the key you just created to satisfy the above requirements (depending on the intended use of this certificate). The CA will use the resulting file to create and sign a certificate that you will use to secure your DDI installation.

Replace the placeholder NS1-specific items in the example with your own.

openssl req -new -key ddi.key -out ddi.csr -extensions v3_req -subj "/C=US/ST=New
  York/L=New York/O=NS1/OU=Engineering/CN=*.ns1.com" -config <(printf "[v3_req]\nkeyUsage
  = keyEncipherment, dataEncipherment\nextendedKeyUsage = serverAuth\nsubjectAltName
  = @alt_names\n[req]\ndistinguished_name = req_distinguished_name\n[req_distinguished_name]\nC
  = US\n[alt_names]\nDNS.1 = *.ns1.com")

3. Request a certificate from your CA

Follow the instructions provided by your CA for obtaining the certificates. The CA will provide the signed certificate you requested and a CA certificate (and potentially one or more intermediate certificates) that chains back to your certificate.

Additional reading:

• https://www.keylength.com
• https://wiki.openssl.org/index.php/Command_Line_Elliptic_Curve_Operations

Option B: Generating self-signed certificates using an NS1 provided script

In this step, you will generate a custom certificate bundle for use with NS1 DDI.

Requirements

• OpenSSL 1.x+
• NS1’s certificate generation script (available here)

Instructions

After downloading the script, you may have modify the access permissions to mark the script as executable:

chmod +x generate_custom_certs.sh

Then run the following command:

./generate_custom_certs.sh -z <domain to use in certificate> [OPTIONS]

Options include:

  -z|--zone Set the zone name to use in the certificates. [required]
  -d|--directory Set the directory to store certificates. [default: 'certs/']
  -t|--type Set the type of key and cert to produce (RSA, ECDSA) [default: ECDSA]
  -f|--force Force overwrite of existing certificates. [default: false]
  -x|--debug Enable debug logging. [default: false]
  -h|--help Print this help page.

After the script runs, the certificates, keys and bundles will be in the directory specified (default is certs).

FILE	DESCRIPTION
transport.bundle.pem	The certificate bundle that DDI uses to secure inter-node communication
management.bundle.pem	The certificate bundle that DDI uses to secure http traffic to and from the management interface (supd)
web.bundle.pem	The certificate bundle that DDI uses to secure http traffic to and from the Portal and API
client.p12	The client certificate that can be used with a browser to authenticate if strict mode is enabled for the management or Portal/API interfaces

Option C: Downloading self-signed, auto-generated certificates during the initial setup wizard

As you complete the installation wizard, the system will prompt you to either generate your own certificates or to download auto-generated certificates.

Click Download to save a file named bundle.tar.gz to your system. Extract this file to find the relevant bundle pem files in the /ns1/data/certs directory.

Step 2: Add the certificates to the NS1 DDI platform

You can add custom certificates to all nodes (containers) for both transport security and the management interface (supd). You can also add a custom certificate to the CORE node to secure the portal and API communications.

Upload certificate bundles directly via each node’s configuration web interface, or place the files in the node manually and activate them using the command-line interface (CLI).

Option A: Upload via the container’s configuration web interface

1. Open a web browser and navigate to the hostname or IP address of the node to which you are adding a certificate at the management port (the default is 3300):
   
   
   
   
2. In the top navigation, click Certificate & File Manager:
   
   
   
   
3. Determine the certificate that you would like to upload and click Upload. Select the file on your local machine, then upload it. A green checkmark displays next to the name of the certificate that you uploaded to show that the certificate was uploaded and validated as a valid certificate bundle:
   
   
   
   
4. Open the Configuration Manager tab and scroll down to the TLS Settings section.
   
   
5. Select Manual Settings from the menu for the Transport, Management, or Web TLS bundle:
   
   
   
   
6. Type the name of the domain that you specified when you created the certificate in the TLS Certificate Zone field.
   
   
7. If necessary, enable Strict Certificate Validation and adjust the TLS version and cipher list:
   
   
   
   
8. Click Commit Changes to save the settings:
   
   

You may also optionally upload a Certificate Revocation List (CRL) to use with custom certificates.

Option B: Add the certificates directly to the node

You must have direct access to the container and the host that it is running on. You must have sufficient privileges on the file system and Docker to bind mount in the relevant files.

Ensure that the certificate bundles are named appropriately:

FILE	DESCRIPTION
transport.bundle.pem	The certificate bundle that DDI uses to secure inter-node communication
management.bundle.pem	The certificate bundle that DDI uses to secure http traffic to and from the management interface (supd)
web.bundle.pem	The certificate bundle that DDI uses to secure http traffic to and from the Portal and API

After the files are on the host system and named appropriately, add a bind mount into the container that works with your chosen DDI deployment method that maps those files into the /ns1/data/certs/custom/ directory.

For example, with Docker Compose, your volume stanza may look like this:

volumes:
  - type: bind
  source: custom-certs
  target: /ns1/data/certs/custom

You can then recreate the container and the certificate bundles will be mounted in (substitute the container that you are working with):

docker-compose up -d core

After the container is up and healthy, you can either follow steps 5 through 8 in the previous section to enable the certificate in the Configuration Manager, or you can run one of the following commands in the container:

supd run --transport_enable_tls manual_transport_tls_settings

supd run --management_enable_tls manual_management_tls_settings

supd run --web_enable_tls manual_web_tls_settings

If you want to enable different options, such as strict verification, you can add them to those commands:

supd run --transport_enable_tls manual_transport_tls_settings --manual_transport_tls_sni_zone
example.com --manual_transport_tls_client_cert_verify true

Refer to the DDI Operator Guide for more information on the different options available.