Skip to main content

Script types

DigiCert​​®​​ Trust Lifecycle Manager supports the following script types to customize agent-based certificate lifecycle management on your servers. Select the links for more details about each script type.

Script type

Description

Custom automation

Manage certificates for custom server applications.

SNI information

Dynamically learn the SNI domains used by DigiCert agents to discover and manage certificates.

Pre-installation

Do extra work before installing a certificate for a web server application during an automation event.

Post-installation

Do extra work after installing a certificate for a web server application during an automation event.

Admin request post-delivery

Do extra work after delivering a certificate to a server system using the admin web request enrollment method.

Importante

Use one of the following languages for your custom agent scripts, based on the host operating system:

  • Windows: bat, cmd, or PowerShell script

  • Linux: shell script (any)

If you use a different language/format to do work, use one of the above scripting languages as a wrapper to ensure compatibility.

Custom automation

Use custom automation scripts to manage certificates for custom server applications through DigiCert agents.

This type of script allows you to use your own ACME client like Certbot on your server to manage certificate lifecycles for applications not natively supported by Trust Lifecycle Manager.

You configure the custom automation script to invoke the third-party ACME client with the options needed to request and install certificates for your application.

To learn more, see Configurar um aplicativo personalizado para automação gerenciada.

SNI information

Trust Lifecycle Manager requires administrators to supply a list of active domains in order to discover and automate certificates on websites using Server Name Indication (SNI). You can use SNI information scripts to dynamically learn the SNI domains on your servers so you don't need to configure them manually.

For example, you might read the SNI domains directly from your web server configuration to ensure that your DigiCert agents always have the latest information.

To simplify management, Trust Lifecycle Manager allows you to assign the scripts across multiple agents in bulk.

Script output format

Set up your SNI script to output the SNI information as JSON in the following format.

exemplo 1. JSON output format for SNI information script
[
   {
        "IP": "10.1.2.3",
        "Port": "8443",
        "Domain": "www.example.com"
    },
    {
        "IP": "10.1.2.3",
        "Port": "8443",
        "Domain": "app2.example.com"
    }
]

Example script (PowerShell)

The following example SNI information script uses the Microsoft PowerShell scripting language to read the latest SNI information from the local IIS web server. It outputs the information as JSON to use to dynamically configure the local DigiCert agent.

exemplo 2. SNI information script (PowerShell) for IIS web server application
$bindingInfo = get-website | select -ExpandProperty Bindings | Select -ExpandProperty Collection | where sslFlags -eq 1 | select bindingInformation

$res = @{}

foreach($ele in $bindingInfo) {
        $list = $ele.bindingInformation.split(":")
        $res[$list[2]] = @{IP=$list[0]; Port=$list[1]; Domain=$list[2]}
}

$thumbs = Get-ChildItem IIS:SSLBindings | Foreach-Object {
        [PSCustomObject]@{
                Host       = $_.Host
                Thumbprint = $_.Thumbprint
        }
}

echo($res.values | ConvertTo-Json)

Pre- or post-installation

Use pre- or post-installation scripts to do extra work before an automation event (pre-installation) or after the local DigiCert agent installs the certificate in an automation event (post-installation).

This type of script allows you to do any type of work needed to facilitate PKI operations on your servers, such as readiness testing, preparation, or clean up. You can use different pre- or post-installation scripts per web server application.

To simplify management, Trust Lifecycle Manager allows you to assign the scripts across multiple agents in bulk.

Return codes

Return 0 from a pre-installation script for success, or non-zero for failure. Avoid using return codes 1, 127, or 4294770688 as they are pre-defined by the agent for other purposes.

With pre-installation scripts, the DigiCert agent will cancel the automation event if the script does not return a success code of 0. This helps you control when a certificate is automated based on an external input.

Admin request post-delivery

Use this script type to perform extra work after delivering a certificate from Trust Lifecycle Manager to an external server system using the admin web request enrollment method.

When you assign the post-delivery script to an agent-based certificate automation event, you can enter up to five parameters to pass to the target host to control how the script gets executed there.

Script execution data

During a certificate delivery event, the local DigiCert agent adds script-related data to the DC1_POST_SCRIPT_DATA environment variable in Base64-encoded JSON format. Target and decode this variable in your post-delivery scripts to get the list of parameters passed from Trust Lifecycle Manager and other relevant details to help process the delivered certificate, as in the following examples:

  • Example of decoded DC1_POST_SCRIPT_DATA environment variable value after delivering a PKCS#12 certificate (.pfx file extension) on a Windows system:

    {"args":["abc", "def"],"certfolder":"C:\Program Files\DigiCert\TLM Agent\.secrets","files":["my-cert-1.pfx"], "password":"P@ssw0rd"}
  • Example of decoded DC1_POST_SCRIPT_DATA environment variable value after delivering an X.509 certificate (.crt file extension) on a Linux system:

    {"args":["abc","def","ghi"],"certfolder":"/opt/tlm_agent/.secrets","files":["my-cert-1.crt","my-cert-1.key"]}

