Choosing the Right Chunk Crypto Cipher

While the Machina Tools SDK provides powerful tools to protect any type of data, we also want it to be as easy and convenient to drop in and share data. The ISFileCrypto module defines formats for a few specific file types like PDF, CSV, and OpenXML, as well as any generic file. However, a growing volume of our valuable data is in the form of text fields, whether on a website, database, or chat message. The name ‘Chunk’ in ISChunkCrypto was chosen to be ambiguous – something between a word and a “file.” Thus, the chunk cipher is an all-purpose module that can protect both structured and unstructured data.

The ISChunkCrypto module provides several format versions, and the distinctions between them may not be clear at first glance. This post covers each cipher version and explains its intended usage.

  • Chunk Cipher V1 – Legacy format with AES CTR
  • Chunk Cipher V2 – Default AES CTR with a bit less overhead
  • Chunk Cipher V3 – AES GCM for highest integrity
  • Chunk Cipher V4 – Small text compression but without binary support

Chunk Cipher V1

V1 is the original implementation of ChunkCryptoCipher and is included for legacy support.

Sample and Delimiters

Our first sample is of course “Hello, World!” encoded using V1.


Three delimiters separate the two sections of the format. The key ID begins with ‘~!’ and is separated from the cipher text with ‘~fEc!’. The format ends with ‘!cEf’. The key ID and Base 64 encoded ciphertext do not use the tilde or exclamation mark as valid characters.


While V1 will continue to work going forward, we recommend using one of the newer formats.

Chunk Cipher V2

V2 is the default used when encrypting with the automatic cipher.

Chunk Cipher V2 uses AES CTR (Counter Mode), a streaming cipher variant of AES where the next keystream block is calculated by encrypting increasing values of a “counter.” V2 uses a shorter set of delimiters than V1, as noted below.

Sample and Delimiters


The delimiters for V2 and onward are a little different. The beginning delimiter could be interpreted as a new initial version field as well – ‘~!2!’. A single ‘!’ delimits the remaining fields as well as the end of the format.


When encrypting a chunk of data using ISChunkCryptoCipherAuto, V2 is the format that will be used. It can be used to protect any amount of data from a single digit to over a gig and can be used either for text or binary. However, since the output is encoded as Base64 ASCII, the output data will be about 33% larger than the input.

Chunk Cipher V3

V3 uses AES GCM (Galois/Counter Mode), which uses the Ionic key ID as the additional authentication data and appends the output authentication tag on to the end of the data.

Sample and Delimiters


Similar to V2, it starts with a versioned ‘~!3!’ and uses ‘!’ for the remaining fields.


AES GCM adds a constant additional length to the encrypted data that is used to validate the encrypted data. Internally, it uses the key tag as the authentication input to provide an extra layer of assurance that no tampering could have occurred. It has a minor cost in terms of size and computation.

Chunk Cipher V4

V4 is the most specialized cipher. The intended usage is for limited-size text fields where the additional key data could pose a challenge for fitting a meaningful message in the remaining space. By compressing the plaintext before encryption, Chunk Cipher V4 in some instances can enable the full field length usage in less than 200 characters.

Chunk Cipher v4 uses a compression library named ‘Shoco’ that is intended to optimally compress words. The compression scheme was trained against English language texts, but will be reasonably effective at compressing most languages that can use ASCII characters. Additionally, it can use either Base64 or Z85 encoding depending on which encoding provides the most space saving given the input size.

Sample and Delimiters


The delimiters for V4 are chosen to save space – it starts with ‘~\’, separates key ID and ciphertext with a ‘;’, and ends with ‘\’.


For non-text input, you can expect the output to be about 25% larger than the input. However, for English text it can compress as much as 10%. At around 400-500 characters, V4 format should make up for the additional Ionic data and can be shorter than the input. You could fit around 100 characters into a 140 character field, as opposed to fewer than 80 characters if you were to use ISChunkCryptoCipherV3.
However, unlike other formats, V4 cannot support binary data.

Getting Started with Chunk Crypto Ciphers

To get started, you’ll need an Ionic Machina account. If you haven’t already, sign up for your account and be sure to follow the Machina quick-start instructions. To learn more about using Chunk Crypto and File Crypto, visit Machina Developers.