Handling Multiple PGP Subkeys in MuleSoft Without the Headache

The Setup: You’ve Got PGP Working… Until You Don’t

You’ve configured PGP encryption or decryption in your MuleSoft flow. You imported the key, dropped in the fingerprint, configured the passphrase, deployed, and it worked.

Then one day, while trying to decrypt a file, it doesn’t. Or worse, it works for one file but silently fails for another.

Sound familiar? You’re likely hitting one of PGP’s most misunderstood concepts: subkeys, and more specifically, what happens when a PGP certificate has more than one subkey, each with its own fingerprint.

This article walks you through what subkeys are, why MuleSoft cares about which fingerprint you use, and the exact steps to identify and use the right one.

Quick PGP Vocabulary

Before We Dive In: Key PGP Terms

Let’s quickly level-set on a few important terms:

• PGP Key / Certificate: The complete bundle containing one master key and one or more subkeys.
• Public vs Private Certificate / Key: The public key is used for encryption, while the private key is used for decryption.
• Master Key (Primary Key): The main key used for signing and certifying. It has its own unique fingerprint.
• Subkey: A secondary key within the same certificate, typically used for encryption or signing. Each subkey also has its own fingerprint.
• Fingerprint: A 40-character hexadecimal string that uniquely identifies a key or subkey. (Version 4 Keys)

A single .asc or .gpg file can contain one master key and multiple subkeys, and each of them has a unique fingerprint.

Why MuleSoft Needs the Right Fingerprint:

How MuleSoft Uses PGP Fingerprints

MuleSoft’s Cryptography Module uses the fingerprint you provide to look up the exact key material inside your keyring file.

If your PGP certificate contains multiple subkeys — for example, one for encryption and another for signing, providing the wrong fingerprint, or not providing all the required fingerprints, can lead to issues.

You might see errors like:

Could not find key with fingerprint: ABCD1234...

The core rule:** The fingerprint you provide must match the specific subkey** intended for that operation (encryption vs. signing), not just any fingerprint from the certificate. Additionally, all relevant subkey fingerprints present in the certificate should be properly configured to ensure correct processing.

Real-World Scenario: The Two-Fingerprint Problem

Here’s what this looks like in practice.

When you open a PGP certificate in Kleopatra (a popular PGP key manager) and navigate to the Subkeys tab, you’ll typically see multiple entries listed — each representing a different subkey associated with the certificate.

What You Actually See in a Real Certificate

In a real certificate, the Subkeys tab reveals multiple entries — typically one primary key and one or more subkeys.

For example:

• Primary Key Fingerprint: 7B80 9871 D766 E468 BC09 6A6A 85B4 CD44 9972 84EB
• Subkey Fingerprint: 515C 31B7 7341 8A98 08B4 C8A0 4F8B 1AF1 CB03A5A3

Notice something important:

The fingerprint shown at the top of the certificate (7B80 9871...) matches the primary key. The second fingerprint (515C 31B7...) belongs to the subkey.

Both keys are valid. Both have identical usage flags and validity periods.

And this is exactly where confusion starts — which fingerprint should you use in MuleSoft?

The answer (from practical experience): In scenarios where multiple subkeys are present, all subkey fingerprints, along with the primary key fingerprint, should be configured. Relying only on the primary key fingerprint can cause the module to fail in locating or using the correct key material for encryption and decryption.

Configuring the Fingerprint in MuleSoft

The Error You’ll See If You Get It Wrong

If you configure only the primary key fingerprint (7B809871D766E468…) and miss the subkey fingerprint (515C31B773418A98…), MuleSoft will throw an error at runtime indicating that it cannot locate the required key for the operation.

Notice the key ID in the error message — 4F8B1AF1CB03A5A3. This corresponds to the last 16 characters of the subkey fingerprint:

515C31B773418A98 08B4 C8A0 **4F8B 1AF1 CB03 A5A3**

What MuleSoft is effectively telling you is this: it tried to resolve the passphrase for that specific subkey, but couldn’t find it — because only the primary key was configured.

This is one of the most common causes of PGP decryption failures in MuleSoft, and it typically happens due to a missing subkey entry in the configuration.

The Fix: Register Both Fingerprints in Your Crypto PGP Config

In Anypoint Studio, open your Crypto PGP global configuration

You should configure three entries in the key list:

The working configuration: FFB_ENCRYPT uses the primary key fingerprint (no passphrase is needed for encryption with a public key), while FFB_DECRYPT and FFB_DECRYPT2 have passphrases configured — one for each fingerprint present in the certificate.

Why two DECRYPT entries?:

When MuleSoft attempts to decrypt an incoming file, it inspects the encrypted message to determine which key was used for encryption.

If the sender used a subkey (for example, 515C31B7…), MuleSoft must have a corresponding entry (like FFB_DECRYPT2) configured with that subkey’s fingerprint, along with the correct passphrase, to successfully decrypt the message.

Without this, the operation fails and results in a CRYPTO:PASSPHRASE error.

Wrapping Up

PGP in MuleSoft trips up a lot of developers, not because it’s inherently hard, but because the multi-subkey scenario isn’t well documented. The key insight is simple: a PGP certificate is not a single key — it’s a bundle, and MuleSoft needs you to be precise about which key inside that bundle you intend to use.

Once you get comfortable with the idea that each subkey has its own fingerprint, PGP in MuleSoft starts to feel much simpler. You’ll spend less time chasing errors and more time actually getting things done.

Happy encrypting! 🔐