Breadcrumbs

Set up OpenPGP Signer

The OpenPGP Signer signs arbitrary data and produces an OpenPGP detached signature in binary or ASCII armored form, or a cleartext signature. For more information on the OpenPGP format, refer to RFC 4880.

After setting up the OpenPGP Signer, see the following guides for signing:

To download a sample configuration file for this worker, see Sample Worker Configurations.

Prerequisite: Configure a Crypto Worker

As with all Signers, the OpenPGP Signer requires a Crypto Worker (software keystore or PKCS#11) to be available before setup. If you already have one configured, skip to Step 1.

To set up a Crypto Worker using the sample software keystore:

  1. Select the Admin Web Workers tab, and click Add.

  2. Click From Template, select keystore-crypto.properties in the list, and click Next.

  3. In the configuration text view, update WORKERGENID1.KEYSTOREPATH to match your SignServer installation. For example: WORKERGENID1.KEYSTOREPATH=/home/username/signserver/res/test/dss10/dss10_keystore.p12. 

  4. Click Apply.

Note the Crypto Worker name (for example, CryptoTokenP12) to use in Step 1.

OpenPGP Signer Configuration Properties

The following lists the relevant configuration properties when configuring OpenPGP Signer:

Property

Description

DETACHEDSIGNATURE

Required. Whether to produce a detached signature (true) or a clear-text signature (false).

DIGEST_ALGORITHM

(Optional) OpenPGP Hash Algorithm to use with the signature. Possible values are numeric or textual OpenPGP Hash Algorithms, for example SHA256 or 10.

Default: SHA256.

RESPONSE_FORMAT

(Optional) Response format: BINARY or ARMORED.

Default: ARMORED.

Clear-text signatures (DETACHEDSIGNATURE=false) only support ARMORED.

For all available properties, refer to OpenPGP Signer.

Step 1 - Add OpenPGP Signer

  1. Select the Admin Web Workers tab, and click Add to add a new Worker.

  2. Select From Template.

  3. Choose openpgpsigner.properties in the list, and click Next.

  4. Update the configuration properties as needed:

    • NAME: Set a descriptive Worker name.

    • CRYPTOTOKEN: set this to match your Crypto Token:

      • SignServer Enterprise: use the name of the Crypto Token configured during Installation.

      • Appliance: the token was created automatically and is named HSMCryptoToken10.

      • SignServer Cloud: a CryptoTokenP12 is provided with sample keys and certificates. Skip the key generation step below and verify the Worker is in an Active state.

    • AUTHTYPE: If using a live system, configure this so that the Worker cannot be accessed without authentication.

    • DEFAULTKEY: Set to an existing key alias, or do this in a later step.

    • DETACHEDSIGNATURE, DIGEST_ALGORITHM, RESPONSE_FORMAT: Configure as needed. For descriptions of all OpenPGP Signer-specific properties, see OpenPGP Signer.

  5. Click Apply. The Worker appears in the All Workers list.

  6. To generate a new key pair, click the Status Summary tab and then Renew Key.

  7. Select a Key Algorithm, such as RSA, and a Key Specification such as 2048, and click Generate.

  8. Select the Worker, and confirm the Worker status is Active and without errors.

Worker Offline?

If the status is Offline with a "No key available for purpose" error, the DEFAULTKEY property does not point to an existing key. Confirm that the DEFAULTKEY property is correct and check in the Crypto Token tab of the Crypto Worker that a key with the specified name exists. If this is unsuccessful, generate a new key:

  1. Click Renew key and specify the following:

    • Key Algorithm: For example, RSA or ECDSA.

    • Key Specification: For example, 2048 (RSA) or prime256v1 (ECDSA).

    • New Key Alias: Set to match the DEFAULTKEY property (typically change to the same value as the Old Key Alias).

  2. Click Generate.

  3. Reselect the Worker and confirm the status is now Active with no errors.

Step 2 - Add User ID and Certification

This step associates a User ID with the OpenPGP public key, using the Generate CSR option:

  1. On the Admin Web Workers tab, select the OpenPGP Worker.

  2. Click Generate CSR, and specify:

    • Signature Algorithm: For example, SHA256withRSA or SHA256withECDSA. The OpenPGP Signer also accepts an OpenPGP Hash Algorithm directly.

    • DN: Enter the User ID, for example: Signer001 (Code Signing) <signer001@example.com>

  3. Click Generate, and then Download.

  4. Open the downloaded file using any text editor and copy the content.

  5. Select the Worker, and click the Configuration tab.

  6. Click Edit next to the PGPPUBLICKEY property.

  7. Paste the public key content into the Value field, and click Submit.

  8. Click Status Summary and confirm that PGP Key ID, PGP Public key, and User ID are all listed.

Step 3 - Generate and Store Revocation Certificate

A revocation certificate lets authorized personnel invalidate the public key if it is ever compromised. Generate one and store it securely.

The GENERATE_REVOCATION_CERTIFICATE property must be temporarily set to true to generate the certificate, then set back to false afterward so that normal signing requests do not produce revocation certificates.

  1. On the Configuration tab, click Edit next to the GENERATE_REVOCATION_CERTIFICATE property.

  2. Set the value to true, and click Submit.

  3. Click Generate CSR and specify:

    • Signature Algorithm: For example, SHA256withRSA or SHA256withECDSA. The OpenPGP Signer also accepts an OpenPGP Hash Algorithm directly.

    • DN: Any value as this field is not used when generating a revocation certificate.

  4. Click Generate, and then Download.

  5. Store the downloaded revocation certificate in a secure location accessible to authorized personnel.

  6. Return to the Configuration tab, and click Edit next to the GENERATE_REVOCATION_CERTIFICATE property.

  7. Set value back to false, and click Submit.

Step 4 - Test Signing

The following example shows how to sign using the SignServer Client Web, but you can use any SignServer client interface.

  1. Click Client Web.

  2. Under File Upload, specify the Worker name used, for example, OpenPGPSigner.

  3. Select the file you want to sign, for example, release.zip.

  4. Click Submit and save the resulting detached signature file, for example, release.zip.asc.

Step 5 - Verify Signature

Use any OpenPGP-compatible tool to verify the signature. The following example uses GnuPG:

If the public key of the Signer is not yet in your GnuPG keyring, import it first:

  1. Save the public key (from the PGPPUBLICKEY property) as signer001-pub.asc.

  2. Import the key:

$ gpg --import signer001-pub.asc

Then verify the signature:

$ gpg --verify release.zip.asc release.zip

Step 6 - (Optional) Distribute the OpenPGP Public Key

The OpenPGP Public Key can be published to online key servers or distributed to clients by other means.