Skip to content

Docs: document AES.GCM ciphertext binary format for cross-language interoperability #129

@nxmxbbd

Description

@nxmxbbd

Description

The Cloak.Ciphers.AES.GCM module uses a specific binary format for encrypted data that differs from what most non-Elixir crypto libraries expect. While the source code contains an ASCII diagram of the format, there's no documentation aimed at developers who need to decrypt Cloak-encrypted data from other languages (Python, JavaScript, Go, etc.).

I recently needed to decrypt Cloak-encrypted data from Python and ran into two undocumented behaviors that required reading the source:

1. GCM authentication tag placement

Cloak places the 16-byte GCM auth tag before the ciphertext:

| Key Tag | IV | Auth Tag (16 bytes) | Ciphertext |

Most crypto libraries (Python's cryptography, Node.js crypto, Go crypto/cipher) expect the auth tag appended after the ciphertext:

| Ciphertext | Auth Tag (16 bytes) |

This means external consumers need to rearrange the bytes before decrypting.

2. Hardcoded AAD (Additional Authenticated Data)

The module uses a hardcoded AAD value of "AES256GCM" (defined as @aad "AES256GCM" in the source). This isn't mentioned in the module docs or README, and omitting or using the wrong AAD causes decryption to silently fail with an authentication error.

Suggested improvement

Add a section to the README or module docs titled something like "Interoperability / Decrypting from other languages" that documents:

  1. The complete binary format with byte offsets
  2. The AAD value used ("AES256GCM")
  3. That the GCM tag precedes the ciphertext (unlike most non-Erlang implementations)
  4. A reference example in one or two popular languages

This would help the ecosystem around projects that use Cloak to encrypt data that users sometimes need to access from external tools.

Related: #127 (closed — asked about JS decryption but self-resolved by switching to JWT)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions