Skip to main content

Set up a DigiCert gateway

DigiCert gateways are designed to enable secure and efficient certificate management for devices where direct internet access is limited. It acts as a proxy, connecting isolated devices to DigiCert's digital certificate infrastructure to manage device identities and operational certificates effectively in closed networks.

General architecture overview

Once deployed within the network infrastructure, a DigiCert gateway serves as the primary interface between DigiCert ONE IoT Trust Manager and your IoT devices, ensuring controlled access and secure data flow. This positioning allows for secure communications without exposing the internal network to the internet.

Network connection and protocols

Waarschuwing

DigiCert gateway does not provide any services for OCSP (Online certificate status protocol) or CRLs (Certificate Revocation List).

DigiCert gateways support several essential protocols to ensure robust security and interoperability:

  • Certificate request REST API Provides REST API endpoints that allow for the requesting and renewing of certificates.

  • EST (Enrollment over Secure Transport) Facilitates secure certificate enrollment by encrypting the transport layer, ensuring that all communications remain confidential and tamper-proof.

  • CMPv2 (Certificate Management Protocol version 2) Allows devices to perform certificate-related operations such as registration, renewal, and revocation through a secure protocol.

  • SCEP (Simple Certificate Enrollment Protocol) Enables simpler devices to enroll for certificates securely, supporting widespread adoption in environments with varied technological capabilities.

  • ACME (Automatic Certificate Management Environment) Automates the process of obtaining, renewing, and managing SSL/TLS certificates.

Before you begin

Make sure you have the following requirements before attempting to configure a DigiCert gateway.

  • Java runtime environment version 14 or higher installed on the gateway host.

  • Email address of the administrator performing the gateway installation.

  • If binding the gateway to a MAC address, you will need the MAC address of host device on which the gateway will be installed.

  • If you secure your gateway traffic through HTTPS, a TLS certificate (private key in PKCS12 format) on the host device.

Step 1: Create a DigiCert gateway

  1. In the DigiCert​​®​​ IoT Trust Manager menu, select Integrations > DigiCert gateways.

  2. Click Create gateway.

  3. On the DigiCert gateway information page, do the following:

    1. Enter a Gateway nickname.

    2. (Optional) Enter a Description

    3. Enter a Server Admin User Email.

    4. Select whether or not to bind the gateway to a MAC address. If binding to a MAC address, enter the MAC address of the host device.

      Belangrijk

      During the installation process, the server admin will be asked to enter the MAC address of the hose device. If binding to a MAC address, make sure the entered MAC address is the same as the device on which the gateway will be installed.

    5. Select an Authentication method. Authentication assets are automatically generated when the gateway is created and provided to the installer.

  4. Select Create.

Let op

Network settings, such as MAC address and port number, will be collected from the server admin during the installation of the DigiCert gateway on the host device.

Step 2: Download gateway installation file

Once a DigiCert gateway is created, an email with instructions to download and install the DigiCert gateway is sent to the admin email address. This email contains a tokenized link to download the DigiCert gateway installation zip file.

  1. Find and open the email with the subject line DigiCert Gateway Installation.

  2. Click Download installation file.

  3. Choose a location to save the DigiCert_Installation.zip file.

Belangrijk

The tokenized download link expires after 48 hours, or when used. To resend the email with a new tokenized link, hover over the name of the new gateway and select More actions > Resend. The server admin will receive a new email with a new tokenized link that will expire in 48 hours, or when used.

Step 3: Prepare for HTTPS (optional)

If you choose to secure your gateway traffic via HTTPS, you must provide a TLS certificate in PKCS12 format during installation. Follow the steps below to prepare your certificate and understand the options available.

Determine the certificate type

You have two options for obtaining a TLS certificate:

  • CA-signed certificate Recommended for production environments. A certificate issued by a trusted Certificate Authority (CA) ensures HTTPS traffic is fully secure and trusted.

  • Self-signed certificate Suitable for test or development environments. This option comes with risks as it won’t be trusted by external parties, potentially leading to browser warnings and security vulnerabilities.

Waarschuwing

Using a self-signed certificate poses potential security risks due to the lack of third-party validation. If using a self-signed certificate, make sure you understand the risks associated with it.

Create or convert a TLS certificate into PKCS12 Format

If you have an existing certificate (public CA-signed or self-signed)

To convert an existing certificate and its private key into PKCS12 format, follow these steps:

  1. Ensure you have the following files:

    • The certificate (.crt or .pem file).

    • The private key (.key file).

  2. Use the following OpenSSL command to combine the certificate and private key into a PKCS12 file:

     openssl pkcs12 -export -in <certificate.crt> -inkey <private.key> -out <output-file.p12> -name "<certificate_name>"

    Replace <certificate.crt>, <private.key>, and <output-file.p12> with the paths to your files, and set <certificate_name> as a key alias for the certificate.

If you need to create a self-signed certificate

To generate a self-signed certificate and bundle it with a private key into a PKCS12 file, use the following steps:

  1. Use OpenSSL to create a private key and self-signed certificate:

     openssl req -x509 -newkey rsa:2048 -keyout <private.key> -out <certificate.crt> -days 365

    You will be prompted to enter certificate details like country and organization. The -days flag specifies the validity period of the certificate.

  2. Convert the self-signed certificate and private key into a PKCS12 file:

     openssl pkcs12 -export -in <certificate.crt> -inkey <private.key> -out <output-file.p12> -name "<self_signed_certificate>"

Verify the PKCS12 file

Once you’ve created or converted the certificate to the PKCS12 format, it’s important to verify its contents to ensure everything is correct. Use the following command to check the file:

 openssl pkcs12 -info -in <output-file.p12>

