Signing and Certificates

Purpose of signing and certificates

The signing and verification flow for an Agent package is:

• Build: The signing tool signs the package with a private key and writes the corresponding certificate information into the package.
• Install: The system verifies the signature with the public key in the certificate to ensure that the package has not been modified.
• Update: In addition to verifying the signature, the system compares the certificates of the old and new packages to prevent replacement with a package from another source.

Signing keys use a PKCS#12 keystore (normally with a .p12 extension). The file contains both the private key and certificate and is password-protected. All later versions of the same Agent must be signed with the same keystore and password, otherwise, updates will fail verification.

Without a custom certificate, generated Agents use a common debug certificate for development and debugging. For production releases, configure a dedicated certificate to distinguish the signing source.

Generate a certificate and keystore

Run the following commands on a computer with OpenSSL installed. This example uses a 4096-bit RSA private key and creates a self-signed certificate valid for 9125 days:

# Generate a private key
openssl genrsa -out agent.key 4096

# Generate a certificate request and enter the organization and name when prompted
openssl req -new -key agent.key -out agent.csr

# Generate a self-signed certificate with the private key
openssl x509 -req -days 9125 -in agent.csr -signkey agent.key -out agent.crt

# Export the private key and certificate as a PKCS#12 keystore
openssl pkcs12 -export -inkey agent.key -in agent.crt -out agent.p12 -name "agent"

# Inspect the keystore
openssl pkcs12 -info -in agent.p12 -noout

The commands generate:

File	Purpose
agent.key	Private key used for signing. It is included in agent.p12 and can be deleted after the keystore is verified.
agent.crt	Self-signed certificate containing the public key. It can be deleted after verification.
agent.csr	Certificate signing request used to generate the self-signed certificate. It can be deleted after verification.
agent.p12	Keystore containing the private key and certificate, used by the build tool.

When exporting the keystore, OpenSSL prompts for a password. This is the keystore_pass used in the build configuration.

After confirming that agent.p12 is valid, delete the intermediate files agent.key, agent.csr, and agent.crt, and retain only agent.p12 and its password. All subsequent builds require this keystore and password, so back them up and protect them carefully.

Configure build signing

Booster Studio supports signing configuration in build.toml starting with version 1.13. Store agent.p12 in a dedicated project directory, such as certs under the project root, and put its relative path in build.toml:

[sign]
keystore_path = "certs/agent.p12"
keystore_pass = "replace with the password set when generating the keystore"

keystore_path must be relative to the project root, which is the directory containing build.toml.

After configuration, build the Agent with Booster Studio. The build tool signs it automatically. You can then install or distribute the .agent package generated in the build directory.

Note:

1. Back up the keystore and password. Later versions must continue to use the same keystore.
2. Do not commit private keys, keystores, or configuration files containing real passwords to a public repository. Do not place them in directories such as res for distribution with the Agent.