CodeSign Protect architecture

The CodeSign Protect solution consists of the following components:

• Trust Protection Platform server with CodeSign Protect enabled. Throughout this article, this is referred to as the CodeSign Protect server.
• Venafi 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 CodeSign Protect server to generate and store private code signing keys

All code signing private keys are stored in either the CodeSign Protect Secret Store or in an attached HSM.

Venafi Code Signing Clients

The Venafi Code Signing Clients link code signing workstations to the CodeSign Protect server, which stores and manages use of private code signing keys. The Venafi Code Signing Clients communicate with the CodeSign Protect server over a TLS-encrypted REST API. Venafi CodeSign Protect currently supports RSA, Elliptic Curve, and experimental post-quantum code signing keys. The following Code Signing Connectors 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 CodeSign Protect 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 CodeSign Protect Clients on signing workstations. For more information about using the clients, see the sections for PKCS#11, CSP, GPG, and Keychain Access.

Trust Protection Platform server

The CodeSign Protect server is the central orchestrator of the CodeSign Protect solution, and its job is to protect and govern the use of private code signing keys. All the keys are stored in either the CodeSign Protect Secret Store or on an HSM. The CodeSign Protect 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, CodeSign Protect 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 CodeSign Protect server over the vedauth endpoint. If the credentials are valid, the CodeSign Protect 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 CodeSign Protect server. When users sync their CodeSign Protect client with the CodeSign Protect 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 CodeSign Protect. After validating that the request is a permitted use of the key, CodeSign Protect manages the code signing and returns the signed artifacts to the CodeSign Protect client.

Hardware Security Module (HSM)

As an optional feature, CodeSign Protect 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 CodeSign Protect Secret Store. When a request is made to sign a hash with that key, CodeSign Protect forwards the request to the HSM. The signing occurs on the HSM, which then returns the signed hash to the CodeSign Protect server. In turn, the CodeSign Protect server returns the signed hash to the CSP.

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

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