How to Setup PGP Integration

For development purposes, it's possible to set up PGP integration for a local Zammad instance. However, since the approach uses self-generated test keys, this is considered unsafe for production. You've been warned!

Configure PGP Integration

Navigate to the System > Integrations > PGP section in GUI, and turn on the toggle switch on top to activate the feature.

Note: In case your local gpg binary cannot be found or it's a wrong version, you may receive an error message on top. Please try to fix it before proceeding by either installing or updating your GnuPG installation.

Upload Sender Private Key

In the same screen, click on the Add Key button.

Paste the following text in the Paste Key box:

Enter zammad in Passphrase box.
Click on the Add button.

The test sender private key above was generated for the following sender email address: zammad@localhost. In case your sender address is different, please see below on how to re-generate it.

Upload Recipient Public Key

In the same screen, click again on the Add Key button.

Paste the following text in the Paste Key box:

Leave Passphrase box empty.
Click on the Add button.

The test recipient public key above was generated for the following customer email address: nicole.braun@zammad.org. In case your recipient address is different, please see below how to re-generate it.

Create a Test Email Ticket with Encrypted & Signed Content

Go to new ticket screen.
Switch to the Send Email article type.
Provide a Title.
Choose a Customer called Nicole Braun.
Provide some Text.
Choose Users for the Group.
Verify that both Encrypt and Sign toggle buttons are now active.
Click on the Create button.
Verify that the first article has a Security attribute in article metadata with PGP: Encrypted / Signed value.

Re-generate Test Keys

You will need a recent installation of gpg utility (GnuPG) for the following commands.

Generate Sender Key

Make a temporary GPG keyring for the following commands:
```
GNUPGHOME=$(mktemp -d)
export GNUPGHOME
```

On systems with GnuPG version higher than 2.3.0, please set the following configuration option before generating new keys, so they can be backwards compatible:

   echo "default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed" > "$GNUPGHOME/gpg.conf"

Generate the private key:

gpg --quick-generate-key "zammad@localhost" rsa4096 sign,encr 10y

Where zammad@localhost is the key UID, rsa4096 key algorithm, sign,encr key usage and 10y key expiration date relative to current time.

Provide the key passphrase when asked, confirm it and remember it for later.

Export the private key in armor-ASCII format:

gpg --output "zammad@localhost.asc" --armor --export-secret-key "zammad@localhost"

Where zammad@localhost.asc is the file output for the private key and zammad@localhost the key UID.

Provide the key passphrase when asked.

Clean up the temporary GPG keyring:
```
rm -rf $GNUPGHOME
unset GNUPGHOME
```

You can now upload your new test sender private key. Either upload the actual text file (zammad@localhost.asc) or paste its contents in the appropriate box. Remember that the private key export includes the public key information as well, there is no need to import them separately. Also, you will have to provide the passphrase for the private key during the upload to Zammad.

Generate Recipient Key

Make a temporary GPG keyring for the following commands:
```
GNUPGHOME=$(mktemp -d)
export GNUPGHOME
```

On systems with GnuPG version higher than 2.3.0, please set the following configuration option before generating new keys, so they can be backwards compatible:

   echo "default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed" > "$GNUPGHOME/gpg.conf"

Generate the private key:

gpg --quick-generate-key "Nicole Braun <nicole.braun@zammad.org>" rsa4096 sign,encr 10y

Where Nicole Braun <nicole.braun@zammad.org> is the key UID, rsa4096 key algorithm, sign,encr key usage and 10y key expiration date relative to current time.

Provide the key passphrase when asked and confirm it.

Export the public key in armor-ASCII format:

gpg --output "nicole.braun@zammad.org.pub.asc" --armor --export "Nicole Braun <nicole.braun@zammad.org>"

Where nicole.braun@zammad.org.pub.asc is the file output for the public key and Nicole Braun <nicole.braun@zammad.org> the key UID.

Clean up the temporary GPG keyring:
```
rm -rf $GNUPGHOME
unset GNUPGHOME
```

You can now upload your new test recipient public key. Either upload the actual text file (nicole.braun@zammad.org.pub.asc) or paste its content in the appropriate box. Note that in this case you should NOT upload the generated private key since the public key may be used only for encryption.

Other Useful GnuPG commands

List Keys in the GPG Keyring

gpg --list-keys

Show Info About a Keyfile

gpg --show-key path/to/keyfile.asc

With preferences included in the verbose mode:

gpg --list-options show-pref-verbose --show-key path/to/keyfile.asc

Delete a Private Key from the GPG Keyring

gpg --delete-secret-key zammad@localhost

Delete a Public Key from the GPG Keyring

gpg --delete-key zammad@localhost

how-to-setup-pgp-integration.md 11 KB History Raw