PGP Encrypter

Mule has the ability to encrypt a message payload, or part of a payload, using Pretty Good Privacy (PGP). PGP combines data compression and data encryption to secure messages. The compression reduces message transmission time between origin and destination. 

There are two scenarios that this document addresses:

• Using another party’s public key to encrypt a messages in a Mule application 
• Using one’s own set of private and public keys so as to accept, and decrypt messages in a Mule application

The sections below outline the steps involved in encrypting or decrypting messages using PGP in Mule.

Prerequisites

This document assumes that you are reasonably familiar with PGP encryption, and the concept of public and private keys. For more details on encryption in general, and PGP in particular, review the PGP 6.5.1 documentation or How PGP Works.

Encrypting

In the world of PGP encryption, the sender of a message must encrypt its contents using the receiver’s public key. Thus, where your Mule flow handles messages that it must encrypt with someone else’s public key, you need to add the receiver’s public key to your "key ring" in Mule. Essentially, Mule stores asks the user for the key ring file which the Message Encryption message processor accesses to encrypt the any part of your message before sending.

• Studio Visual Editor
• XML Editor or Standalone

1. Use a tool such as GPG Keychain Access to import the other party’s public key. Refer to section below for more details about using GPG to facilitate implementation of PGP encryption and decryption in Mule.
2. Using the same tool, export the public key, selecting binary as the output format. This produces a key ring file with a .gpg extension.
3. Ensure that the .gpg file is stored in a place that the Mule application can access it at runtime; record the filepath of the .gpg file (also known as your public key ring file).
4. In your Mule application, create a global Encryption element, specifying a name for the element; change the default value for the Default Encrypterto PGP_ENCRYPTER.
5. On the Pgp Encrypter tab, configure the fields according to the table below.
   

   Field	Value
   General Tab
   Name	Required - A unique name for the global element.
   Default Encrypter	PGP_ENCRYPTER
   Pgp Encrypter Tab
   Reference or expression	If selected, in the Pgp Encrypter Config Reference, use an expression to reference attributes you have defined elsewhere in the XML configuration of your applications, or to reference the configurations defined in a bean.
   Define attributes	If selected, enter values in the following field.
   Public Key Ring File Name	Enter the filepath of the public key ring. This binary "key ring" holds the message receiver’s public key. Read more about creating the public key ring above. Note that you do not enter the public key itself, only the location of the key ring file in which the public is stored.

6. Set an Encryption message processor in the flow in which you wish to encrypt data in the message payload.
7. Configure the message processor according the table below. 
   

   Field	Value
   Display Name	A unique name for your message processor.
   Config Reference	Required - Use the drop down to select the global Encryption element you created in the steps above.
   Operation	Required - Encrypter
   Input reference	Enter a Mule expression to define the part(s) of the message Mule should encrypt. If no value is entered, Mule encrypts the entire message payload.
   Select encrypter	Required - PGP_ENCRYPTER
   Reference or expression	If selected, in the Pgp Encrypter Reference, use an expression to reference attributes you have defined elsewhere in the XML configuration of your applications, or to reference the configurations defined in a bean.
   Define attributes	If selected, enter values in the following field.
   Principal	An alternative to using a clientID and secret to authenticate a client, define a username and password as the principal.

8. Click OK to save your PGP encrypter configuration.

Decrypting

In the world of PGP encryption, the receiver of a message must be prepared to use a private key to decrypt its contents which were encrypted with a public key. Therefore, the receiver of an encrypted message must first generate a set of PGP keys:

• A public key to distribute to those who use it to encrypt and send messages to you
• A private key to decrypt the messages you receive which were encrypted using the public key

Thus, where your Mule flow receives messages that it must decrypt using your own private key, you must complete the following steps:

1. Generate a set of keys.
2. Send the public key out to those who send you encrypted messages.
3. Set a message encryption processor in your Mule flow that uses the private key to decrypt messages it receives.  

Mule itself does not generate sets of keys, nor distribute public keys. Access theGenerating PGP Keys section below to learn more about key generation; otherwise, if you already have your keys, proceed to the instructions directly below to set up a message encryption processor in your Mule flow.

Generating PGP Keys

You can use a tool such as GPG Keychain Access to create a new set of keys in the application (see screenshot below) or from the command line, answering questions to customize and identify your keys (see code sample below). Best practice recommends using the same key size – 1536 bits or 2048 bits – in all your environments (development, QA and production). 

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

Aarons-MacBook-Air:~ aaron$ gpg --gen-key
gpg (GnuPG/MacGPG2) 2.0.19; Copyright (C) 2012 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Please select what kind of key you want:
   (1) RSA and RSA (default)
   (2) DSA and Elgamal
   (3) DSA (sign only)
   (4) RSA (sign only)
Your selection? 1
RSA keys may be between 1024 and 8192 bits long.
What keysize do you want? (2048) 2048
Requested keysize is 2048 bits      
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) <n=2>
invalid value             
Key is valid for? (0) 2
Key expires at Tue Aug 25 11:46:00 2015 PDT
Is this correct? (y/N) y
                         
