Managing private key agents

Updating private key agents

Update to a new agent version

  • Pre-2.0

  • Windows

  • Windows ( CLI )

  • Linux Self-Extracting

Due to incompatibility between private key agent version 2.0 and earlier versions, updating from earlier versions requires a new installation. To ensure a seamless transition to the new agent, we recommend the following steps:

  1. Back up your private keys.

  2. Uninstall the private key agent.

  3. Install the new private key agent.

  4. In SCM, navigate to the Private Key Agent page and verify that the agent is connected and showing the correct version.

  5. Restore your private keys.

Available for private key agent version 2.0 and later.

  1. Log in to SCM.

  2. From the left-hand menu, select About.

  3. In the Private Key Agent Version row, click the Download Private Key Agent icon, and select Windows.

  4. (Optional) If required, move the Sectigo_Pk_Agent.exe file to the install location of the existing private key agent.

  5. Right-click Sectigo_Pk_Agent.exe and click Install.

    The package automatically recognizes that there’s an existing version of the private key agent and initiates an update instead of a new install.

  6. Read the EULA, select I agree to the license terms and conditions, and click Install.

  7. Click Next.

  8. Read the EULA, select I accept the terms in the License Agreement, and click Next.

  9. Specify whether to keep or delete the existing files, and click Next.

  10. (Optional) Specify an installation location.

  11. Click Next, Install, Finish, and Close.

  12. In SCM, navigate to the Private Key Agent page and verify that the agent is connected and showing the correct version.

Available for private key agent version 2.0 and later.

  1. Open the Windows command prompt.

  2. In the command line, navigate to the download location of the bootstrap application.

    The bootstrap application will download the Windows Installer package files (MSI) from https://dist.sectigo.com as necessary. If you’re using an HTTP proxy, ensure that your OS proxy settings have been configured to allow access to https://dist.sectigo.com.

  3. Run the installer.

    .\Sectigo_Pk_Agent.exe

  4. Read the EULA, select I agree to the license terms and conditions, and click Install.

  5. Click Next.

  6. Read the EULA, select I accept the terms in the License Agreement, and click Next.

  7. (Optional) Specify an installation location.

  8. Click Next, Install, and Close.

  9. In SCM, navigate to the Private Key Agents page and verify that the agent is connected and showing the correct version.

Available for private key agent version 2.0 and later.

  1. Log in to SCM.

  2. From the left-hand menu, select About.

  3. In the Private Key Agent Version row, click the Download Private Key Agent icon, and select Linux Self-Extracting.

  4. (Optional) If required, move the sectigo-pk-agent.bin file to the install location of the existing private key agent.

  5. Give execute permission to the installer binary.

    chmod +x sectigo-pk-agent.bin

  6. Run the installer.

    sudo ./sectigo-pk-agent.bin -- --upgrade

  7. In SCM, navigate to the Private Key Agent page and verify that the agent is connected and showing the correct version.

Update proxy server details

  • Windows ( CLI )

  • Linux APT ( DEB )

  • Linux DNF ( RPM )

To update the proxy server information for your existing private key agent, do the following:

  1. In a terminal, navigate to the private key agent install location.

  2. Run the private key agent configuration utility.

    pkagent.exe config interactive

  3. Skip providing the installation token.

  4. Configure proxy settings.

    1. Specify whether you want to use proxy settings.

    2. Complete proxy configuration based on the information provided in the following table.

      Parameter Description

      Proxy URL

      The hostname or IP address and port number used by your proxy server.

      • Host only — host

      • Host and port — host:port

      Proxy User

      The username for accessing the proxy server, if configured to use credentials.

      Proxy Password

      The password for accessing the proxy server, if configured to use credentials.

  5. Skip changing the key storage provider.

  6. Restart the private key agent.

    sc stop SectigoPkAgent
    sc start SectigoPkAgent

