Contact Us 1-800-596-4880

PGP Security

The Pretty Good Privacy (PGP) extension adds PGP security on connector communication. With PGP you can achieve end-to-end security communication with signed and encrypted messages between parties.

Requirements

Policy Files

If you are running a JDK that comes with the Oracle Java Cryptography Extension (JCE) by default, you must install the Unlimited Strength Jurisdiction Policy files, which can be downloaded from the following URLs (note that they are listed entirely at the bottom of the page, in the Other Downloads section):

These files must be installed in the $JAVA_HOME$/jre/lib/security directory.

According to Oracle, the default distribution of the JCE allows "strong, but limited strength cryptography." This means that you cannot use RSA keys bigger than 2048 bits and no symmetric ciphers that use more than 128 bits. ElGamal is not allowed at all, thus DH/DSS cannot be used for encryption.

Encrypting and Decrypting

To encrypt and decrypt messages you need to configure the following elements:

  • Security manager: Responsible of holding a security provider, which contains the key rings, and the encryption strategy to be used. This allows for the encryption of all messages using the same key or to facilitate the use of different key rings.

  • Key manager: Responsible for reading the key rings.

  • Credential accessor: Determines the key ring and key manager to be used to encrypt or decrypt the message being processed.

A full example is shown below:

<spring:beans>
    <spring:bean id="pgpKeyManager" class="org.mule.module.pgp.PGPKeyRingImpl" init-method="initialise">
        <spring:property name="publicKeyRingFileName" value="pubring.gpg"/>
        <spring:property name="secretKeyRingFileName" value="secring.gpg"/>
        <spring:property name="secretAliasId" value="${public.KeyId.LongValue}"/>
            <spring:property name="secretPassphrase" value="${secret.Passphrase}"/>
    </spring:bean>

        <spring:bean id="credentialAccessor" class="com.somecompany.apps.AppCredentialAccessor">
            <spring:property name="credentials" value="John Smith (TestingKey) &lt;john.smith@somecompany.com&gt;"/>
        </spring:bean>
</spring:beans>

<pgp:security-manager>
    <pgp:security-provider name="pgpSecurityProvider" keyManager-ref="pgpKeyManager"/>
        <pgp:keybased-encryption-strategy
        name="keyBasedEncryptionStrategy"
        keyManager-ref="pgpKeyManager"
        credentialsAccessor-ref="credentialAccessor"/>
</pgp:security-manager>

The pgpKeyManager (inside the <spring:beans> tag) is the one responsible for reading the rings. You have to set all the parameters: public and secret rings, the alias ID (the long value in the ring) and the secret passphrase. In the same section, you can see the credentials accessor which needs to implement the CredentialsAccessor interface basically returning the key id based on the message (MuleEvent). Finally the pgp:security-manager glues both beans.

You are ready to encrypt and decrypt messages in your flows. The following two flows show how to use the encrypt-transformer and decrypt-transformer to encrypt and decrypt files.

<flow name="processEncryptFiles">
    <file:inbound-endpoint connector-ref="inputEncrypt"
        path="file:///temp/fileInput" moveToDirectory="file:///temp/fileInputBackup"
        moveToPattern="#[header:originalFilename].backup" transformer-refs="file2Bytes" />

    <encrypt-transformer name="pgpEncrypt"
        strategy-ref="keyBasedEncryptionStrategy" />

    <file:outbound-endpoint connector-ref="output"
        path="file:///temp/fileOutput" outputPattern="#[function:datestamp]-#[header:originalFilename]" />
</flow>

<flow name="processDecryptFiles">
    <file:inbound-endpoint connector-ref="inputDecrypt"
        path="file:///temp/fileOutput" moveToDirectory="file:///temp/fileOutputEncrypted"
        moveToPattern="#[header:originalFilename].backup" transformer-refs="file2Bytes" />

    <decrypt-transformer name="pgpDecrypt"
        strategy-ref="keyBasedEncryptionStrategy" />

    <file:outbound-endpoint connector-ref="output"
        path="file:///temp/fileOutputDecrypted" outputPattern="#[function:datestamp]-#[header:originalFilename]" />
</flow>

The following sections explain how to configure each element.

Configuring the Security Manager

To configure the Security Manager you need to reference your key manager and your encryption strategy. The Key manager is simple a reference to your key manager ring.

Configuring the Key Manager

To configure your key manager you have to create a spring bean as shown before. You will need to set the public and secret ring files, the alias id and the secret passphrase. As Mule uses the bouncy castle library to encrypt/decrypt messages we recommend to obtain the alias ID (as a long value) using this library. If Mule does not find your ID in the ring, it throws an exception and lists all the available IDs in your ring.

Configuring a Credential Accessor

To configure your credential accessor, you need to define a class which determines your key ID. For instance the following class (used in the example) returns always the same fixed string thus all the messages are encrypted and decrypted using the same key ID. If you need to use different key IDs, then return different strings according to the MuleEvent received as a parameter.

public class FakeCredentialAccessor implements CredentialsAccessor
{
    private String credentials = "John Smith (TestingKey) <john.smith@somecompany.com>";

    public FakeCredentialAccessor()
    {
    }

    public FakeCredentialAccessor(String string)
    {
        this.credentials = string;
    }

    public String getCredentials()
    {
        return credentials;
    }

    public void setCredentials(String credentials)
    {
        this.credentials = credentials;
    }

    public Object getCredentials(MuleEvent event)
    {
        return this.credentials;
    }

    public void setCredentials(MuleEvent event, Object credentials)
    {
        // dummy
    }
}

Configuration Reference

PGP Module

This extension adds PGP security on endpoint communication. With PGP you can achieve end-to-end security communication with signed and encrypted messages between parties.

Security Manager

There are no Attributes of security-manager.

Child Elements of security-manager

Name Cardinality Description

security-provider

0..1

Security provider for PGP-related functionality.

keybased-encryption-strategy

0..1

The key-based PGP encryption strategy to use.

Security Provider

Security provider for PGP-related functionality. There are no default values.

Attributes of security-provider

Name Type Required Description

keyManager-ref

string

yes

Reference to the key manager to use.

Key-Based Encryption Strategy

The key-based PGP encryption strategy to use. There are no default values.

Attributes of keybased-encryption-strategy:

Name Type Required Description

keyManager-ref

string

yes

Reference to the key manager to use.

credentialsAccessor-ref

string

no

Reference to the credentials accessor to use.

checkKeyExpirity

boolean

no

Check key expiration.

There are no Child Elements of keybased-encryption-strategy.

Security Filter

Filters messages based on PGP encryption. There are no default values.

Attributes of security-filter:

Name Type Required Description

strategyName

string

yes

The name of the PGP encryption strategy to use.

signRequired

string

yes

Whether signing is required.

keyManager-ref

string

yes

Reference to the key manager to use.

credentialsAccessor-ref

string

yes

Reference to the credentials accessor to use.

There are no Child Elements of security-filter.