Sectigo Palo Alto Firewall Agent

Overview

The Sectigo Palo Alto Firewall Agent (the agent) is a certificate management solution designed to automate the enrollment and management of SSL/TLS certificates for Palo Alto VM-Series virtual next-generation firewall and secure communication between the external clients and applications behind the firewall.

The certificate lifecycle management is handled by Sectigo SDK for Python which communicates with the Sectigo backend server through the SCM enrollment API to request and renew SSL/TLS certificates, and import them into the certificate management area of Palo Alto Firewall using the PAN-OS REST API.

The administrator creates a firewall profile for Palo Alto and adds its name to the certificate profiles—​this way, a single firewall profile can be used as target in multiple certificate profiles.

The agent can obtain the following types of SSL/TLS certificates:

  • Domain Validation (DV) certificates

  • Organization Validation (OV) certificates

  • Extended Validation (EV) certificates

Scope

This guide contains instructions for enrolling and managing Sectigo certificates on Palo Alto virtualized firewalls. It does not cover configuration of firewalls.

Audience

This document is intended for IT administrators and network administrators who manage Palo Alto virtualized firewalls.

Architecture

The agent is developed using Sectigo Certificate Manager (SCM) SDK for Python. The SDK uses the SCM REST API to securely authenticate and communicate with the Sectigo backend for certificate management.

Sectigo Palo Alto Firewall Agent architecture

The agent uses two Sectigo REST APIs to enroll and renew SSL certificates:

  • OAuth API: Responsible for OAuth authentication and JWT token creation.

  • Enrollment API: Responsible for certificate management (enrollment and renewal) using access token received from the OAuth API. The enrollment API supports OAuth 2.0 to protect customer information.

The following key types are supported: RSA (2048, 3072, 4096), ECDSA (256, 384, 521).

The client secret can be encrypted to protect from unauthorized access. To access and manage GPG encrypted credentials, the agent uses the sops editor.

The agent supports only the pre-validated domains in SCM. The domains for which certificates are requested should go through Domain Control Validation (DCV) in SCM as per the instructions provided in Section 6.4.2 How To Validate Domains of the SCM administrator’s guide. For more information on DCV methods, see Domain Control Validation Methods in Sectigo’s Knowledge Base.

Package contents

The package contains the following components:

  • paloaltofw: This folder and its subfolders contain the agent and configuration files

    • paloaltoagent.py: The agent as an executable file

    • config.yaml: This file stores the configuration for SCM, logging, and encryption

    • profiles_sample: This folder contains sample configuration files for a certificate profile, firewall profile, and SCM credentials

      • certificate.yaml: A sample configuration file for a certificate profile

      • fw_paloalto_config.yaml: A sample configuration file for a firewall profile

      • sectigo_credentials.yaml: This file stores SCM credentials

  • SCM Client EULA v1.0.1.txt: The EULA agreement. You need to accept it once when running the agent for the first time.

  • requirements.txt: This file contains a list of Python dependencies

Execution workflow

The script is triggered manually or automatically through a cronjob. You specify which operation will be performed by the script and, optionally, define the certificate profile name when the target is a specific certificate profile. The available operations include enrollment, renewal, encryption, and decryption.

The script performs the following actions:

  1. Loads its configuration from the config.yaml file. The path to the config file is stored in the sectigo_pycert_config environment variable. Alternatively, the script looks for the file in the relative path of paloaltoagent.py. The script reads information from the config file, such as the SCM API URL, the log level, the path for saving the log file and its name, and the path to the certificate and firewall profiles.

  2. Reads the certificates and firewall profile files. Each certificate profile describes a unique certificate that can be DV, OV, or EV. The certificate profile file contains all the information related to the certificate, such as domains, SANs, key type and size, and the target firewall name. The firewall profile contains information related to the Palo Alto firewall instance, such as the API key, URL or IP address, admin name, and commit description. You can encrypt these credentials using GPG.

  3. Sends a request to Palo Alto to check whether a certificate named as the certificate profile already exists. If the certificate doesn’t exist, or is expired or revoked, the script calls the Palo Alto API to generate a CSR with the certificate information. Palo Alto creates an asymmetric key pair with the key type and size defined in the certificate profile, then creates a CSR using the public key and signs it with the private key. The private key is not exposed to the outside world—​it is kept private inside the Palo Alto firewall.

  4. Downloads the CSR and submits it to the Sectigo CA (Public or Private CA) which issues an SSL/TLS certificate based on the information in the CSR. The script downloads the certificate chain.

  5. Saves the certificate ID in Base64 format to a file with the .ids extension, imports the downloaded certificate chain into Palo Alto, and commits the changes.

  6. Writes the main events that occur during enrollment or renewal of a certificate into the log file.

Prerequisites

The integration assumes that a Palo Alto firewall instance already exists.

The agent needs access to the Internet to communicate with the Sectigo backend server and access to the Palo Alto firewall to install the certificates.

General requirements

  • Operating systems: The integration was tested on RHEL 8, Ubuntu 20.04, and Windows 10

  • Python: Install Python 3.6 or later.

  • pip: Install the pip package installer for Python.

    • DEB

    • RPM

    sudo apt-get install python3-pip
    sudo yum install python3-pip
  • sops: If you are going to use encryption, install the sops editor for encrypting and decrypting the client secret. You can check that sops is installed on the system using the sops --version command. If the tool is not available, install it with the package.

  • Go: If you are going to use encryption, install Go 1.17 or later.

    • DEB

    • RPM

    sudo apt-get install golang
    echo 'export GOPATH=~/go' >> ~/.bashrc
    source ~/.bashrc
    mkdir $GOPATH
    sudo yum install golang
    echo 'export GOPATH=~/go' >> ~/.bashrc
    source ~/.bashrc
    mkdir $GOPATH
  • GPG (GNU Privacy Guard): Install GPG. You can check that GPG is installed on the system using the gpg --version command. The last two commands from the following list of commands allow you to generate the randomness required to generate a key.

    • DEB

    • RPM

    sudo apt-get install gnupg
    sudo apt-get install rng-tools
    sudo sed -i -e 's|#HRNGDEVICE=/dev/hwrng|HRNGDEVICE=/dev/urandom|' /etc/default/rng-tools
    sudo service rng-tools start
    GPG_TTY=$(tty)
    export GPG_TTY
    sudo yum install gnupg
    sudo tum install rng-tools
    sudo sed -i -e 's|#HRNGDEVICE=/dev/hwrng|HRNGDEVICE=/dev/urandom|' /etc/default/rng-tools
    sudo service rng-tools start
    GPG_TTY=$(tty)
    export GPG_TTY

SCM requirements

  • SCM API: To enable API access for your account:

    1. Log in to SCM at https://cert-manager.com/customer/<customer_uri> with your credentials.

    2. On the Organizations page, select your organization and click Edit.

    3. Select Certificate Settings, then expand the SSL Certificates menu.

    4. Enable the Web API option.

      If the option is not available for your account, contact Sectigo Support or the Onboarding Team to have SCM API access enabled.
  • SCM API credentials: Obtain the sectigo_scm_url value for the config.yaml file, and sectigo_cm_user_id and sectigo_cm_user_secret values for the sectigo_credentials.yaml:

    1. Select Enrollment  REST. Under URL next to SSL Certificates REST API, you will see the value for sectigo_scm_url.

      SSL certificates REST API
    2. Select SSL Certificates REST API and click Accounts.

    3. Select your account and click Edit. The SCM admin can edit existing or create new accounts.

      SSL certificates REST accounts
    4. Click Reset Secret and confirm client reset secret.

      SSL certificates REST accounts

      You will see the values for sectigo_cm_user_id and sectigo_cm_user_secret under Client ID and Application (client) Secret.

      Client ID and secret
  • Certificate profile: Configure a certificate profile for a firewall instance. The sample certificate.yaml file is located in the profiles_sample directory. You can have one or more certificate profile for each firewall profile. You can give any name to the certificate profile file.

    The following table describes parameters in the file.

    Parameter Description

    paloalto_fw_profile

    The name of the firewall profile file

    scm_credential_detail

    The credential ID (label) from the sectigo_credentials file.

    sectigo_ssl_cert_type

    The type of the SSL certificate. The supported values are DV, OV, and EV.

    sectigo_ssl_cert_comments

    Comments for certificate enrollment

    sectigo_ssl_cert_external_requester

    The email or a comma-separated list of emails of the certificate requester

    sectigo_ssl_cert_subject_alt_names

    A comma-separated list of subject alternative names (SAN)

    sectigo_csr_domain

    A single value for a domain included in the certificate Common Name (CN) field

    sectigo_csr_country

    The country name included in the certificate Country © field

    sectigo_csr_state

    The state or province name included in the certificate State (ST) field

    sectigo_csr_location

    The location name included in the certificate Location (L) field

    sectigo_csr_organization

    The organization name included in the certificate Organization (O) field.

    sectigo_csr_email_address

    The email address included in the certificate emailAddress field

    sectigo_csr_key_type

    The private key algorithm to use to generate the private key. The possible values are RSA and EC.

    sectigo_csr_key_size

    The size of the TLS/SSL key to generate. The possible values are 2048, 3072, 4096 for RSA and 256, 384, 521 for ECDSA.

    sectigo_force_renewal

    Whether to forcibly renew a certificate, even though it’s not yet expired. The default value is false.

    sectigo_expiry_window

    The period of days prior to expiration that a certificate renewal process will be initiated (numeric). The default expiry window is 30 days.

    An example certificate profile.

    # 1. Paloalto Firewall information
    paloalto_fw_profile: "fw_paloalto_config"
    # 2. SCM Credentials
    scm_credential_detail : "SCMDV"
    # 3. <SSL CERT RELATED VALUES>
    sectigo_ssl_cert_type: DV
    sectigo_ssl_cert_comments: Certificate for Palo Alto Firewall
    sectigo_ssl_cert_subject_alt_names: example.com, www.example.com
    # 4. <CSR RELATED VALUES>
    sectigo_csr_domain: "www.example.com"
    sectigo_csr_country: "CA"
    sectigo_csr_state: "ON"
    sectigo_csr_location: "Ottawa"
    sectigo_csr_organization: "JohnDoe"
    sectigo_csr_email_address: [email protected]
    sectigo_csr_key_type: "RSA"
    sectigo_csr_key_size: "3072"
    # 5. <OTHER VALUES>
    sectigo_force_renewal: False
    sectigo_expiry_window: 30
    sectigo_auto_renew: true
  • Configuration file: Configure the config.yaml file.

    The following table describes parameters in the file.

    Parameter Description

    sectigo_log_file

    The name for the log file. When the log file reaches its maximum size as specified in sectigo_logger_size_mb, the current log file is backed up and a new log file is created. For example, if the log file name is sectigo_pycert.log, backed up log files will be named as sectigo_pycert.log.1, sectigo_pycert.log.2, and so on.

    sectigo_log_path

    The path to the directory that hosts the log files.

    If you are on Windows, use a double backslash as a separator (\\).

    cert_profile_path

    The path to the directory that hosts the certificate and firewall profile files.

    If you are on Windows, use a double backslash as a separator (\\).

    sectigo_scm_url

    Your SCM URL

    sectigo_log_level

    The log level. The supported values are INFO and DEBUG. The default value is INFO.

    sectigo_logger_size_mb

    The maximum size (in megabytes) of a log file. The default value is 1.

    sectigo_logger_count

    The maximum number of log files. The default value is 10.

    sectigo_sleep_download

    The time (in seconds) between an enrollment request and an attempt to dowload the provisioned certificate files.

    sectigo_encrypt_credentials

    Whether the credentials will be encrypted. The default value is False.

    sectigo_gnu_key

    The GPG key for encrypting the credentials

    An example configuration file.

    sectigo_log_file : "sectigo_pycert.log"
    sectigo_log_path : "/opt/sectigo/paloaltowf/logs"
    cert_profile_path : "/opt/sectigo/paloaltowf/profiles_sample"
    sectigo_scm_url : "https://murray.enroll.demo.sectigo.com/api/v1"
    sectigo_log_level : debug
    sectigo_log_size_mb : 1
    Sectigo_logger_count : 10
    sectigo_sleep_download : 1
    sectigo_encrypt_credentials : False
    sectigo_gnu_key : "02C5433F6789F1390EBA00C4316B3F25AD25DBE0"
  • Credentials file: Configure the sectigo_credentials.yaml file. The sample sectigo_credentials.yaml file is located in the profiles_sample directory.

    The following table describes parameters in the file.

    Parameter Description

    <SCMDV>

    An arbitrary label (credential ID). This label is referenced in the scm_credential_detail parameter in a certificate profile file. You can have multiple client ID and secret pairs, each with their own label.

    sectigo_cm_user_id

    The client ID of the SCM user

    sectigo_cm_user_secret

    The client secret of the SCM user

    An example credentials file.

    SCMDV:
        sectigo_cm_user_id      : "b8923830-11f5-4c34-951b-fc1235634972"
        sectigo_cm_user_secret  : "Ti]hXzuxj.!T,zg!S0rZ0StbwyDlhCP4"

Palo Alto Firewall requirements

  • Palo Alto firewall: The integration supports Palo Alto VM-Series firewalls and was tested with VM-Series PAN-OS 10.0.9 in an AWS environment

  • Palo Alto API: See Enable API Access for instructions.

  • Firewall profile: Configure a Palo Alto firewall profile. This profile specifies the target firewall to which a certificate will be attached. The sample fw_paloalto_config.yaml file is located in the profiles_sample directory. You can have as many firewall profile files as you want, just make sure that all filenames start with fw_.

    The following table describes parameters in the file.

    Parameter Description

    paloalto_url

    The FQDN or IP address of the firewall instance

    paloalto_api_key

    The API key for authenticating API calls to Palo Alto. See Get Your API Key for instructions on generating an API key.

    paloalto_commit_description

    An arbitrary description for a commit of configuration changes

    paloalto_commit_user

    The user that will commit changes. You may create a separate user on Palo Alto specifically for API operations.

    An example firewall profile.

    paloalto_url : "https://my_paloalto_instance.com/"
    paloalto_api_key : "gJlQWE56987nBxIqyfa62sZeRtYuIo2BgzEA9UOnlZBhU=="
    paloalto_commit_description : "Sectigo Palo Alto commit"
    paloalto_commit_user : "admin"

Installation instructions

  1. Log in to your Linux client machine as a user with administrator privileges.

  2. Create a new directory called sectigo somewhere on your machine and place the integration package in the newly created directory. The following commands assume that the package is located in opt/sectigo.

  3. Navigate to /opt/sectigo and execute the following commands (you don’t need to install the unzip utility if you already have it).

    • DEB

    • RPM

    sudo apt-get update
    sudo apt-update install unzip
    unzip Sectigo_PaloAltofw_Agent_<version>.zip -d /opt/sectigo
    sudo yum update
    sudo yum install unzip
    unzip Sectigo_PaloAltofw_Agent_<version>.zip -d /opt/sectigo
  4. Navigate to Sectigo_PaloAltofw_Agent_<version>/paloaltofw and install the Python dependencies listed in the requirements.txt file.

    • System Python

    • Virtual environment

    pip3 install -r requirements.txt
    python3 -m venv .venv
    source .venv/bin/activate
    pip3 install -r requirements.txt

Using the agent

Encrypt the credentials

Encrypting the SCM secret and Palo Alto API key is an optional but recommended step to protect your credentials from unauthorized access.

To encrypt the values:

  1. Change the value of the sectigo_encrypt_credentials parameter in the config.yaml file to True.

  2. Create a private key.

    • Unattended key generation

    • Attended key generation

    gpg --batch --passphrase '' --quick-gen-key <user_id> default default

    The --quick-generate-key option requires you to specify the <user_id> field on the command line and optionally an algorithm, usage, and expire date. Default values are used for all other options.

    gpg --full-generate-key

    The --generate-key option prompts for the real name and email fields before asking for a confirmation to proceed, and provides a dialog for all options.

  3. Retrieve the key fingerprint.

    gpg -list-keys
    GPG key fingerprint
  4. Add the fingerprint to the sectigo_gnu_key parameter in config.yaml.

  5. Encrypt the credentials.

    • All certificate profiles

    • Specific certificate profile

    python3 paloaltoagent.py -a encrypt
    python3 paloaltoagent.py -a encrypt -p <certificate>.yaml

Edit the credentials file

If you need to edit the ecrypted file, first decrypt it.

python3 paloaltoagent.py -a decrypt -p <certificate>.yaml

Enroll a certificate

You can enroll for a specific certificate profile.

python3 paloaltoagent.py -a enroll -p <certificate>.yaml

To view the provisioned certificate in Palo Alto firewall, navigate to the Device tab, and then select Certificate Management  Certificates.

Certificates in Palo Alto Firewall

Renew a certificate

You can renew for a specific certificate profile or for all certificate profiles available in the profile’s path.

  • All certificate profiles

  • Specific certificate profile

python3 paloaltoagent.py -a renew
python3 paloaltoagent.py -a renew -p <certificate>.yaml

Enable auto-renewal

You can create a cronjob that will invoke the script on a schedule (see crontab for cron schedule expressions) to check the certificate expiry status:

  1. Run crontab -e on the terminal.

  2. Add a cronjob that will trigger the script. The following example will trigger paloaltoagent.py every week.

    • All certificate profiles

    • Specific certificate profile

    0 0 * * 7 python3 /opt/sectigo/paloaltowf/paloaltoagent.py -a renew
    0 0 * * 7 python3 /opt/sectigo/paloaltowf/paloaltoagent.py -a renew -p <certificate>.yaml
  3. Save the changes and exit.