Cryptography Module Mule 4 - Part 1 (PGP Encryption/Decryption)

Mule 4 has a Cryptography module which includes PGP, XML, and JCE. In this article, we will see the PGP technique — a cryptographic way that allows secure communication between two entities using public and private keys.

GitHub repository with the Mule project can be found at the end of the post.

Mule 4 has a Cryptography module which includes these 3 different strategies:

In this article, we will see the PGP technique.

PGP

Pretty Good Privacy (PGP) is a cryptographic way that allows secure communication between two entities. It uses the public and private key concepts to encrypt the data as shown in the below diagram.

PGP diagram: A encrypts a message with B's public key and B decrypts it with the private key

Prerequisites

1. Install the Crypto Module from Exchange, located in the Mule palette.

Note

Here is the reference documentation on how to install new modules to your Mule Project: Adding Modules to Your Project.

Mule Palette Crypto module listing PGP, JCE, and XML operations like Pgp encrypt and Pgp decrypt

2. Create private and public keys

Please follow the below steps to generate a public/private key pair:

Download and install the GnuPG from this link.
Install Kleopatra to use a Graphical User Interface (GUI).
To generate the keys, click on “New Key Pair” and follow the instructions on the screen.

Kleopatra welcome screen with New Key Pair and Import buttons for managing PGP keys

Once the keys are generated, export them to the file system.

Kleopatra context menu noting Export gives the public key and Export Secret Keys the private key

The generated files are of ASC format, which is not supported by Mule yet, so we need to dearmor the keys first. Run the following command: ./gpg --dearmor <PATH_TO_YOUR_ASC_FILE> for each of the keys. This command will create new files alongside the ASC files that will have .gpg appended to their filename which are supported in Mule.

File listing with private.asc and public.asc next to their dearmored .gpg versions

This is what you will get after following the previous steps:

Public/Private keys
Fingerprint
Passphrase
KeyId

Mule Code Implementation

We will limit our scope to PGP encrypt/decrypt operation in this article.

Global configurations

Create 2 global configurations:

Encryption – Configure public key, keyId, and fingerprint.
Decryption – Configure private key, keyId, and fingerprint.

**For projects: you should have these 2 configurations in different projects and all fields should be read from property files. The passphrase should be treated as a secure property.

Usage

1. Encryption/Decryption of entire payload

Encryption:

**To log or use payload in the next processor, convert the encrypted stream to a base64 data type.

Output:

Postman POST to /encrypt returning a PGP-encrypted payload as a base64 string

Decryption:

Mule XML for the decryption flow converting the base64 payload to a stream and running Pgp decrypt

Output:

Postman POST to /decrypt returning the original JSON payload with name, city, and email

2. Encryption/Decryption at field level

This is a very common non-functional requirement where sensitive fields should be encrypted.

For this, we can still reuse the pgp-encryption-flow and pgp-decryption-flow flows. The only change would be the way we refer to these flows from the main flow, and for that, the DataWeave lookup function is very useful.

Encryption:

**Used lookup function to invoke the pgp-encryption-flow.

Output:

Postman POST to /encrypt returning JSON where only the EMAIL field is PGP-encrypted

Decryption:

Mule XML using a DataWeave decrypt function with lookup to decrypt only the email field

Output:

Postman POST to /decrypt returning JSON with the email field decrypted back to its original value

Conclusion

So far we learned Mule code implementation for PGP. You can set this Mule code as a common service that will help to achieve the encryption/decryption non-functional requirement in many APIs.

Here are the 2 ways to set up this Mule code as a common service:

Externalize the flow and publish it on the Anypoint Exchange.
Create a common API, which will encrypt/decrypt the payload.

References

GitHub repository

ProstDev GitHub - Demo PGP

FAQs

Frequently asked questions about this post.

What strategies does the Mule 4 Cryptography module include?

The Cryptography module includes three different strategies: PGP, XML, and JCE. This article covers the PGP technique, a cryptographic way that allows secure communication between two entities using public and private keys.

Why do I need to dearmor the PGP keys before using them in Mule?

The keys generated and exported from Kleopatra are in ASC format, which is not supported by Mule yet, so you need to dearmor them first. Run ./gpg --dearmor <PATH_TO_YOUR_ASC_FILE> for each key, which creates new files alongside the ASC files with .gpg appended to their filename that are supported in Mule.

What do I configure in the encryption and decryption global configurations?

Create two global configurations: an Encryption config where you configure the public key, keyId, and fingerprint, and a Decryption config where you configure the private key, keyId, and fingerprint.

How do I encrypt only a specific field instead of the entire payload?

You can reuse the same pgp-encryption-flow and pgp-decryption-flow flows for field-level encryption; the only change is the way you refer to these flows from the main flow, and for that the DataWeave lookup function is very useful, letting you encrypt or decrypt just a sensitive field such as the email.

How can I reuse this PGP code as a common service across many APIs?

There are two ways to set up this Mule code as a common service: externalize the flow and publish it on the Anypoint Exchange, or create a common API that will encrypt and decrypt the payload, which helps achieve the encryption/decryption non-functional requirement in many APIs.

Why convert the encrypted output to a base64 data type?

To log or use the payload in the next processor, you convert the encrypted stream to a base64 data type, which is why the encryption output is returned as a base64 string.