Understanding CodeSign Protect Projects and Environments in Trust Protection Platform

The Venafi CodeSign Protect solution is based around code signing projects. While there is flexibility around how your organization chooses to use projects, in general, code signing projects are an embodiment of a general code signing need. Projects can include multiple code signing certificates, each of which can be used for a different purpose, even though those keys might be used by the same people.

EXAMPLE  You may have a product that has a need to be signed at multiple stages during the product lifecycle. Development builds might be signed with a self-signed certificate, whereas release builds might be signed with a CA-issued certificate. Both of these signing needs could be included in the same project.

Another example might be signing different parts of your product with different keys.

Anyone who can login to Aperture can create a new Project if they have access to at least one environment template. New project requests are sent to the Code Signing Administrator for approval or rejection. If rejected, the project reverts to the draft state to allow the requestor to make any changes as requested by the administrator before re-submitting for approval.

The requester of the code signing project becomes the Owner.

Each code signing project is comprised of the following:

  • Environments
  • Users & Approvers

Environments

Environments are the containers for the keys and certificates associated with the project. Projects can contain as many environments as necessary, and each environment can be configured to generate a new key or to use a key that already exists.

In CodeSign Protect, environments are divided into two broad categories:

  • Single environments
  • Per-user environments

Single environments contain just one code signing certificate, GPG key, or .NET strong-naming key, depending on the environment type. These are ideal environments for housing the keys used to sign code binaries, RPM packages, or for strong-naming your .NET assemblies, for example. The keys and certificates in these environments tend to be more applicable to an organization or company, as opposed to individual users.

Per-user environments can contain multiple user-based certificates or GPG keys. The templates for these environments typically contain macros to allow for differentiation between the certificates or keys that are issued under the environment. These environments are ideal for issuing many certificates or keys to users in your organization for things like macro signing or signing git commits.

The way that Trust Protection Platform handles the keys and certificates associated with any environment is determined by how the certificate or key was created. The following private key sources are available for Code Signing Environments:

  • Create a new key and have Trust Protection Platform handle the certificate life cycle

    • Once the Project is approved, the private key is generated by Trust Protection Platform and kept in the key storage location selected in the Environment
    • Trust Protection Platform will issue a new certificate through the Certificate Authority set on the Environment
    • The Certificate object is place in Enrollment mode
    • Signing operations are serviced by the selected encryption device for the private key
    • Available to Master Admins, Code Signing Administrators, and Owners
  • Import an existing PKCS#12 certificate and private key bundle

    • The key already exists
    • The certificate and private key are imported into the Trust Protection Platform Secret Store
    • The Certificate object is placed into Monitoring mode
    • Signing operations are serviced by the Venafi software encryption driver
    • Available to Master Admins, Code Signing Administrators, and Owners
    • This method is not available for per-user environments
  • Import an existing GPG private key

    • The key already exists
    • The private key is imported into the Trust Protection Platform Secret Store, which can be done from the CodeSign Protect GPG client
    • Signing operations are serviced by the Venafi software encryption driver
    • This method is only available for per-user GPG environments
  • Reference an existing key in an HSM and upload a certificate

    • The key already exists in the HSM
    • The certificate is imported into the Trust Protection Platform Secret Store
    • The Certificate object is placed into Monitoring mode
    • Signing operations are serviced by the HSM
    • Can be configured only by Master Admins and Code Signing Administrators
    • This method is not available for per-user environments
  • Reference an existing key in an HSM and have Trust Protection Platform handle the certificate life cycle

    • The key already exists in the HSM
    • Trust Protection Platform will reference the private and public keys, and will issue a new certificate via the selected Certificate Authority
    • The Certificate object is placed into Enrollment mode
    • The Certificate object is set to "re-use private key"
    • Signing operations are serviced by the HSM
    • Can be configured only by Master Admins and Code Signing Administrators
    • This method is not available for per-user environments

Project environments are based on Environment Templates, which are configured by the Code Signing Administrator. The environment template selection will restrict what options can be configured when setting up project environments. For information about configuring Environment Templates, see Create Environment Templates. For more information about setting up Projects and Environments, see Working with CodeSign Protect Projects.

Rules & Restrictions

Rules and restrictions allow Project Owners to set options to define conditions that must be met before a signing can occur.

At the project level, the Owner can specify which code signing applications are permitted to be used for this project. The overall list of code signing applications is maintained by the Code Signing Administrator. If this field is left blank, any code signing application can be used.

At the environment level, the Owner can specify which IP addresses or IP address range are permitted (or allow all by not specifying any addresses). When a Key User signs in from an IP address that is permitted, the associated code signing certificate is installed in the user's certificate store. If that same user signs in from an IP address that isn't allowed, the certificate is removed.

Users & Approvers

Each code signing project has specific users that are assigned to fulfill specific roles when this project is invoked. The users assigned to each role are defined on the Users & Approvers page. Both users and groups can be assigned to roles.

The Code Signing Administrator has the ability to set the following optional restrictions:

  • Role members must be groups. If this option is set, the Owner is able to assign only groups to roles, not individual users.

    NOTE  This option eliminates having to maintain and update projects directly due to employee turnover. Access is instead handled through regular IT maintenance of groups.

  • Key Users may not have other roles in the same project. This option prohibits any Key User from being able to have any other role in the project. If a key user has another role (either through direct user assignment or group membership) and this option is enabled, that user will not be able to sign using keys managed by this project.

    This option should typically be checked as measure to prevent users with an administrative role in the project from giving themselves rights to use signing keys.

    NOTE  User roles in the project are checked when the key is used, not when the project is created or edited. The reason for this is that group membership is dynamic, which means that the only reliable time to validate user roles is at the time of key use.

To get started creating projects, see Working with CodeSign Protect Projects.