To update the proxy server information for your existing private key agent, do the following:

  1. In a terminal, navigate to the private key agent install location.

  2. Run the private key agent configuration utility.

    sudo pkagent config interactive

  3. Skip providing the installation token.

  4. Configure proxy settings.

    1. Specify whether you want to use proxy settings.

    2. Complete proxy configuration based on the information provided in the following table.

      Parameter Description

      Proxy URL

      The hostname or IP address and port number used by your proxy server.

      • Host only — host

      • Host and port — host:port

      Proxy User

      The username for accessing the proxy server, if configured to use credentials.

      Proxy Password

      The password for accessing the proxy server, if configured to use credentials.

  5. Skip changing the key storage provider.

  6. Restart the private key agent service.

    • SysVinit Linux:

      sudo service sectigo-pk-agent restart

    • systemd Linux:

      sudo systemctl restart sectigo-pk-agent

To update the proxy server information for your existing private key agent, do the following:

  1. In a terminal, navigate to the private key agent install location.

  2. Run the private key agent configuration utility.

    sudo pkagent config interactive

  3. Skip providing the installation token.

  4. Configure proxy settings.

    1. Specify whether you want to use proxy settings.

    2. Complete proxy configuration based on the information provided in the following table.

      Parameter Description

      Proxy URL

      The hostname or IP address and port number used by your proxy server.

      • Host only — host

      • Host and port — host:port

      Proxy User

      The username for accessing the proxy server, if configured to use credentials.

      Proxy Password

      The password for accessing the proxy server, if configured to use credentials.

  5. Skip providing the installation token.

  6. Restart the private key agent service.

    • SysVinit Linux:

      sudo service sectigo-pk-agent restart

    • systemd Linux:

      sudo systemctl restart sectigo-pk-agent

Configure a local SSL certificate replacement

The private key agent hosts the SSL endpoint to download private key files using a fixed certificate included in the installer. Alternatively, you can configure the private key agent to utilize your own SSL certificate to secure the certificate download site. As long as the certificate remains valid, this will prevent any SSL warnings when downloading private keys.

  • Windows ( CLI )

  • Linux

  1. In a terminal, navigate to the private key agent install location.

  2. Update the private key agent configuration.

    pkagent.exe config --cert_path <pathToCertificate> --cert_file_password <certificatePassword>

    The command options are outlined in the following table.

    Option Description

    cert_path

    The path to the .p12, .jks, or .pem (CERTIFICATE block, and PRIVATE KEY or ENCRYPTED PRIVATE KEY) certificate to be used in securing private key agent certificate downloads.

    cert_file_password

    The password for the certificate.

  3. Restart the private key agent.

    sc stop SectigoPkAgent
    sc start SectigoPkAgent

  1. In a terminal, navigate to the private key agent install location.

  2. Update the private key agent configuration.

    sudo pkagent config --cert_path <pathToCertificate> --cert_file_password <certificatePassword>

    The command options are outlined in the following table.

    Option Description

    cert_path

    The path to the .p12, .jks, or .pem (CERTIFICATE block, and PRIVATE KEY or ENCRYPTED PRIVATE KEY) certificate to be used in securing private key agent certificate downloads.

    cert_file_password

    The password for the certificate.

  3. Restart the private key agent service.

    • SysVinit Linux:

      sudo service sectigo-pk-agent restart

    • systemd Linux:

      sudo systemctl restart sectigo-pk-agent

Update certificate download naming convention

You can update the agent’s file naming convention for certificate downloads.

  • Windows ( CLI )

  • Linux

  1. In a terminal, navigate to the private key agent install location.

  2. Update the agent’s file naming convention for certificate downloads.

    pkagent config --download_file_name <formatValue>

    The command format values are outlined in the following table.

    Value Description

    cert_{ID}.ext

    The file will be saved with the ID of the certificate.

    \{common name}.ext

    The file will be saved with the common name of the certificate.

    {subject}.ext

    The file will be saved with the subject of the certificate.

  3. Restart the private key agent.

    sc stop SectigoPkAgent
    sc start SectigoPkAgent

  1. In a terminal, navigate to the private key agent install location.

  2. Update the agent’s file naming convention for certificate downloads.

    pkagent config --download_file_name <formatValue>

    The command format values are outlined in the following table.

    Value Description

    cert_{ID}.ext

    The file will be saved with the ID of the certificate.

    \{common name}.ext

    The file will be saved with the common name of the certificate.

    {subject}.ext

    The file will be saved with the subject of the certificate.

  3. Restart the private key agent service.

    • SysVinit Linux:

      sudo service sectigo-pk-agent restart

    • systemd Linux:

      sudo systemctl restart sectigo-pk-agent

Uninstall a private key agent

  • Windows

  • Linux Self-Extracting

  • Linux APT ( DEB )

  • Linux DNF ( RPM )

  1. Navigate to Settings  Apps & features.

  2. Search for Sectigo Private Key Agent.

  3. Select the Sectigo Private Key Agent and click Uninstall.

  4. Click Uninstall.

  5. Click Uninstall.

  6. Click Close.

  7. (Optional) Delete the files and logs associated with the private key agent.

    1. Navigate to C:\ProgramData\Sectigo.

    2. Delete the PK Agent folder.

      This cannot be undone. When using Local key storage, you must back up or export your keys before deleting this file to prevent losing your private keys. Only delete this folder if you want to completely remove all files and logs related to the agent.

  1. Stop the private key agent service.

    sudo service sectigo-pk-agent stop

  2. Navigate to the /etc/init.d directory.

  3. Delete the sectigo-pk-agent directory.

  4. Delete the private key agent installation files.

    1. Navigate to the /opt directory.

    2. Delete the sectigo-pk-agent directory.

  5. (Optional) Delete the files and logs associated with the private key agent.

    1. Navigate to the /var/opt directory.

    2. Delete the sectigo-pk-agent directory.

      This cannot be undone. When using Local key storage, you must back up or export your keys before deleting this directory to prevent losing your private keys. Only delete this directory if you want to completely remove all files and logs related to the agent.

  1. Remove the private key agent.

    sudo apt remove sectigo-pk-agent

  2. (Optional) Delete the files and logs associated with the private key agent.

    1. Navigate to the /var/opt directory.

    2. Delete the sectigo-pk-agent directory.

      This cannot be undone. When using Local key storage, you must back up or export your keys before deleting this directory to prevent losing your private keys. Only delete this directory if you want to completely remove all files and logs related to the agent.

  1. Remove the private key agent.

    sudo dnf remove sectigo-pk-agent+

  2. (Optional) Delete the files and logs associated with the private key agent.

    1. Navigate to the /var/opt directory.

    2. Delete the sectigo-pk-agent directory.

      This cannot be undone. When using Local key storage, you must back up or export your keys before deleting this directory to prevent losing your private keys. Only delete this directory if you want to completely remove all files and logs related to the agent.

Private key agent service commands

  • Windows

  • Linux ( SysVinit )

  • Linux ( systemd )

Command Description

Start

Start a private key agent:

sc start SectigoPkAgent

Stop

Stop a private key agent:

sc stop SectigoPkAgent

Query

Query the status of a private key agent:

sc query SectigoPkAgent
Command Description

Start

Start a private key agent:

sudo service sectigo-pk-agent start

Stop

Stop a private key agent:

sudo service sectigo-pk-agent stop

Restart

Restart a private agent:

sudo service sectigo-pk-agent restart

Status

Query the status of a private key agent:

sudo service sectigo-pk-agent status
Command Description

Start

Start a private key agent:

sudo systemctl start sectigo-pk-agent

Stop

Stop a private key agent:

sudo systemctl stop sectigo-pk-agent

Restart

Restart a private key agent:

sudo systemctl restart sectigo-pk-agent

Status

Query the status of a private key agent:

sudo systemctl status sectigo-pk-agent