karenswry edited this page Aug 22, 2018 · 18 revisions
:warning: Attention! This documentation is for Acra v0.82.0. For the latest documentation, examples, tutorials, and demos, please visit Cossack Labs Documentation Server. :warning:

AcraStruct container format

Before generating each AcraStruct, AcraWriter generates a keypair of throwaway keys that are used in the encryption process and then get zeroed (turned into zeros) in the memory once the process is over.

AcraStruct = Begin_Tag + Throwaway_Public_Key + Encrypted_Random_Key + Data_Length + Encrypted_Data

  • Begin_Tag[8] — 8 bytes, header tag (can be changed);
  • Throwaway_Public_Key[45] — temporary public key generated by AcraWriter;
  • Encrypted_Random_Key[84] — encrypted Random Key by using SMessage (see next);
  • Data_Length[8] — length of the Encrypted data (see next);
  • Encrypted_Data[Data_Length] — payload encrypted with Random Key.

Generating AcraStruct

AcraWriter is used to generate AcraStruct, but the generation process is quite simple and can be implemented in any custom writer:

  • AcraWriter generates a key pair of throwaway keys using Themis EC key generator:
    Throwaway_Keypair = (Throwaway_Public_Key, Throwaway_Private_Key).
  • Generates Random Symmetric Key (RK), 32 bytes long.
  • Encrypts RK using Secure Message with Throwaway_Private_Key and Acra_Public_Key (or Zone key – see Zones):
    Encrypted_Random_Key = SMessage(RK, Throwaway_Private_Key, Acra_Public_Key).
  • Encrypts the payload with Secure Cell in Seal mode:
    Encrypted_Data = SCell(RK, payload).
  • Erases/fills with zeros memory area with the RK.
  • Calculates the encrypted payload length and transforms it to little endian 8 bytes long (Data_Length).
  • Connects attributes together as described in the original formula.
  • Erases/fills with zeros memory area with the Throwaway_Keypair and original payload.

You can check how AcraStruct is generated in acra-writer.go,, acrawriter.rb or acrawriter.php.

Decrypting AcraStruct

AcraServer, upon receiving and detecting valid AcraStruct, is able to:

  • Extract Throwaway Public Key (TPK).
  • Decrypt asymmetric envelope with TPK and Acra's Private Key (or Zone key).
  • Extract Random Key (RK) for Secure Cell container out of a decrypted envelope;
  • Decrypt Secure Cell, extract payload;
  • Reconstruct database answer in such a way that AcraStruct is replaced by decrypted data.

Check implementation in decryptor/base/utils.go.

Zone IDs

Although not directly related to AcraStructs, Zone IDs are used for matching Zones to keys. The current format is 8 bytes "begin tag" + 16 symbols a-zA-Z.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.