Code Sign Manager architecture

The Code Sign Manager solution consists of the following components:

• Trust Protection Foundation server with Code Sign Manager enabled. Throughout this article, this is referred to as the Code Sign Manager server.
• Palo Alto Networks Code Signing clients, installed on the Windows, Linux, or macOS workstations from which code will be signed
• Optionally, a Hardware Security Module (HSM) connected to the Code Sign Manager server to generate and store private code signing keys

All code signing private keys are stored in either the Code Sign Manager Secret Store or in an attached HSM.

Palo Alto Networks Code Sign Clients

The Code Sign Clients link code signing workstations to the Code Sign Manager server, which stores and manages use of private code signing keys. The Code Sign Clients communicate with the Code Sign Manager server over a TLS-encrypted REST API. The following code signing clients are available:

• Windows: CSP/KSP, PKCS#11, and GPG clients
• Linux: PKCS#11 and GPG clients
• macOS: PKCS#11, Keychain Access, and GPG clients

During Code Signing Client configuration, you will provide the address of the Code Sign Manager server you want to connect to and whether you want an access grant for the current user, local machine, or both. These options are described in the next section.

For more information on installing the Code Signing Clients, see Install Code Sign Clients on signing workstations. For more information about using the clients, see the sections for PKCS#11, CSP, GPG, and Keychain Access.

Trust Protection Foundation server

The Code Sign Manager server is the central orchestrator of the Code Sign Manager solution, and its job is to protect and govern the use of private code signing keys. All the keys are stored in either the Code Sign Manager Secret Store or on an HSM. The Code Sign Manager server performs the following functions:

• Authenticates users
• Issues certificate signing requests for approved code signing projects
• Stores code signing certificates
• Stores and protects private code signing keys
• Receives code signing requests
• Enforces permitted uses of private code signing keys
• Manages code signing request flows
• Returns signed hash to the requesting workstation

To facilitate authentication and virtual HSM functions, Code Sign Manager uses these two endpoints:

Endpoint	Description
vedauth	The vedauth endpoint is used to authenticate the current user, local machine, or both. During Code Signing Client configuration, a username and password is passed to the Code Sign Manager server over the vedauth endpoint. If the credentials are valid, the Code Sign Manager server returns one or more grants, depending on options selected during installation. Current user grant Current user grants are valid only for the user who is signed in on the workstation when the grant was issued. The tokens are stored in the following locations: CSP on Windows: Registry in HKEY_CURRENT_USER\Software\Venafi\CSP PKCS#11 driver in Windows: Registry in HKEY_CURRENT_USER\Software\Venafi\libhsm PKCS#11 driver on Linux and macOS: The ~/.libhsmconfig configuration file. Local machine grant IMPORTANT  Local machine grants are an advanced option and are generally considered less secure than current user grants. Local machine grants are valid for the machine and are supported only for PKCS#11 and CSP. This grant may be useful if you want to sign code from a workstation without a user having to be signed in. Note the following permissions requirements: On Windows, you need administrative rights (read/write) to get a grant, refresh a grant, or change settings. Only read access is required to use the grant. On macOS and Linux, using machine grants for PKCS#11 requires granting read/write access to /etc/venafi for any user of the grant. The tokens for this grant are stored in the registry at the following locations: CSP: HKEY_LOCAL_MACHINE\SOFTWARE\Venafi\CSP PKCS#11 on Windows: HKEY_LOCAL_MACHINE\SOFTWARE\Venafi\pkcs11 PKCS#11 on macOS/Linux: /etc/venafi These tokens are stored in the user's registry or user's configuration file and are used for authentication from that point forward.
vedhsm	All code signing-related requests are sent to the vedhsm endpoint on the Code Sign Manager server. When users sync their Code Sign Manager client with the Code Sign Manager server, all available keys and certificates become available for the key user to sign with (within the restrictions set by the Code Signing Administrator). When a user issues a signing request, the hash, hashing algorithm, and certificate to use are sent to the vedhsm endpoint in Code Sign Manager. After validating that the request is a permitted use of the key, Code Sign Manager manages the code signing and returns the signed artifacts to the Code Sign Manager client.

Hardware Security Module (HSM)

As an optional feature, Code Sign Manager can sign code with keys that are generated and reside on a Hardware Security Module (HSM). When the private key is on the HSM, a reference to that key is stored in the Code Sign Manager Secret Store. When a request is made to sign a hash with that key, Code Sign Manager forwards the request to the HSM. The signing occurs on the HSM, which then returns the signed hash to the Code Sign Manager server. In turn, the Code Sign Manager server returns the signed hash to the CSP.

Using an HSM for code signing requires the use of a supported HSM and activation of Advanced Key Protect, which is a separately-licensed component.

For more information about HSM integration with Trust Protection Foundation, see Managing system encryption keys. For a list of supported HSMs, see Supported HSMs.