Skip to content
Xferity

Tutorial: Secure PGP File Delivery

Tutorial: Secure PGP File Delivery

Section titled “Tutorial: Secure PGP File Delivery”

This tutorial shows how to add OpenPGP encryption or decryption to an SFTP flow so that file payloads are cryptographically protected in transit and at rest before delivery.

Prerequisites: a working SFTP flow (see Your First SFTP Transfer)

Scenario: Uploading encrypted files to a partner

Section titled “Scenario: Uploading encrypted files to a partner”

Your partner requires files to be PGP-encrypted with their public key before upload.

Step 1: Obtain the partner’s public key

Section titled “Step 1: Obtain the partner’s public key”

Get the partner’s PGP public key (.asc file) and save it:

Terminal window
mkdir -p ./keys/partner-a
cp partner-a-public.asc ./keys/partner-a/public.asc

Verify the fingerprint with the partner. Never use a public key without verifying its fingerprint.

Step 2: Configure PGP in the flow

Section titled “Step 2: Configure PGP in the flow”

Update flows/partner-a-upload.yaml:

flows:
  partner-a-upload:
    direction: upload
    enabled: true
    target:
      partner: partner-a-sftp
      path: /incoming
    local:
      path: ./storage/partner-a/outgoing
    files:
      - pattern: "*.csv"
    pgp:
      provider: gopenpgp
      encrypt: true
      public_key_path: file:./keys/partner-a/public.asc
    idempotency_mode: hash
    delete_after_upload: true
    delete_encrypted_after_upload: true

delete_encrypted_after_upload: true removes the encrypted intermediate file after the upload succeeds. Without this, the .gpg file stays in the staging area.

Step 3: Validate configuration

Section titled “Step 3: Validate configuration”
Terminal window
xferity validate
xferity diag partner-a-upload

Diagnostics will confirm the key file is readable and the partner endpoint is reachable.

Step 4: Run manually and confirm

Section titled “Step 4: Run manually and confirm”
Terminal window
xferity run partner-a-upload

Confirm in logs that files were encrypted before upload. The audit trace will show encrypt: true in the event metadata.

Scenario: Decrypting files downloaded from a partner

Section titled “Scenario: Decrypting files downloaded from a partner”

Your partner sends PGP-encrypted files to their SFTP. You need to decrypt them after download.

Configure decryption in the flow

Section titled “Configure decryption in the flow”
flows:
  partner-b-inbound:
    direction: download
    enabled: true
    source:
      partner: partner-b-sftp
      path: /outgoing
    local:
      path: ./storage/partner-b/incoming
    files:
      - pattern: "*.pgp"
    pgp:
      provider: gopenpgp
      decrypt: true
      private_key_path: file:./keys/our-private.asc
      passphrase: env:OUR_PGP_PASSPHRASE
    idempotency_mode: hash
    delete_encrypted_after_decrypt: true

delete_encrypted_after_decrypt: true removes the downloaded .pgp file after successful decryption. The plaintext file remains in the destination path.

Using the auto provider for enterprise key structures

Section titled “Using the auto provider for enterprise key structures”

If the partner uses an enterprise key structure that the native provider cannot handle, switch to auto mode:

pgp:
  provider: auto
  gnupg_binary: /usr/bin/gpg
  decrypt: true
  private_key_path: file:./keys/our-private.asc
  passphrase: env:OUR_PGP_PASSPHRASE

auto mode tries the native Go provider first. If it fails with a classified compatibility error (compat_enterprise_key_structure), it falls back to GnuPG once.

Ensure GnuPG is installed and the path is correct before relying on auto mode.

Checking crypto results in logs

Section titled “Checking crypto results in logs”

After a run with PGP configured, look for these structured fields in logs:

  • provider — which provider handled the operation
  • fallback_used — whether GnuPG fallback was triggered
  • fallback_reason — why fallback was triggered
Section titled “Related pages”