Skip to main content

Set up a DigiCert gateway

About DigiCert gateways

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 the IoT devices, ensuring controlled access and secure data flow. This positioning facilitate secure communications without exposing the internal network to the internet.

Network connection and protocols

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

  • 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.

Prerequisites

  • Java runtime environment version 17 or higher.

  • Email address of the administrator performing the gateway installation.

  • MAC address of the host device on which the gateway will run.

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

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.

    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 will be collected from the server admin during the installation of the DigiCert gateway on the host device.

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.

Install a DigiCert gateway

Let op

The gateway installer must be run on the host device it will be installed on. Make sure to transfer the DigiCert_Installation.zip file to the appropriate host device before installing.

  1. Extract the DigiCert_Installation.zip file.

  2. Go to the directory where you extracted DigiCert_Installation.zip, and execute the .jar file using the following command:

    java -jar gateway-install.jar

Once run, the installer asks for the MAC address of the server, server port number, and whether to use HTTP or HTTPS for communication.

Let op

If using HTTPS, you will be asked to provide the TLS certificate path, TLS certificate password, and HTTPS port number. See Configure SSL support (optional) for details on generating a PKCS12 certificate.

During the installation, the installer does the following:

  • Sends the provided information from the host device to DigiCert​​®​​ IoT Trust Manager.

  • Downloads a preconfigured dcone-gateway.jar file. This is used to run the gateway service on the host device.

  • Tells DigiCert​​®​​ IoT Trust Manager to change the status of the DigiCert gateway from Invite sent to Ready.

After the installation finishes, you are ready to start the gateway service.

Configure SSL support (optional)

When using HTTPS, you need to provide a keystore file using OpenSSL. Use the following command to generate the PKCS12 file:

openssl pkcs12 -export -inkey [private_key] -in [certificate] -name [alias] -out [name_of_pkcs12]

For a certificate chain, include the certificate file in the command as shown below:

openssl pkcs12 -export -inkey [private_key] -in [certificate] -certfile [chain_file] -out [name_of_pkcs12]

These commands create a PKCS12 file that includes your private key, certificate, and, if applicable, the certificate chain.

Start a DigiCert gateway service

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.

Start a gateway using JVM

  1. On the gateway host device, create a new directory called dcone-gateway.

    Belangrijk

    Make sure the dcone-gateway directory is protected to restrict unauthorized access.

  2. Copy the DC-Gateway.jar file into the dcone-gateway directory.

  3. In the dcone-gateway directory, create a new directory called config.

  4. Copy your configuration yaml file into the config directory.

  5. Run the application:

    java -jar DC-Gateway.jar --spring.config.location=config/application.yml

    To redirect logging to a different directory:

    java -jar DC-Gateway.jar --spring.config.location=config/application.yml > [path-to-directory]/gateway.log 2>&1

Start a gateway using docker

  1. Navigate to the directory where you want run the gateway.

  2. Copy your configuration yaml file into the directory.

  3. Run the application:

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

    Belangrijk

    Insert correct ports as generated in your configuration yaml file.

In deze sectie: