Logo

github Download
AcraStruct

AcraStruct #

AcraStruct is an asymmetric cryptographic container. In a nutshell, it encrypts data using symmetric encryption, and then encrypts the key using asymmetric encryption.

AcraServer and AcraTranslator can encrypt/decrypt AcraStructs, but the main gem of AcraStructs is client-side encryption. Due to the asymmetric nature, client application can generate AcraStructs (encrypt data into AcraStructs) without risks, as only Acra’s public key is exposed.

AcraStruct supports key rotation: it’s possible to rotate only KEK without re-encrypting the data (known as “key rotation without data re-encryption”), or re-encrypt data and rotate both keys (“key rotation with data re-encryption”).

AcraStruct supports searchable encryption.

Prefer AcraStruct when using client-side encryption.

Container structure #

AcraStruct is a cryptographic container with a specific format. The data is encrypted using random symmetric encryption key (DEK) and AES-256-GCM-PKCS#7. Then the encryption key is encrypted using a key derived asymmetrically. For these purposes, encryptor 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.

During decryption, AcraServer/AcraTranslator use own private key for decrypting DEK, and then decrypting data using DEK.

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.

Starting from Acra 0.90.0, AcraStructs and AcraBlocks support interoperability.

Example #

AcraStruct example for the example plaintext:

[34, 34, 34, 34, 34, 34, 34, 34, 85, 69, 67, 50, 0, 0, 0, 45, 17, 107, 171, 101, 3, 5, 207, 103, 32, 150, 35, 237, 58, 19, 79, 215, 123, 254, 205, 12, 154, 149, 16, 116, 80, 130, 110, 20, 249, 80, 253, 209, 219, 167, 55, 50, 135, 32, 39, 4, 38, 84, 0, 0, 0, 0, 1, 1, 64, 12, 0, 0, 0, 16, 0, 0, 0, 32, 0, 0, 0, 63, 95, 208, 109, 191, 139, 244, 155, 230, 168, 180, 64, 234, 84, 240, 17, 116, 147, 64, 73, 253, 86, 60, 226, 127, 240, 170, 251, 229, 234, 145, 85, 88, 142, 29, 221, 12, 230, 72, 4, 254, 95, 243, 71, 174, 9, 126, 41, 221, 0, 127, 202, 160, 42, 53, 72, 218, 86, 141, 248, 51, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 64, 12, 0, 0, 0, 16, 0, 0, 0, 7, 0, 0, 0, 34, 115, 175, 148, 77, 152, 188, 222, 105, 123, 145, 77, 152, 254, 160, 19, 183, 122, 53, 138, 147, 149, 157, 223, 238, 71, 133, 139, 117, 210, 232, 110, 181, 241, 3]

  • Begin_Tag[8] - [34, 34, 34, 34, 34, 34, 34, 34]
  • Throwaway_Public_Key[45] - [85, 69, 67, 50, 0, 0, 0, 45, 17, 107, 171, 101, 3, 5, 207, 103, 32, 150, 35, 237, 58, 19, 79, 215, 123, 254, 205, 12, 154, 149, 16, 116, 80, 130, 110, 20, 249, 80, 253, 209, 219, 167, 55, 50, 135]
  • Encrypted_Random_Key[84] - [32, 39, 4, 38, 84, 0, 0, 0, 0, 1, 1, 64, 12, 0, 0, 0, 16, 0, 0, 0, 32, 0, 0, 0, 63, 95, 208, 109, 191, 139, 244, 155, 230, 168, 180, 64, 234, 84, 240, 17, 116, 147, 64, 73, 253, 86, 60, 226, 127, 240, 170, 251, 229, 234, 145, 85, 88, 142, 29, 221, 12, 230, 72, 4, 254, 95, 243, 71, 174, 9, 126, 41, 221, 0, 127, 202, 160, 42, 53, 72, 218, 86, 141, 248]
  • Data_Length[8] - [51, 0, 0, 0, 0, 0, 0, 0]
  • Encrypted_Data[51] - [0, 1, 1, 64, 12, 0, 0, 0, 16, 0, 0, 0, 7, 0, 0, 0, 34, 115, 175, 148, 77, 152, 188, 222, 105, 123, 145, 77, 152, 254, 160, 19, 183, 122, 53, 138, 147, 149, 157, 223, 238, 71, 133, 139, 117, 210, 232, 110, 181, 241, 33]

Generation (encryption) #

To generate AcraStructs, AcraServer/AcraTranslator/AcraWriter uses a public key generated for every ClientID/ZoneID.

Zones are deprecated since 0.94.0, will be removed in 0.95.0.

The generation contains the following steps:

  • Generate a keypair of throwaway keys using Themis EC key generator: Throwaway_Keypair = (Throwaway_Public_Key, Throwaway_Private_Key).
  • Generate Random Symmetric Key (RK), 32 bytes long.
  • Encrypt 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)).
  • Encrypt the payload with Secure Cell in Seal mode: Encrypted_Data = SCell(RK, payload).
  • Erase/fill with zeros memory area of the RK.
  • Calculate the encrypted payload length and transforms it into little endian 8 bytes long (Data_Length).
  • Connect attributes together as described in the original formula.
  • Erase/fill with zeros the memory area containing the Throwaway_Keypair and original payload.

Decryption #

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

  • Extract Throwaway Public Key (TPK).
  • Decrypt an 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, extracts payload;
  • Reconstruct database answer in such a way that AcraStruct is replaced by decrypted data.
Edit Edit this page