Skip to content


The file bolt, in charge of archiving the data, supports enciphering. Pay attention to the key management strategy and make sure to understand what is the role of each key. Their management is your responsibility.

Each batch of data is enciphered with a symmetrical algorithm (AES-256-GCM) and symmetrical keys are enciphered with an asymmetric key (using RSA-2048 algorithm).

Each object metadata (as just highlighted in Objects Indexation<objectsIndexation>) stores an envelop that embeds the enciphered symmetrical key.

Enciphered file

!!! info "As illustrated on the figure, you can specify multiple asymmetric keys, for example to replace a compromised key. This is explained below.

These keys are managed in a Java KeyStore. The recommended keys management workflow depend of your use case.


  1. On a secure server, create a Java KeyStore and a pair of asymmetric keys using the following single command:
$ keytool -genkey -alias MyPPMasterKey -keyalg RSA -keysize 2048 -keystore /data/keystore.jks

Specify a first passphrase for your keystore (which will be known by all topologies including File Bolts or Archiving Processor Bolts) and a second passphrase for your asymmetric keys pair.

Both passphrase must be strong. The first passphrase is used to manage your KeyStore. It will be required for example to remove a key pair. The second passphrase is used to encrypt your private key, and thus used as well to decrypt your data later on.

This key pair is your PunchPlatform Master Key. Public key can be kept on your local KeyStore, but private key has to be moved to a safe cold storage (out of your system). It will be used only if you lose all other private keys.

We recommend you also keep a safe copy of your KeyStore outside your system.

1 . Create a second couple of keys for current operations with the same command:

keytool -genkey -alias MyOperationalKey -keyalg RSA -keysize 2048 -keystore /data/keystore.jks

This secondary private key can be kept on your local KeyStore. It will be used for current decryption operations.

You can create as many couples of keys you need. There is a little overhead: your symmetrical keys will be ciphered as many times as the number of couples of keys you specified. Don\'t worry the performance loss is low as long as your Kafka Spout is configured to send important batches (with batch_size settled to 1000 for example).

2 . Configure enciphering section of your File Bolts :

"enciphering" : {
  "keystore" : "/data/keystore.jks",
  "keystore_pass" : "MyKeyStorePassword",
  "keys" : [
    { "key_id" : "MyPPMasterKey" },
    { "key_id" : "MyOperationalKey" }

3 . Launch your channels and insert events 4 . Check data is enciphered

mkdir /tmp/extracted-data
storectl extract-scope --cluster myCluster --pool myTenant-data --topic myTopic --into /tmp/extracted-data
gunzip -c /tmp/extracted-data/myTenant-data/MyFile.gz

An error occurs (gunzip fails to unzip) because data is enciphered.

5 . Check data is readable using MyOperationalKey (working also with MyPPMasterKey)

mkdir /tmp/unciphered-extracted-data
storectl extract-scope --cluster myCluster --pool myTenant-data --topic myTopic --into /tmp/unciphered-extracted-data --keystore /data/keystore.jks --key-aliases MyOperationalKey
<Enter keystore and key passwords>
gunzip -c /tmp/unciphered-extracted-data/myTenant-data/MyFile.gz


As specified in storectl manual page, an enciphering extraction works only if you specify a target directory (--into option).

Change compromised keys

This section explains a working process to react to a compromised key scenario. Say one of the operational keys has been compromised. You need to remove this key and re-encipher envelope data with a new safe key (this will be faster than it seems, because we will only re-cipher meta-data that enclose secret keys specific to each ciphered file, therefore ciphering a much smaller amount of data than the overall archived data).

1 . Generate new key

keytool -genkey -alias MyNewSafeKey -keyalg RSA -keysize 2048 -keystore /data/keystore.jks

2 . Re-configure impacted File Bolts. In enciphering.keys section, replace :

{ "key_id" : "MyCompromisedKey" }

By :

{ "key_id" : "MyNewSafeKey" }

You also need to change topic (or path in file-system mode) destination. In publication_actions section, replace all topic field value (or path field value in file-system mode) by a new topic name. For example replace arkoon_parsed by arkoon_parsed_version_2.

3 . On a PunchPlatform administration station, restart archiving channel

channelctl stop --channel myArchivingChannel
channelctl start myTenant/myArchivingChannel

4 . Now you need to move your archive and update each encryption envelop (composed of enciphered symmetrical keys). To do it please configure a Massive Extraction topology<MassiveExtraction>. The only section to adapt is the ArchiveProcessor Bolt configuration.

You have to configure it to extract data from your old archiving system to your new archiving system (with topic or path updated) and to add two sections not described in samples. The first one permits to decipher data:

"deciphering" : {
     "keystore" : "/data/keystore/keystore.jks",
     "keystore_pass" : "MyKeyStorePassword",
     "keys" : [
                        "key_id" : "MyCompromisedOperationalKey",
                        "key_pass" : "MyCompromisedKeyPassword"

The second section permits to re-encipher encryption envelop:

"enciphering" : {
     "keystore" : "/data/keystore/keystore.jks",
     "keystore_pass" : "MyKeyStorePassword",
     "keys" : [
                        "key_id" : "MyNewSafeKey"

These two sections have to be placed at bolt-level (next to republication_actions section).


The PunchPlatform provides tools and procedures to re-encipher encryption envelop, it does not provide payloads re-enciphering.

5 . Once all data have been moved and all encryption envelops have been updated, remove compromised key from keystore (keystore password needed). Do not remove compromised key before.

$ keytool -delete -alias MyCompromisedKey -keystore /data/keystore/keystore.jks