Message Format

[paragonie-scott]

We should encode some "basic" information in a header: Library, version, etc.

For example, the message format might seem like this (assume hex):

AAAAAAAA AAAAAAAA BBBBBBBB BBBBBBBB 
BBBBBBBB BBBBBBBB CCCCCCCC CCCCCCCC
CCCCCCCC CCCCCCCC CCCCCCCC CCCCCCCC
CCCCCCCC CCCCCCCC CCCCCCCC CCCCCCCC
CCCCCCCC CCCCCCCC CCCCCCCC CCCCCCCC
DDDDDDDD DDDDDDDD DDDDDDDD DDDDDDDD
DDDDDDDD DDDDDDDD DDDDDDDD DDDDDDDD

• A - 8 bytes - is metadata about the version of the library (and, possibly, the driver used?), whether it's asymmetric or symmetric, an identifier for other configuration information, etc.
• B - any number of bytes- nonce or IV, public key, etc.
• C - any number of bytes - ciphertext
• D - fixed number of bytes - MAC or authentication tag (Poly1305, etc.) -- must authenticate nonces and ciphertext.

---

Proposed Header Format

We should reserve 8 bytes (64 bits)

• Byte 0-1 => library version
  • [00][01] => alpha 0.1
  • [00][FF] => final beta before stable 1.0 release
  • [01][00] => stable 1.0
• Byte 2 => which driver, asymmetric or symmetric (first bit)
  • [01] => OpenSSL, symmetric
  • [02] => Libsodium, symmetric
  • [81] => OpenSSL, asymmetric
  • [82] => Libsodium, asymmetric
• Bytes 3-7 => configuration options (driver-specific)

[ircmaxell]

Well, I would suggest having the version dictate the rest of the layout. There may be algorithms that need more than 2 components prior to the MAC.

[paragonie-scott]

Right, that makes sense. The idea I wanted to establish was whether or not the first 8 bytes should be reserved for the header. (Is 8 bytes enough?)

[paragonie-scott]

Actually, if we just make the first 4 bytes the header then let each driver prepend its own "driver-specific" header after that, we can eschew the 3-7 detail.

[ircmaxell]

8 bytes is plenty. If more is needed the version can identify that and parse it explicitly (like an extension)

[ircmaxell]

Yeah, in that case, I'd do 4 bytes: VVDC

where C is a checksum (computed as V ^ V ^ D) to validate that the ciphertext is infact a valid ciphertext.

[paragonie-scott]

Alright, I'll put a formal definition in the docs directory. :+1: