Crypto (Java Cryptographic Extension)

Since Camel 2.3

The Crypto Data Format integrates the Java Cryptographic Extension into Camel, allowing simple and flexible encryption and decryption of messages using Camel’s familiar marshall and unmarshal formatting mechanism. It assumes marshalling to mean encryption to cyphertext and unmarshalling to mean decryption back to the original plaintext. This data format implements only symmetric (shared-key) encryption and decyption.

CryptoDataFormat Options

The Crypto (Java Cryptographic Extension) dataformat supports 10 options, which are listed below.

Name Default Java Type Description

algorithm

String

The JCE algorithm name indicating the cryptographic algorithm that will be used.

cryptoProvider

String

The name of the JCE Security Provider that should be used.

keyRef

String

Refers to the secret key to lookup from the register to use.

initVectorRef

String

Refers to a byte array containing the Initialization Vector that will be used to initialize the Cipher.

algorithmParameterRef

String

A JCE AlgorithmParameterSpec used to initialize the Cipher. Will lookup the type using the given name as a java.security.spec.AlgorithmParameterSpec type.

buffersize

Integer

The size of the buffer used in the signature process.

macAlgorithm

HmacSHA1

String

The JCE algorithm name indicating the Message Authentication algorithm.

shouldAppendHMAC

true

Boolean

Flag indicating that a Message Authentication Code should be calculated and appended to the encrypted data.

inline

false

Boolean

Flag indicating that the configured IV should be inlined into the encrypted data stream. Is by default false.

contentTypeHeader

false

Boolean

Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSON etc.

ND

Basic Usage

At its most basic all that is required to encrypt/decrypt an exchange is a shared secret key. If one or more instances of the Crypto data format are configured with this key the format can be used to encrypt the payload in one route (or part of one) and decrypted in another. For example, using the Java DSL as follows:

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());

from("direct:basic-encryption")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

In Spring the dataformat is configured first and then used in routes

<camelContext id="camel" xmlns="http://camel.apache.org/schema/spring">
  <dataFormats>
    <crypto id="basic" algorithm="DES" keyRef="desKey" />
  </dataFormats>
    ...
  <route>
    <from uri="direct:basic-encryption" />
    <marshal ref="basic" />
    <to uri="mock:encrypted" />
    <unmarshal ref="basic" />
    <to uri="mock:unencrypted" />
  </route>
</camelContext>

Specifying the Encryption Algorithm

Changing the algorithm is a matter of supplying the JCE algorithm name. If you change the algorithm you will need to use a compatible key.

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());
cryptoFormat.setShouldAppendHMAC(true);
cryptoFormat.setMacAlgorithm("HmacMD5");

from("direct:hmac-algorithm")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

A list of the available algorithms in Java 7 is available via the Java Cryptography Architecture Standard Algorithm Name Documentation.

Specifying an Initialization Vector

Some crypto algorithms, particularly block algorithms, require configuration with an initial block of data known as an Initialization Vector. In the JCE this is passed as an AlgorithmParameterSpec when the Cipher is initialized. To use such a vector with the CryptoDataFormat you can configure it with a byte[] containing the required data e.g.

KeyGenerator generator = KeyGenerator.getInstance("DES");
byte[] initializationVector = new byte[] {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07};

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES/CBC/PKCS5Padding", generator.generateKey());
cryptoFormat.setInitializationVector(initializationVector);

from("direct:init-vector")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

or with spring, suppling a reference to a byte[]

<crypto id="initvector" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey" initVectorRef="initializationVector" />

The same vector is required in both the encryption and decryption phases. As it is not necessary to keep the IV a secret, the DataFormat allows for it to be inlined into the encrypted data and subsequently read out in the decryption phase to initialize the Cipher. To inline the IV set the /oinline flag.

KeyGenerator generator = KeyGenerator.getInstance("DES");
byte[] initializationVector = new byte[] {0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07};
SecretKey key = generator.generateKey();

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES/CBC/PKCS5Padding", key);
cryptoFormat.setInitializationVector(initializationVector);
cryptoFormat.setShouldInlineInitializationVector(true);
CryptoDataFormat decryptFormat = new CryptoDataFormat("DES/CBC/PKCS5Padding", key);
decryptFormat.setShouldInlineInitializationVector(true);

from("direct:inline")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(decryptFormat)
    .to("mock:unencrypted");

or with spring.

<crypto id="inline" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey" initVectorRef="initializationVector"
  inline="true" />
<crypto id="inline-decrypt" algorithm="DES/CBC/PKCS5Padding" keyRef="desKey" inline="true" />

For more information of the use of Initialization Vectors, consult

Hashed Message Authentication Codes (HMAC)

To avoid attacks against the encrypted data while it is in transit the CryptoDataFormat can also calculate a Message Authentication Code for the encrypted exchange contents based on a configurable MAC algorithm. The calculated HMAC is appended to the stream after encryption. It is separated from the stream in the decryption phase. The MAC is recalculated and verified against the transmitted version to insure nothing was tampered with in transit.For more information on Message Authentication Codes see http://en.wikipedia.org/wiki/HMAC

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());
cryptoFormat.setShouldAppendHMAC(true);

from("direct:hmac")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

or with spring.

<crypto id="hmac" algorithm="DES" keyRef="desKey" shouldAppendHMAC="true" />

By default the HMAC is calculated using the HmacSHA1 mac algorithm though this can be easily changed by supplying a different algorithm name. See here for how to check what algorithms are available through the configured security providers

KeyGenerator generator = KeyGenerator.getInstance("DES");

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", generator.generateKey());
cryptoFormat.setShouldAppendHMAC(true);
cryptoFormat.setMacAlgorithm("HmacMD5");

from("direct:hmac-algorithm")
    .marshal(cryptoFormat)
    .to("mock:encrypted")
    .unmarshal(cryptoFormat)
    .to("mock:unencrypted");

or with spring.

<crypto id="hmac-algorithm" algorithm="DES" keyRef="desKey" macAlgorithm="HmacMD5" shouldAppendHMAC="true" />

Supplying Keys Dynamically

When using a Recipient list or similar EIP the recipient of an exchange can vary dynamically. Using the same key across all recipients may neither be feasible or desirable. It would be useful to be able to specify keys dynamically on a per exchange basis. The exchange could then be dynamically enriched with the key of its target recipient before being processed by the data format. To facilitate this the DataFormat allow for keys to be supplied dynamically via the message headers below

  • CryptoDataFormat.KEY "CamelCryptoKey"

CryptoDataFormat cryptoFormat = new CryptoDataFormat("DES", null);
/**
 * Note: the header containing the key should be cleared after
 * marshalling to stop it from leaking by accident and
 * potentially being compromised. The processor version below is
 * arguably better as the key is left in the header when you use
 * the DSL leaks the fact that camel encryption was used.
 */
from("direct:key-in-header-encrypt")
    .marshal(cryptoFormat)
    .removeHeader(CryptoDataFormat.KEY)
    .to("mock:encrypted");

from("direct:key-in-header-decrypt").unmarshal(cryptoFormat).process(new Processor() {
    public void process(Exchange exchange) throws Exception {
        exchange.getIn().getHeaders().remove(CryptoDataFormat.KEY);
        exchange.getOut().copyFrom(exchange.getIn());
    }
}).to("mock:unencrypted");

or with spring.

<crypto id="nokey" algorithm="DES" />

Dependencies

To use the Crypto dataformat in your camel routes you need to add the following dependency to your pom.

<dependency>
  <groupId>org.apache.camel</groupId>
  <artifactId>camel-crypto</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>

Spring Boot Auto-Configuration

When using crypto with Spring Boot make sure to use the following Maven dependency to have support for auto configuration:

<dependency>
  <groupId>org.apache.camel.springboot</groupId>
  <artifactId>camel-crypto-starter</artifactId>
  <version>x.x.x</version>
  <!-- use the same version as your Camel core version -->
</dependency>

The component supports 49 options, which are listed below.

Name Description Default Type

camel.component.crypto.algorithm

Sets the JCE name of the Algorithm that should be used for the signer.

SHA256withRSA

String

camel.component.crypto.alias

Sets the alias used to query the KeyStore for keys and {link java.security.cert.Certificate Certificates} to be used in signing and verifying exchanges. This value can be provided at runtime via the message header org.apache.camel.component.crypto.DigitalSignatureConstants#KEYSTORE_ALIAS

String

camel.component.crypto.basic-property-binding

Whether the component should use basic property binding (Camel 2.x) or the newer property binding with additional capabilities