This command will display the contents of the PKCS12 file, showing the included certificates and private key. Make sure the certificate and key are accurate before proceeding with installation.

Belangrijk

If you choose to use HTTPS, the gateway installer will prompt you to provide the PKCS12 file containing your TLS certificate. Ensure the PKCS12 file is available and accessible on the host system where the gateway is being installed.

Step 4: Install a DigiCert gateway

Before installing a DigiCert gateway, ensure the following:

  • The DigiCert_Installation.zip file is transferred to the host device where the gateway will be installed.

  • The necessary prerequisites, such as the Java runtime environment, are in place.

  • If using HTTPS, make sure you have the following information:

    • File path to the PKCS12 file.

    • If password protected, the passcode for the PKCS12 file.

    • If needed, the key alias of the key to use.

Tip

See Step 3: Prepare for HTTPS (optional) information on creating a PKCS12 certificate file.

  1. On the host device, unzip the installation file:

     unzip DigiCert_Installation.zip

  2. Navigate to the extracted directory and run the gateway-install.jar file:

     java -jar gateway-install.jar

The installer will prompt you for several inputs, detailed in the table below:

Installer Question

Required/Optional

Description

Example

Server MAC address

Optional

MAC address of the host device. If MAC address validation is required, this should match the host’s MAC.

ab:cd:ef:12:1a:11

HTTP (y/n)

Required

Specifies whether the gateway will use HTTP.

y or n

HTTP port

Required if HTTP

The port number for HTTP traffic.

80

HTTPS (y/n)

Required

Specifies whether the gateway will use HTTPS for secure communication.

y or n

SSL certificate path

Required if HTTPS

The file path to the PKCS12 certificate used for HTTPS.

/path/to/keystore.p12

SSL certificate passcode

Optional

Passcode for the PKCS12 file, if it is password-protected.

test

SSL certificate key alias

Optional

Key alias for the certificate, if the PKCS12 file contains multiple keys.

key_alias

HTTPS port

Required if HTTPS

The port number for HTTPS traffic.

443

Description of installation questions

Below are further explanations of each option and how to provide the necessary information:

  • Server MAC address This is optional unless MAC address validation is required. If you choose to bind the gateway to a specific MAC address, enter the MAC address of the host device.

  • HTTP/HTTPS Options You will be asked whether you want to use HTTP, HTTPS, or both. If you select “y” for HTTP, the installer will prompt you for the HTTP port number. If you select “y” for HTTPS, the installer will ask for the PKCS12 certificate path, the passcode (if any), and the HTTPS port number.

    Let op

    The SSL certificate passcode and key alias are only needed if the PKCS12 file is passwordprotected or contains multiple keys. If not needed, these fields can be left blank.

After all the necessary information is provided, the installer performs the following tasks:

  • Modifies the application.yml configuration file, which contains the necessary information to connect the gateway to IoT Trust Manager.

  • Connects to IoT Trust Manager using the provided information.

  • Downloads the pre-configured Digicert-Gateway.jar file, which along with the application.yml file is used to run the gateway.

Step 5: Start a DigiCert gateway

DigiCert gateways can be started using the Java Virtual Machine (JVM) by executing it with the java -jar command. Alternatively, you can use Docker to containerize and run the application, which involves creating a Docker image that includes the Java runtime and your .jar file. This approach is useful for ensuring consistent environments across different systems.

  1. Confirm that the following files are present in the same directory as the Digicert-Gateway.jar file:

    • application.yml This configuration file contains the authentication and network settings required for the gateway to connect to IoT Trust Manager.

    • PKCS12 certificate If using HTTPS, the certificate file for securing HTTPS communication.

    All required files must be located in the same directory as the Digicert-Gateway.jar file for the gateway to function correctly.

  2. With all required files in place, use one of the following to start the gateway:

    • To use JVM:

      java -jar Digicert-Gateway.jar

    • To use Docker (make sure to replace the port numbers with the ones you configured during installation):

      docker run -it -v "$(pwd)":/config -e JAVA_OPTS="- Dspring.config.location=/config/ application.yml" -p 80:80 -p 443:443 DC- Gateway

      Opmerking

      The above example assumes you are using both HTTP and HTTPS for communication, as indicated by the two -p options. If using only one communication method (HTTP or HTTPS), you only need to specify one port option.

After starting the gateway, it will attempt to connect to DigiCert® IoT Trust Manager.

  • The gateway uses the authentication credentials (API token, client authentication certificate, or enrollment profile) that were set up during installation.

  • If HTTPS is enabled, the gateway will use the provided PKCS12 certificate for secure communication.

  • When successful, the status of the gateway in IoT Trust Manager will change from Ready to Active.

Let op

If the gateway fails to start or connect, verify the following:

  • Ensure the MAC address, ports, and authentication credentials are correct.

  • Check the firewall settings on the host device to ensure the required ports are open.

  • If the device has multiple network interfaces, confirm that the correct interface is being used for the gateway’s communication.

Run a gateway on multiple devices (optional)

If MAC address validation is not enabled, you can reuse the gateway installation across multiple devices. To do this:

  1. Copy the following files to the target device:

    • Digicert-Gateway.jar

    • application.yml

    • PKCS12 certificate (if using HTTPS)

  2. Run the gateway using the same command above.

This allows the gateway to be deployed on multiple devices without needing to perform the installation multiple times.

Waarschuwing

If MAC address validation is enabled, the gateway can only be run on the original host device with the specific MAC address that was validated during installation.

In deze sectie: