GPG Environment

Follow the steps below to complete setting up a GPG Environment.

NOTE  As you proceed through these steps, note that some of the fields may not be editable, and some fields may not appear at all. This is based on the Environment Type you selected and the Environment Template settings that your Code Signing Administrator has established.

  1. If this Environment will be used as an issuer for other GPG Environments, click the Issuer for other GPG Environments checkbox.

    Per-User Environments can't be set up as issuer Environments.

    The GPG issuer feature works similar to the way a certificate chain works. If an Environment has this box checked, then it can be used as an issuer, which is similar to a root or intermediate certificate.

    With this checked, other GPG Environments can use this Environment as their issuer. If trust is established with this issuer Environment, then anything issued from it will also be trusted.

    Any environment that has that checked can be used as an issuer for another environment, but can't be used to sign directly.

    Chains can be as long as they need to be.

    EXAMPLE  One common use case is having an issuer Environment used with a per-user Environment. In this case, you enable Issuer for other GPG Environments, then create a separate per-user environment and pick the issuer Environment as it's issuer (see the next step). Then, each user of that per-user Environment will automatically get the issuer marked as trusted, which means they will automatically trust any signature from another user of that per-user Environment.

  2. If this Environment should use another GPG Environment as its issuer, select the issuing Environment from the Issuer GPG Environment drop-down.

    DID YOU KNOW?  The Issuer for other GPG Environments and the Issuer GPG Environment options are not mutually exclusive. A single GPG Environment can have an Issuer GPG Environment and also be an issuer for other GPG Environments.

  3. Select a Signing Flow to use for this Environment. The Flow you select will be invoked when the keys associated with this Environment are used.

    This field is removed from GPG Environments designated as Issuer Environments since these Environments can't be used for signing.

  4. Select a Key Storage Location, which is where the private key will be stored. Selecting Software stores the key in the Trust Protection Platform Secret Store.

    Other options, such as HSMs, may be available based on key storage locations configured by your Code Signing Administrator. If you plan to import an existing key currently stored on an HSM, select the HSM that stores that key.

  5. In Creation Type, choose whether you want to Create new key, Import existing key, or Use existing key in HSM. Follow the remaining steps in the sections below based on your selection.

    If you're setting up a Per-User Environment, follow the steps in Create new key.

    IMPORTANT  Two Environments may not use the same certificate or private key. Make sure that each certificate or private key is assigned to only one CodeSign Protect Environment.

    Complete the fields using the following guidelines:

    Field Guidelines
    Real Name

    Real name of the person using the GPG key. Together with the E-mail address, this becomes part of the user ID (UID). The user ID is used to associate the key with a real person and is used to identify the key when signing.

    For per-user Environments, this field supports macros.
    Email Address

    E-mail address of the person using the GPG key. Together with the Real Name, this becomes part of the user ID (UID). The user ID is used to associate the key with a real person and is used to identify the key when signing.

    For per-user Environments, this field support macros.
    Validity Period

    Number of days until the key expires. A value of zero (0) means the key will not expire.

    Signing Key Algorithm

    		 Select the encryption algorithm for the GPG signing key.
    Encryption Key Algorithm Select the encryption algorithm for the GPG encryption key.
    Authentication Key Algorithm Select the encryption algorithm for the GPG authentication key.

    Click Create Environment.

    NOTE  These steps outline what you need to do to add an existing key to a single key GPG environment, such as for signing RPM packages. To import user-based GPG keys, follow the steps in Create New Key above, and then refer to Configuring GPG clients with per user Environments.

    Step 1: Prepare GPG Key for Import

    GPG keys must be prepared for import in order to complete this procedure. Follow these steps to prepare your key:

    1. Remove the passphrase from your gpg secret key.

      If a gpg secret key has a passphrase set then it will be exported as an encrypted secret key using that passphrase. An encrypted secret key cannot be converted to a format that can be imported by CodeSign Protect.

      $ gpg --passwd <uid>

      This command will ask you to enter the current passphrase to unlock the key and will then ask you for a new passphrase. Press enter to remove the passphrase. When prompted select Yes, protection is not needed.

      If your key contains subkeys then you will be prompted once for each.

      This process can be repeated after exporting in order to restore the original passphrase if desired.

    2. Export your gpg secret key

      $ gpg --export-secret-key <uid> > <filename>.pgp

      This will write the contents of your key to the specified filename.

    3. Convert your gpg into an SSH2 key file.

      1. Download and build pgpdump, with the Venafi modifications:

        $ wget https://github.com/Venafi/pgpdump/archive/master.zip

        $ unzip master.zip

        $ cd pgpdump-master

        $ ./configure && make

      2. Run the tool with the -e option to perform the conversion:

        ./pgpdump -e <filename>.pgp

      3. The export writes files named secret-key.x, where x is the key number. In most cases secret-key.0 is the signing key and secret-key.2 is the encryption key if an encryption subkey was present.

    The keys are now ready for import.

    Step 2: Complete the Environment configuration fields

    Complete the fields according to the following guidelines.

    NOTE  The Key Storage Location for imported keys will be Software. Importing existing keys to an HSM is not supported.

    Field Guidelines
    Real Name

    Real name of the person using the GPG key. Together with the E-mail address, this becomes part of the user ID (UID). The user ID is used to associate the key with a real person and is used to identify the key when signing.
    Email Address

    E-mail address of the person using the GPG key. Together with the Real Name, this becomes part of the user ID (UID). The user ID is used to associate the key with a real person and is used to identify the key when signing.
    Validity Period

    Number of days until the key expires. A value of zero (0) means the key will not expire.

    Step 3: Import Existing Keys

    NOTE  Be sure to complete Step 1: Prepare GPG Key for Import before uploading existing keys.

    In the Signing Key, Authentication Key, and Encryption Key fields, select the keys that were exported in Step 1: Prepare GPG Key for Import.

    Click Create Environment.

    Once this Project is approved, the original keys should be available to those who have the Key User role for this project.

    Complete the fields using the following guidelines.

    It may take a few minutes for CodeSign Protect to retrieve available keys from your HSM. You'll see a status wheel while it's communicating with the HSM, and once the keys are retrieved, they'll be available from the drop-down menus.

    Field Guidelines
    Real Name

    Real name of the person using the GPG key. Together with the E-mail address, this becomes part of the user ID (UID). The user ID is used to associate the key with a real person and is used to identify the key when signing.

    For per-user Environments, this field supports macros.
    Email Address

    E-mail address of the person using the GPG key. Together with the Real Name, this becomes part of the user ID (UID). The user ID is used to associate the key with a real person and is used to identify the key when signing.

    For per-user Environments, this field support macros.
    Validity Period

    Number of days until the key expires. A value of zero (0) means the key will not expire.

    Signing Private Key

    Select the signing private GPG key to associate with this environment.

    Signing Public Key

    Select the signing public key that corresponds with the signing private key. This drop-down pre-populates based on your selection in the Signing Private Key drop-down.

    Encryption Private Key

    (Optional) Select the encryption private GPG key to associate with this environment.

    Encryption Public Key

    (Optional) Select the encryption public key that corresponds with the encryption private key. This drop-down pre-populates based on your selection in the Encryption Private Key drop-down.

    Authentication Private Key

    (Optional) Select the authentication private GPG key to associate with this environment.

    Authentication Public Key

    (Optional) Select the authentication public key that corresponds with the authentication private key. This drop-down pre-populates based on your selection in the Encryption Private Key drop-down.

    After you finish creating the Environment, you'll be able to see the HSM Key Label by opening the Project, selecting the Environment, and then clicking the Instances tab on the Environment properties.

    NOTE  The HSM Key Label is shown for single key Environments only.

What's Next

If you need additional Environments as part of this Project, you can create those now. A Project can have as many Environments as needed, and the Environments can be any type.

If you're done creating Environments, you can submit your Project for approval.