false

Boolean

camel.component.crypto.buffer-size

Set the size of the buffer used to read in the Exchange payload data.

2048

Integer

camel.component.crypto.certificate

Set the Certificate that should be used to verify the signature in the exchange based on its payload. The option is a java.security.cert.Certificate type.

String

camel.component.crypto.certificate-name

Sets the reference name for a PrivateKey that can be found in the registry.

String

camel.component.crypto.clear-headers

Determines if the Signature specific headers be cleared after signing and verification. Defaults to true, and should only be made otherwise at your extreme peril as vital private information such as Keys and passwords may escape if unset.

true

Boolean

camel.component.crypto.configuration

To use the shared DigitalSignatureConfiguration as configuration. The option is a org.apache.camel.component.crypto.DigitalSignatureConfiguration type.

String

camel.component.crypto.enabled

Whether to enable auto configuration of the crypto component. This is enabled by default.

Boolean

camel.component.crypto.key-store-parameters

Sets the KeyStore that can contain keys and Certficates for use in signing and verifying exchanges based on the given KeyStoreParameters. A KeyStore is typically used with an alias, either one supplied in the Route definition or dynamically via the message header CamelSignatureKeyStoreAlias. If no alias is supplied and there is only a single entry in the Keystore, then this single entry will be used. The option is a org.apache.camel.support.jsse.KeyStoreParameters type.

String

camel.component.crypto.keystore

Sets the KeyStore that can contain keys and Certficates for use in signing and verifying exchanges. A KeyStore is typically used with an alias, either one supplied in the Route definition or dynamically via the message header CamelSignatureKeyStoreAlias. If no alias is supplied and there is only a single entry in the Keystore, then this single entry will be used. The option is a java.security.KeyStore type.

String

camel.component.crypto.keystore-name

Sets the reference name for a Keystore that can be found in the registry.

String

camel.component.crypto.lazy-start-producer

Whether the producer should be started lazy (on the first message). By starting lazy you can use this to allow CamelContext and routes to startup in situations where a producer may otherwise fail during starting and cause the route to fail being started. By deferring this startup to be lazy then the startup failure can be handled during routing messages via Camel’s routing error handlers. Beware that when the first message is processed then creating and starting the producer may take a little time and prolong the total processing time of the processing.

false

Boolean

camel.component.crypto.password

Sets the password used to access an aliased PrivateKey in the KeyStore.

String

camel.component.crypto.private-key

Set the PrivateKey that should be used to sign the exchange. The option is a java.security.PrivateKey type.

String

camel.component.crypto.private-key-name

Sets the reference name for a PrivateKey that can be found in the registry.

String

camel.component.crypto.provider

Set the id of the security provider that provides the configured Signature algorithm.

String

camel.component.crypto.public-key

Set the PublicKey that should be used to verify the signature in the exchange. The option is a java.security.PublicKey type.

String

camel.component.crypto.public-key-name

references that should be resolved when the context changes

String

camel.component.crypto.secure-random

Set the SecureRandom used to initialize the Signature service. The option is a java.security.SecureRandom type.

String

camel.component.crypto.secure-random-name

Sets the reference name for a SecureRandom that can be found in the registry.

String

camel.component.crypto.signature-header-name

Set the name of the message header that should be used to store the base64 encoded signature. This defaults to 'CamelDigitalSignature'

String

camel.dataformat.crypto.algorithm

The JCE algorithm name indicating the cryptographic algorithm that will be used.

String

camel.dataformat.crypto.algorithm-parameter-ref

A JCE AlgorithmParameterSpec used to initialize the Cipher. Will lookup the type using the given name as a java.security.spec.AlgorithmParameterSpec type.

String

camel.dataformat.crypto.buffersize

The size of the buffer used in the signature process.

Integer

camel.dataformat.crypto.content-type-header

Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSON etc.

false

Boolean

camel.dataformat.crypto.crypto-provider

The name of the JCE Security Provider that should be used.

String

camel.dataformat.crypto.enabled

Whether to enable auto configuration of the crypto data format. This is enabled by default.

Boolean

camel.dataformat.crypto.init-vector-ref

Refers to a byte array containing the Initialization Vector that will be used to initialize the Cipher.

String

camel.dataformat.crypto.inline

Flag indicating that the configured IV should be inlined into the encrypted data stream. Is by default false.

false

Boolean

camel.dataformat.crypto.key-ref

Refers to the secret key to lookup from the register to use.

String

camel.dataformat.crypto.mac-algorithm

The JCE algorithm name indicating the Message Authentication algorithm.

HmacSHA1

String

camel.dataformat.crypto.should-append-h-m-a-c

Flag indicating that a Message Authentication Code should be calculated and appended to the encrypted data.

true

Boolean

camel.dataformat.pgp.algorithm

Symmetric key encryption algorithm; possible values are defined in org.bouncycastle.bcpg.SymmetricKeyAlgorithmTags; for example 2 (= TRIPLE DES), 3 (= CAST5), 4 (= BLOWFISH), 6 (= DES), 7 (= AES_128). Only relevant for encrypting.

Integer

camel.dataformat.pgp.armored

This option will cause PGP to base64 encode the encrypted text, making it available for copy/paste, etc.

false

Boolean

camel.dataformat.pgp.compression-algorithm

Compression algorithm; possible values are defined in org.bouncycastle.bcpg.CompressionAlgorithmTags; for example 0 (= UNCOMPRESSED), 1 (= ZIP), 2 (= ZLIB), 3 (= BZIP2). Only relevant for encrypting.

Integer

camel.dataformat.pgp.content-type-header

Whether the data format should set the Content-Type header with the type from the data format if the data format is capable of doing so. For example application/xml for data formats marshalling to XML, or application/json for data formats marshalling to JSON etc.

false

Boolean

camel.dataformat.pgp.enabled

Whether to enable auto configuration of the pgp data format. This is enabled by default.

Boolean

camel.dataformat.pgp.hash-algorithm

Signature hash algorithm; possible values are defined in org.bouncycastle.bcpg.HashAlgorithmTags; for example 2 (= SHA1), 8 (= SHA256), 9 (= SHA384), 10 (= SHA512), 11 (=SHA224). Only relevant for signing.

Integer

camel.dataformat.pgp.integrity

Adds an integrity check/sign into the encryption file. The default value is true.

true

Boolean

camel.dataformat.pgp.key-file-name

Filename of the keyring; must be accessible as a classpath resource (but you can specify a location in the file system by using the file: prefix).

String

camel.dataformat.pgp.key-userid

The user ID of the key in the PGP keyring used during encryption. Can also be only a part of a user ID. For example, if the user ID is Test User then you can use the part Test User or to address the user ID.

String

camel.dataformat.pgp.password

Password used when opening the private key (not used for encryption).

String

camel.dataformat.pgp.provider

Java Cryptography Extension (JCE) provider, default is Bouncy Castle (BC). Alternatively you can use, for example, the IAIK JCE provider; in this case the provider must be registered beforehand and the Bouncy Castle provider must not be registered beforehand. The Sun JCE provider does not work.

String

camel.dataformat.pgp.signature-key-file-name

Filename of the keyring to use for signing (during encryption) or for signature verification (during decryption); must be accessible as a classpath resource (but you can specify a location in the file system by using the file: prefix).

String

camel.dataformat.pgp.signature-key-ring

Keyring used for signing/verifying as byte array. You can not set the signatureKeyFileName and signatureKeyRing at the same time.

String

camel.dataformat.pgp.signature-key-userid

User ID of the key in the PGP keyring used for signing (during encryption) or signature verification (during decryption). During the signature verification process the specified User ID restricts the public keys from the public keyring which can be used for the verification. If no User ID is specified for the signature verficiation then any public key in the public keyring can be used for the verification. Can also be only a part of a user ID. For example, if the user ID is Test User then you can use the part Test User or to address the User ID.

String

camel.dataformat.pgp.signature-password

Password used when opening the private key used for signing (during encryption).

String

camel.dataformat.pgp.signature-verification-option

Controls the behavior for verifying the signature during unmarshaling. There are 4 values possible: optional: The PGP message may or may not contain signatures; if it does contain signatures, then a signature verification is executed. required: The PGP message must contain at least one signature; if this is not the case an exception (PGPException) is thrown. A signature verification is executed. ignore: Contained signatures in the PGP message are ignored; no signature verification is executed. no_signature_allowed: The PGP message must not contain a signature; otherwise an exception (PGPException) is thrown.

String
Back to top