Signing packages
Sign activity and automation packages with your organization's certificate and configure Studio, the Orchestrator and Robots to trust it.
VeloPhex uses one signing format for every package: activity packages, workflow automation packages and Python automation packages. A signature is a detached file, velophex/signature.json, stored inside the package next to the manifest. It signs the package identity together with the manifest hash, so a valid signature cannot be moved onto a different package.
How trust works#
| Package | Rule |
|---|---|
VeloPhex packages (VeloPhex.*, Velophex.*) |
Must be signed by the VeloPhex certificate built into Studio, the Robot and the Orchestrator. An unsigned or differently signed package with a reserved name is refused. |
| Your packages | Signing is optional by default. |
| Any package with a signature | The signature is always verified. A broken or tampered signature is always refused, whatever the policy. |
Signers are trusted by pin, not by certificate authority: either the certificate's SHA-256 thumbprint, or an spki-sha256: pin of its public key. Signatures use RSASSA-PSS with SHA-512 or ECDSA with SHA-512. The current signature format (format 2) signs the signing time (signedAt), and verifiers check the certificate as of that time, so a signature stays valid after the certificate expires. Every verifier fails closed.
Prerequisites#
- A code-signing certificate and private key for your organization, as a PKCS#12 file (
.pfxor.p12) or, for Studio, in the current user's Windows certificate store. - The certificate's SHA-256 thumbprint.
- Administrator access to the Orchestrator deployment configuration and to the Robots, to pin the signer.
Sign packages#
StudioPythonWorkflow projects. Choose the signing certificate (from the certificate store or a PKCS#12 file) in Studio's publishing settings, and turn on Require signing so that Publish refuses a package it could not sign. See Publish to Orchestrator.
Activity packages. The pack-author build (VeloPhex.ActivityPackage.Build) does not sign packages. To use an unsigned activity package, add the feed that holds it in Studio's Package Manager > Settings and mark that source as trusted. If you do sign activity packages, sign once, before first distribution: signing changes the package hash that project lock files pin.
Sign while packing (signing needs the cryptography package in the project environment; see Package and publish Python automations):
$env:VELOPHEX_SIGNING_PASSWORD = "<password>"
uv run velophex pack --sign C:\keys\automation-signing.pfx
The CLI prints Pin this signer as SHA-256 <thumbprint>. Use that value when you configure trust below. It warns when the certificate is expired or not yet valid, because every verifier would refuse the signature.
Trust your signer#
Configure the pin everywhere packages are checked, and turn on the requirement last. If you require signatures before the pin is in place, every job is refused until it lands.
1. Pin the signer on the Orchestrator#
Set your thumbprint in the deployment's .env and recreate the api container:
VELOPHEX_ORG_SIGNER_THUMBPRINT=<sha256-thumbprint>
BashCopydocker compose -f docker-compose.core.yml up -d api
Packages signed by that certificate are then shown as trusted.
2. Pin the signer on every Robot#
At install time:
PowerShellCopymsiexec /i VeloPhex.Desktop-<version>-win-x64.msi /qn TRUSTEDSIGNERS=<sha256-thumbprint>
On an installed Robot, from an elevated prompt:
PowerShellCopy& "$env:ProgramFiles\VeloPhex\Robot\VeloPhex.Robot.Service.exe" configure --trusted-signers <sha256-thumbprint>
Separate several thumbprints with commas, for example during a certificate rotation. An empty value (--trusted-signers "") clears the list. A running service picks up the change without a restart.
3. Require signatures (optional)#
When every package you run is signed and every Robot has the pin:
PowerShellCopy& "$env:ProgramFiles\VeloPhex\Robot\VeloPhex.Robot.Service.exe" configure --require-signed true
or REQUIRESIGNED=1 at install time (the default is 0). A Robot with this setting refuses any automation package that is not signed by a trusted signer.
On the Orchestrator, the equivalent setting is Packages__RequireSignedPackages in the api service's environment in docker-compose.core.yml (shipped as "false").
Verify#
- Publish a signed package. In the Orchestrator, open the package version. You should see it reported as signed by a trusted signer.
- On a Robot, run
VeloPhex.Robot.Service.exe statusand check the service log at start-up. The Robot logs its trust posture every time it starts. With the requirement on, you should no longer see the line saying unsigned automation packages are accepted. - Start a job from the signed package. It should run normally.
Rotate a signing certificate#
- Get the new certificate and its thumbprint.
- Add the new thumbprint next to the old one on every Robot (
--trusted-signers old,new) and in the Orchestrator configuration. - Start signing new packages with the new certificate.
- Remove the old thumbprint only when no package you still run depends on it. Because format 2 signatures carry their signing time, existing packages stay valid after the old certificate expires as long as its pin is still trusted.
Next steps#
How trust works
Prerequisites
Sign packages
Trust your signer
1. Pin the signer on the Orchestrator
2. Pin the signer on every Robot
3. Require signatures (optional)
Verify
Rotate a signing certificate
Next steps