GnuPG needs to construct a user ID to identify your key.
Real name: Aaron Somebody
Email address: aaron.somebody@mulesoft.com
Comment: no comment                    
You selected this USER-ID:
    "Aaron Somebody (no comment) <aaron.somebody@mulesoft.com>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key. 
<passphrase entered, and hidden>  
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key D54945B4 marked as ultimately trusted
public and secret key created and signed.
gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0  valid:   3  signed:   0  trust: 0-, 0q, 0n, 0m, 0f, 3u
gpg: next trustdb check due at 2015-08-25
pub   2048R/D54945B4 2015-08-23 [expires: 2015-08-25]
      Key fingerprint = 68BC E0A3 A377 417A 5102  ABB3 7689 9D95 D549 45B4
uid                  Aaron Somebody (no comment) <aaron.somebody@mulesoft.com>
sub   2048R/C1596E6C 2015-08-23 [expires: 2015-08-25]

When it completes the operation, the key generation tool adds your new public key to a system wide public key ring, and adds your private key to a parallel system-wide private key ring. The next step is to identify the filepath of the key rings so as to make them available for Mule to access. 

• Find the public key ring file (pubring.gpg) on your local drive
• Find the private key ring file (secring.gpg) 
• Mac or Unix: located in the hidden .gnupg folder on your local drive
• Windows: location varies according to your local configuration, but may be at a location similar to C:/Users/myuser/AppData/Roaming/gnupg

Determining the Numeric Value of the Secret Alias ID

To configure your message encryption processor in Mule, you must be in possession of the Secret Alias ID (such as the public key). Determining the numeric value for the Secret Alias ID is somewhat complex as its numeric value isn’t accessible via the key ring file or within the GPG utility. You can, however, employ a trick to discover the secret alias ID: assign a random value, such as "1", to the Secret Alias ID in the message encryption processor in your Mule flow, then run the application to let Mule throw an error on purpose. In the exception thrown from the Console output, Mule displays a message indicating the keys you can use. See image below. 

Examples

Two MuleSoft blogs posts offer examples of how to use PGP encryption in Mule. Access the following links to dig deeper into PGP.

• PGP Encryption and Salesforce Integration
• Using PGP Security: Explained from the Top

Configuring a Decrypter

• Studio Visual Editor
• XML Editor or Standalone

1. Before you begin, ensure you have the following three pieces of information in your possession:
   1. The filepath of your public key ring
   2. The filepath of your private key ring
   3. The numeric value of the Secret Alias Id (such as the public key)
      See Generating PGP Keys section above to learn more about acquiring these values.
2. Create an global Encryption element, specifying a name for the element if you wish. Change the default value for the Default Encrypter toPGP_ENCRYPTER.
3. On the Pgp Encrypter tab, configure the fields according to the table below.
   

   Field	Value
   General Tab
   Name	Required - A unique name for the global element.
   Default Encrypter	PGP_ENCRYPTER
   Pgp Encrypter Tab
   Reference or expression	If selected, in the Pgp Encrypter Reference, use an expression to reference attributes you have defined elsewhere in the XML configuration of your applications, or to reference the configurations defined in a bean.
   Define attributes	If selected, enter values in the following four fields.
   Public Key Ring File Name	Enter the filepath of the public key ring. This binary "key ring" holds the public key. Read more about finding and creating public key rings in the Generating PGP Keys section above.
   Secret Key Ring File Name	Enter the filepath of the private key ring. This binary "key ring" holds the message sender’s private key. Read more about finding and creating public public and private key rings in the Generating PGP Keys section above.
   Secret Alias Id	The numeric value of the RSA public key.
   Secret Passphrase	The password to access the private key. When you generate keys using GPG, the wizard or command line prompt demands that you enter your Real Name and Email Address, then asks you to create a password for accessing your keys. The password you used to generate the keys is the value you enter as the secret passphrase, which Mule uses to access the contents of the private key ring.

4. Set an Encryption message processor in the flow in which you wish to encrypt data in the message payload.
5. Configure the message processor according the table below. 

   Field	Value
   Display Name	A unique name for your message processor.
   Config Reference	Required - Use the drop-down to select the global Encryption element you created.
   Operation	Required - Decrypter
   Input reference	Enter a Mule expression to define the part(s) of the message Mule should decrypt. If no value is entered, Mule decrypts the entire message payload.
   Select encrypter	Required - PGP_ENCRYPTER
   Reference or expression	If selected, in the Pgp Encrypter Reference, use an expression to reference attributes you have defined elsewhere in the XML configuration of your applications, or to reference the configurations defined in a bean.
   Define attributes	If selected, enter values in the following field.
   Principal	An alternative to using a clientID and secret to authenticate a client, define a username and password as the principal. When you generate a set of keys with GPG, you are asked to enter a Real Name and an Email Address– together, these two pieces of data form the value of your Principal.