Hash and Header

Both the hash and header are used to recover the encryption key used when performing an encrypt

Overview

When encrypting data with Grapheene, you'll be provided with an Encryption Key and it's related cryptographic data. Later, when performing a decrypt, you'll need that same Encryption Key and cryptographic data. In order to match the match the Encryption Key, Grapheene uses a hash or a header. You'll want to store either one of these alongside your data after encrypting it. We recommend that you prepend your data with either one. However, there's some decisions around which one to choose.

Hash

A unique value that references a Key in a KeyRing. This value is smaller than the header. This is provided as a way for the developer to encode their own header to prepend on to the encrypted data, or to store it in some other way that may work better for their use case. This is a base64 encoded 14-byte value.

If you decide to store this one, you'll also want to store any additional cryptographic data that will be required when decrypting; ie the initialization vector (IV).

Header

The header contains the hash, as well as other metadata, and allows Grapheene to build future features into the encryption process. The header is a byte array that contains:

[1 Byte] Version[2 Bytes] Length[14 Bytes] HashBlock Section
  • [1 byte] Version: Header version. Binary number representation.
  • [2 bytes] Length: Total length of the Header. Max size 2^16
  • [14 bytes] Hash: 6 bytes (KeyRing) + 8 bytes (Key)
    • Supports 281,474,976,710,656 KeyRings, or 892,551 KeyRings / min for 10 years
    • Supports 1.89 * 10^19 Keys / KeyRing, or 974,904,028 keys / second for 10 years

Block Section

  • [1 byte] Block Header: This represents a Block Type and the type of information it carries
  • [2 bytes] Block Length: 2 bytes
    • Max Block length would be 64kb
    • Block Data: Block-Length bytes
  • [N bytes] Block Data

Block Types

Block TypeValueDescription
IV1The cryptographic IV