JSON fields in the output depend on the type of certificate delivered and may include:

JSON field

Description

Certificate types

args

List of up to five extra parameters passed to the script from Trust Lifecycle Manager.

All

certfolder

Directory path where the certificate was delivered.

All

files

Names of the certificate files delivered to the above directory.

All

password

The password used to encrypt the certificate file.

PKCS#12 (PFX), PEM, P7B

keystorepassword

Password for the keystore where the certificate was delivered.

JKS

truststorepassword

Password for the truststore where the certificate was delivered.

JKS

Example script (PowerShell)

The following example post-delivery script uses the Microsoft PowerShell scripting language to import a delivered PKCS#12 (PFX) certificate to the LocalMachine\My certificate store on a Windows system. The script decodes and parses the JSON in the DC1_POST_SCRIPT_DATA environment variable to determine the certificate filename, password, and directory where it was delivered by the local DigiCert agent.

# Function to decode base64 encoded string
function Decode-Base64 {
    param (
        [string]$base64String
    )
    $bytes = [System.Convert]::FromBase64String($base64String)
    $decodedString = [System.Text.Encoding]::UTF8.GetString($bytes)
    return $decodedString
}

# Base64 encoded JSON input
$base64Json = [System.Environment]::GetEnvironmentVariable("DC1_POST_SCRIPT_DATA")

# Decode the base64 encoded JSON
$jsonString = Decode-Base64 -base64String $base64Json

# Convert JSON string to PowerShell object
$jsonObject = $jsonString | ConvertFrom-Json

Write-Host "Arguments : "$jsonObject.args

# Extract values from JSON object
$certFolder = $jsonObject.certfolder
$pfxFile = Join-Path -Path $certFolder -ChildPath $jsonObject.files[0]
$password = $jsonObject.password

# Validate inputs
if (-not (Test-Path -Path $pfxFile)) {
    Write-Error "ERROR: The PFX file does not exist."
    exit 1
}

# Import the PFX file into the LocalMachine\My store
try {
    $cert = Import-PfxCertificate -FilePath $pfxFile -CertStoreLocation Cert:\LocalMachine\My -Password (ConvertTo-SecureString -String $password -Force -AsPlainText)
    if ($null -eq $cert) {
        throw "Failed to import the certificate."
    }
    Write-Output "Certificate imported successfully."
} catch {
    Write-Error "ERROR: Failed to import the certificate. $_"
    exit 1
}

Example script (Bash shell)

The following example post-delivery script uses the Bash shell scripting language to import a delivered X.509 (CRT) certificate to the /etc/pki/ca-trust/source/anchors trusted CA directory on a Red Hat-based Linux system that has the ca-certificates package installed. The script decodes and parses the JSON in the DC1_POST_SCRIPT_DATA environment variable to determine the certificate filename and directory where it was delivered by the local DigiCert agent.

#!/bin/bash

# Step 1: Read the Base64-encoded JSON string from the environment variable
CERT_INFO=${DC1_POST_SCRIPT_DATA}

if [[ -z "$CERT_INFO" ]]; then
    echo "Error: Environment variable 'DC1_POST_SCRIPT_DATA' is not set or is empty."
    exit 1
fi

# Step 2: Decode the Base64 string into JSON
JSON_STRING=$(echo "$CERT_INFO" | base64 -d)

# Step 3: Parse JSON manually to extract 'certfolder' and '.crt' file
CERT_FOLDER=$(echo "$JSON_STRING" | grep -oP '"certfolder":"\K[^"]+')
CRT_FILE=$(echo "$JSON_STRING" | grep -oP '"files":\["\K[^"]+\.crt')

if [[ -z "$CERT_FOLDER" || -z "$CRT_FILE" ]]; then
    echo "Error: Invalid JSON data. Could not find 'certfolder' or '.crt' file."
    exit 1
fi

# Step 4: Construct full path to the certificate file
CRT_FILE_PATH="${CERT_FOLDER}/${CRT_FILE}"

if [[ ! -f "$CRT_FILE_PATH" ]]; then
    echo "Error: Certificate file not found at path '$CRT_FILE_PATH'."
    exit 1
fi

# Step 5: Copy the certificate to the system's trusted CA directory
TRUSTED_CA_DIR="/etc/pki/ca-trust/source/anchors"
DEST_CRT_FILE="${TRUSTED_CA_DIR}/$(basename "$CRT_FILE")"

echo "Copying certificate to trusted CA directory..."
sudo cp "$CRT_FILE_PATH" "$DEST_CRT_FILE"

# Step 6: Update the system's trusted certificates
echo "Updating trusted certificates..."
sudo update-ca-trust extract

if [[ $? -eq 0 ]]; then
    echo "Certificate successfully added to the system's trusted certificates."
else
    echo "Error: Failed to update the trusted certificates."
    exit 1
fi
data de publicação: