Cryptography (PGP) Module Reference¶ The Cryptography Module adds in-line OpenPGP (RFC 9580 / RFC 4880) message-level cryptography to WSO2 Integrator: MI mediation flows. It is built on Bouncy Castle, so its output is standard OpenPGP and interoperates with GnuPG and any other compliant tool. Keys are supplied through connections — one per key — that operations reference by config key. There are two connection types: PGP_PRIVATE_KEY — Sender identity. Used to sign and decrypt. PGP_PUBLIC_KEY — Recipient's key. Used to encrypt (to them) and verify (their signature). The module provides six operations: Operation Description Key connection used pgpEncrypt Encrypt the input for a recipient using their public key. encryptionConfigKey → PGP_PUBLIC_KEY pgpDecrypt Decrypt the input using recipient's private key. decryptionConfigKey → PGP_PRIVATE_KEY pgpSign Sign the input with sender's private key. signingConfigKey → PGP_PRIVATE_KEY pgpVerify Verify a signed message with the sender's public key. verificationConfigKey → PGP_PUBLIC_KEY pgpSignAndEncrypt Sign then encrypt in a single pass (outbound). signingConfigKey + encryptionConfigKey pgpDecryptAndVerify Decrypt then verify in a single pass (inbound). decryptionConfigKey + verificationConfigKey Every operation takes its input (Input Source) in one of two ways — the core concept to understand before reading the parameter tables: Message Body (default) — operate on the raw message payload. This is the natural fit for file and binary exchange. Expression — read the input from a variable or field via sourceContent (for example ${payload.message}). Connections¶ A connection points the module at a single PGP key and is reused across any number of operations. In the VS Code tooling you create keys while configuring an operation. On an operation's key field click Add New Key, choose PGP Private Key or PGP Public Key, then fill in the key details. On disk it is a local entry (cryptography.init). Key material sources¶ The privateKeyPath / publicKeyPath field accepts several sources. Use a project resource (resources:) for public keys; keep private keys in a protected secret source such as env:NAME or the Secure Vault. FormSourceUse for resources:keys/bob-public.ascProject resource, bundled in the integration project.Public keys env:NAMEEnvironment variable holding the (armored) key material.Recommended for private keys — containers / Kubernetes Secrets. /path/to/key.ascFilesystem path.On-box files (For both public and private keys). -----BEGIN PGP…Key text pasted inline (armored).Quick tests Note gov:/ and conf:/ are the legacy registry syntax — still supported for backward compatibility, but new integrations should use resources: (public keys) or env: / Secure Vault (private keys). Public vs private keys — where each goes¶ Handle the two kinds of key differently, because only one is a secret. Public key (a partner's key — not secret): safe to bundle with the project. Put the .asc file in the project under resources/keys/. In a PGP Public Key connection, set: publicKeyPath → resources:keys/partner-public.asc keyIdentifier → the owner's email (e.g. [email protected]) Private key (your key — secret): keep it out of the project. Store the key material in an environment variable / mounted secret, and the passphrase in Secure Vault. In a PGP Private Key connection, set: privateKeyPath → env:MY_PRIVATE_KEY passphrase → {${wso2-vault('pgp_my_passphrase')}} keyIdentifier → your email (e.g. [email protected]) Warning Never put a private key under resources: — it gets packaged and committed. Only public keys belong there. PGP_PRIVATE_KEY¶ Your identity — used by pgpSign, pgpDecrypt, pgpSignAndEncrypt (signing side) and pgpDecryptAndVerify (decryption side). FieldParameterRequiredNotes Connection NamenameYesUnique name referenced by operations (as the config key). Private Key LocationprivateKeyPathYesSecret key location. Keep private keys out of project resources — use env:NAME or the Secure Vault, not resources:. See key material sources. Key IdentifierkeyIdentifierNoWhich key to use: fingerprint (40-hex), 16-hex Key ID (0x…), or exact user ID / email. Optional if the key ring holds a single key. PassphrasepassphraseNoProtects the secret key. Use a Secure Vault reference such as {${wso2-vault('pgp_alice_passphrase')}}, not a literal. Leave blank for an unprotected key. <localEntry key="my-private" xmlns="http://ws.apache.org/ns/synapse"> <cryptography.init> <connectionType>PGP_PRIVATE_KEY</connectionType> <privateKeyPath>env:ALICE_PRIVATE_KEY</privateKeyPath> <keyIdentifier>[email protected]</keyIdentifier> <passphrase>{${wso2-vault('pgp_alice_passphrase')}}</passphrase> <name>my-private</name> </cryptography.init> </localEntry> PGP_PUBLIC_KEY¶ A party's key — used by pgpEncrypt, pgpVerify, pgpSignAndEncrypt (encryption side) and pgpDecryptAndVerify (verification side). It has no passphrase. FieldParameterRequiredNotes Connection NamenameYesUnique name referenced by operations (as the config key). Public Key LocationpublicKeyPathYesPublic key location — see key material sources. Key IdentifierkeyIdentifierNoWhich key to use: fingerprint / 16-hex Key ID / exact email or user ID. Required for encryption only when the ring holds multiple keys. <localEntry key="partner-public" xmlns="http://ws.apache.org/ns/synapse"> <cryptography.init> <connectionType>PGP_PUBLIC_KEY</connectionType> <publicKeyPath>resources:keys/partner.asc</publicKeyPath> <keyIdentifier>[email protected]</keyIdentifier> <name>partner-public</name> </cryptography.init> </localEntry> Shared behavior model¶ Every operation shares the same way of receiving input and emitting output. NameParameterValueDescription Input Source inputSource Message Body (default), Expression Where the input comes from. Message Body operates on the raw message payload; Expression reads it from sourceContent. Source Content sourceContent e.g. ${payload.message} The expression to read when inputSource is Expression. Input Type inputType BINARY (default), TEXT How to read the input — outbound operations only (pgpEncrypt, pgpSign, pgpSignAndEncrypt). BINARY is raw bytes; TEXT is a charset-decoded string. Drives the OpenPGP literal-data format byte. Charset charset Default: UTF-8 Charset used when inputType / outputType is TEXT. ASCII Armor armor false (default), true Outbound only. false yields binary output (.gpg); true yields ASCII-armored, text-safe output (.asc). Output Type outputType BINARY (default), TEXT Decrypt / verify only, in Advanced. How the recovered output is represented. BINARY (default) reproduces the recovered bytes exactly, so it round-trips any payload — documents, archives, images, as well as text — losslessly. It is the default because this module's primary job is protecting files, and it keeps the inbound side consistent with the binary-first outbound defaults (inputType=BINARY, armor=false); a TEXT default would charset-decode the output and silently corrupt non-text files. Choose TEXT when the payload really is text you want as a string (e.g. for logging or a text/JSON response). BINARY is surfaced as base64 in the response variable. Response Variable responseVariable Name of the variable the output is assigned to, at ${vars.<name>.payload}. Binary results are base64; armored/text results are a string. Overwrite Body overwriteBody true, false (default) true → the result replaces the message body; false → the result goes to the response variable only. Decrypt / verify auto-detect their input pgpDecrypt, pgpVerify and pgpDecryptAndVerify accept either armored or binary input and detect the format automatically — there is no inputType on the inbound side. outputType controls only how the recovered output is represented; it defaults to BINARY (lossless for any file) and can be set to TEXT in Advanced for text payloads. Because of this, a receiving flow needs almost no configuration, and it reads the output of any OpenPGP tool (GnuPG included). Signature verdict pgpVerify and pgpDecryptAndVerify place a boolean signatureValid field on the response variable's attributes. Branch on it with a Filter mediator, e.g. ${vars.<responseVariable>.attributes.signatureValid}. Protect private-key passphrases Private-key passphrases must never be hard-coded. Store the value in the Secure Vault and give the connection a Secure Vault reference to it, e.g. {${wso2-vault('pgp_alice_passphrase')}}. The module receives the already-decrypted value and never persists it. Key selection Which key to use is fixed on the connection via keyIdentifier (a fingerprint, 0x-prefixed 16-hex Key ID, or exact user ID / email). When it is blank, the module uses the single key in the ring (encryption additionally requires a keyIdentifier when the ring holds more than one key). pgpEncrypt¶ Encrypts the input for a recipient using their public key. Uses the standard hybrid scheme: a one-time symmetric session key is generated per message and wrapped with the recipient's public key. Operation details¶ GroupNameParameterValueDescription GeneralInput TypeinputTypeBINARY (default), TEXTHow to read the input. CharsetcharsetUTF-8Shown when inputType is TEXT. Input SourceinputSourceMessage Body (default), ExpressionWhere the input comes from. Source ContentsourceContente.g. ${payload}Shown when inputSource is Expression. Recipient KeyEncryption Config KeyencryptionConfigKeya PGP_PUBLIC_KEY connection (required)The recipient's public-key connection. Encryption OptionsSymmetric Key AlgorithmsymmetricKeyAlgorithmAES_256 (default), AES_192, AES_128, CAMELLIA_256, CAMELLIA_192, CAMELLIA_128, TWOFISH, CAST5, TRIPLE_DES, BLOWFISH, IDEACipher for the one-time session key. Compression AlgorithmcompressionAlgorithmZLIB (default), ZIP, BZIP2, UNCOMPRESSEDCompression applied before encryption. ASCII Armorarmorfalse (default), trueBinary .gpg vs armored .asc. Integrity CheckintegrityChecktrue (default), falseAdd an integrity-protection (MDC) packet. File NamefileNameoptionalFile name embedded in the literal-data packet. OutputResponse VariableresponseVariablerequiredVariable the output is assigned to. Overwrite BodyoverwriteBodyfalse (default), trueWrite the result to the message body. Sample configuration¶ <cryptography.pgpEncrypt> <encryptionConfigKey>partner-public</encryptionConfigKey> <symmetricKeyAlgorithm>AES_256</symmetricKeyAlgorithm> <compressionAlgorithm>ZLIB</compressionAlgorithm> <armor>false</armor> <integrityCheck>true</integrityCheck> <responseVariable>enc</responseVariable> <overwriteBody>true</overwriteBody> </cryptography.pgpEncrypt> pgpDecrypt¶ Decrypts the input using your private key. Input format (armored or binary) is auto-detected. Operation details¶ GroupNameParameterValueDescription GeneralInput SourceinputSourceMessage Body (default), ExpressionWhere the input comes from. Source ContentsourceContente.g. ${payload}Shown when inputSource is Expression. Decryption Config KeydecryptionConfigKeya PGP_PRIVATE_KEY connection (required)Your private-key connection. Require IntegrityrequireIntegritytrue (default), falseReject the message if it lacks integrity protection (MDC). AdvancedOutput TypeoutputTypeBINARY (default), TEXTHow the recovered output is represented; BINARY round-trips any file losslessly. Set TEXT for a readable string. CharsetcharsetUTF-8Shown when outputType is TEXT. OutputResponse VariableresponseVariablerequiredVariable the output is assigned to. Overwrite BodyoverwriteBodyfalse (default), trueWrite the result to the message body. Result attributes: fileName, modificationTime (embedded metadata, surfaced when present). Sample configuration¶ <cryptography.pgpDecrypt> <decryptionConfigKey>my-private</decryptionConfigKey> <requireIntegrity>true</requireIntegrity> <responseVariable>dec</responseVariable> <overwriteBody>true</overwriteBody> </cryptography.pgpDecrypt> pgpSign¶ Signs the input with your private key, producing a one-pass signed OpenPGP message. Operation details¶ GroupNameParameterValueDescription GeneralInput TypeinputTypeBINARY (default), TEXTHow to read the input. CharsetcharsetUTF-8Shown when inputType is TEXT. Input SourceinputSourceMessage Body (default), ExpressionWhere the input comes from. Source ContentsourceContente.g. ${payload}Shown when inputSource is Expression. Signing KeySigning Config KeysigningConfigKeya PGP_PRIVATE_KEY connection (required)Your private-key connection. Signing OptionsSignature Hash AlgorithmsignatureHashAlgorithmSHA256 (default), SHA384, SHA512, SHA224, SHA1, RIPEMD160Hash used for the signature. Compression AlgorithmcompressionAlgorithmZLIB (default), ZIP, BZIP2, UNCOMPRESSEDCompression applied to the signed message. ASCII Armorarmorfalse (default), trueBinary vs armored output. File NamefileNameoptionalFile name embedded in the literal-data packet. OutputResponse VariableresponseVariablerequiredVariable the output is assigned to. Overwrite BodyoverwriteBodyfalse (default), trueWrite the result to the message body. Sample configuration¶ <cryptography.pgpSign> <signingConfigKey>my-private</signingConfigKey> <signatureHashAlgorithm>SHA256</signatureHashAlgorithm> <compressionAlgorithm>ZLIB</compressionAlgorithm> <armor>false</armor> <responseVariable>sig</responseVariable> <overwriteBody>true</overwriteBody> </cryptography.pgpSign> pgpVerify¶ Verifies a signed message with the sender's public key and exposes the verdict. Input format is auto-detected. Operation details¶ GroupNameParameterValueDescription GeneralInput SourceinputSourceMessage Body (default), ExpressionWhere the input comes from. Source ContentsourceContente.g. ${payload}Shown when inputSource is Expression. Verification Config KeyverificationConfigKeya PGP_PUBLIC_KEY connection (required)The sender's public-key connection. Require Valid Signer KeyrequireValidSignerKeytrue (default), falseReject the message if the signer's key is unusable (revoked/expired) or untrusted. AdvancedOutput TypeoutputTypeBINARY (default), TEXTHow the recovered output is represented; BINARY round-trips any file losslessly. Set TEXT for a readable string. CharsetcharsetUTF-8Shown when outputType is TEXT. OutputResponse VariableresponseVariablerequiredVariable the output is assigned to. Overwrite BodyoverwriteBodyfalse (default), trueWrite the result to the message body. Result attributes: signatureValid (boolean), fileName, modificationTime. Sample configuration¶ <cryptography.pgpVerify> <verificationConfigKey>partner-public</verificationConfigKey> <requireValidSignerKey>true</requireValidSignerKey> <responseVariable>ver</responseVariable> <overwriteBody>false</overwriteBody> </cryptography.pgpVerify> <filter xpath="${vars.ver.attributes.signatureValid}"> <then> <!-- signature valid: continue processing ${vars.ver.payload} --> </then> <else> <log category="WARN"><property name="msg" value="REJECTED: bad PGP signature"/></log> <drop/> </else> </filter> pgpSignAndEncrypt¶ Signs then encrypts in a single pass. The output is a single standard OpenPGP message (encrypt-of-compress-of-one-pass-sign) that GnuPG and peer tools read natively — it is not the two single operations chained. Operation details¶ GroupNameParameterValueDescription GeneralInput TypeinputTypeBINARY (default), TEXTHow to read the input. CharsetcharsetUTF-8Shown when inputType is TEXT. Input SourceinputSourceMessage Body (default), ExpressionWhere the input comes from. Source ContentsourceContente.g. ${payload}Shown when inputSource is Expression. Signing Key (yours)Signing Config KeysigningConfigKeya PGP_PRIVATE_KEY connection (required)Your private-key connection, used to sign. Recipient KeyEncryption Config KeyencryptionConfigKeya PGP_PUBLIC_KEY connection (required)The recipient's public-key connection, used to encrypt. Algorithm OptionsSymmetric Key AlgorithmsymmetricKeyAlgorithmAES_256 (default), AES_192, AES_128, CAMELLIA_256, CAMELLIA_192, CAMELLIA_128, TWOFISH, CAST5, TRIPLE_DES, BLOWFISH, IDEACipher for the one-time session key. Compression AlgorithmcompressionAlgorithmZLIB (default), ZIP, BZIP2, UNCOMPRESSEDCompression applied before encryption. Signature Hash AlgorithmsignatureHashAlgorithmSHA256 (default), SHA384, SHA512, SHA224, SHA1, RIPEMD160Hash used for the signature. ASCII Armorarmorfalse (default), trueBinary vs armored output. Integrity CheckintegrityChecktrue (default), falseAdd an integrity-protection (MDC) packet. File NamefileNameoptionalFile name embedded in the literal-data packet. OutputResponse VariableresponseVariablerequiredVariable the output is assigned to. Overwrite BodyoverwriteBodyfalse (default), trueWrite the result to the message body. Sample configuration¶ <cryptography.pgpSignAndEncrypt> <signingConfigKey>my-private</signingConfigKey> <encryptionConfigKey>partner-public</encryptionConfigKey> <symmetricKeyAlgorithm>AES_256</symmetricKeyAlgorithm> <compressionAlgorithm>ZLIB</compressionAlgorithm> <signatureHashAlgorithm>SHA256</signatureHashAlgorithm> <armor>false</armor> <integrityCheck>true</integrityCheck> <responseVariable>enc</responseVariable> <overwriteBody>true</overwriteBody> </cryptography.pgpSignAndEncrypt> pgpDecryptAndVerify¶ Decrypts then verifies in a single pass and exposes the verdict. Input format is auto-detected. Operation details¶ GroupNameParameterValueDescription GeneralInput SourceinputSourceMessage Body (default), ExpressionWhere the input comes from. Source ContentsourceContente.g. ${payload}Shown when inputSource is Expression. Decryption Key (yours)decryptionConfigKeya PGP_PRIVATE_KEY connection (required)Your private-key connection, used to decrypt. Verification Config KeyverificationConfigKeya PGP_PUBLIC_KEY connection (required)The sender's public-key connection, used to verify. Require Integrity / Valid SignerrequireIntegrity / requireValidSignerKeytrue (default), falseReject on missing integrity protection, or on an unusable/untrusted signer key. AdvancedOutput TypeoutputTypeBINARY (default), TEXTHow the recovered output is represented; BINARY round-trips any file losslessly. Set TEXT for a readable string. CharsetcharsetUTF-8Shown when outputType is TEXT. OutputResponse VariableresponseVariablerequiredVariable the output is assigned to. Overwrite BodyoverwriteBodyfalse (default), trueWrite the result to the message body. Result attributes: signatureValid (boolean), fileName, modificationTime. Sample configuration¶ <cryptography.pgpDecryptAndVerify> <decryptionConfigKey>my-private</decryptionConfigKey> <verificationConfigKey>partner-public</verificationConfigKey> <requireIntegrity>true</requireIntegrity> <requireValidSignerKey>true</requireValidSignerKey> <responseVariable>dec</responseVariable> <overwriteBody>false</overwriteBody> </cryptography.pgpDecryptAndVerify> <filter xpath="${vars.dec.attributes.signatureValid}"> <then> <property name="payload" expression="${vars.dec.payload}" scope="default"/> <!-- signature valid: continue processing --> </then> <else> <log category="WARN"><property name="msg" value="REJECTED: bad PGP signature"/></log> <drop/> </else> </filter> Error codes¶ When an operation fails it raises one of the following error codes (available on the message context for a fault sequence to branch on). CodeNameMeaning 701301INVALID_INPUTThe input payload/content is missing or malformed. 701302INVALID_CONFIGURATIONThe operation or connection is misconfigured. 701303KEY_NOT_FOUNDNo key matched the keyIdentifier (or the ring is empty). 701304KEY_LOAD_ERRORThe key file could not be read or parsed. 701305INVALID_PASSPHRASEThe passphrase for the private key is wrong. 701306INVALID_MESSAGE_FORMATThe input is not a valid OpenPGP message. 701307INTEGRITY_CHECK_FAILEDThe integrity-protection (MDC) check failed — the message was altered. 701308INTEGRITY_PROTECTION_MISSINGIntegrity protection was required (requireIntegrity=true) but absent. 701309OPERATION_ERRORThe cryptographic operation failed. 701310GENERAL_ERRORAn unclassified error. 701320KEY_UNUSABLEThe key is revoked or expired. 701321SIGNER_KEY_UNTRUSTEDThe signer's key is untrusted and requireValidSignerKey=true.