ExIcaoVds.Encryptor behaviour (ex_icao_vds v0.3.2)

Copy Markdown

Behaviour for optional field-level encryption inside the VDS message zone.

VDS provides authenticity and integrity — not confidentiality. Encryption is an optional extra layer applied inside a feature value before the feature is included in the signed message zone.

The signed payload therefore covers the ciphertext, ensuring that any tampering with the encrypted data breaks signature verification.

Encryption ordering

normalize → encode public fields → encrypt sensitive fields
  → canonicalize header + message zone → sign → render carrier

Callbacks

  • encrypt_field/5 — encrypt a single field value; returns encoded bytes ready to be stored as encoded_value in the Feature struct
  • decrypt_field/5 — decrypt a single field value; returns the decoded term
  • mode/1 — encryption mode atom (e.g. :hpke, :none)
  • algorithms/1 — map describing algorithm suite in use

Summary

Callbacks

algorithms(config)

Return a map describing the algorithm suite in use.

decrypt_field(field, encrypted_value, key_store, profile, opts)

Decrypt an encrypted field value.

encrypt_field(field, plaintext, recipient_config, profile, opts)

Encrypt the given plaintext bytes for field.

mode(config)

Return the encryption mode atom (e.g. :hpke, :none).

Callbacks

algorithms(config)

@callback algorithms(config :: map()) :: map()

Return a map describing the algorithm suite in use.

decrypt_field(field, encrypted_value, key_store, profile, opts)

@callback decrypt_field(
  field :: map(),
  encrypted_value :: binary(),
  key_store :: map(),
  profile :: module() | nil,
  opts :: keyword()
) :: {:ok, term()} | {:error, ExIcaoVds.Error.t()}

Decrypt an encrypted field value.

  • field — field definition map
  • encrypted_value — bytes from the decoded Feature.encoded_value
  • key_store — map of key_id => {priv_key_bytes, pub_key_bytes}
  • profile — the calling profile module (may be nil)
  • opts — keyword options

Returns {:ok, decoded_term} or {:error, ExIcaoVds.Error.t()}.

encrypt_field(field, plaintext, recipient_config, profile, opts)

@callback encrypt_field(
  field :: map(),
  plaintext :: binary(),
  recipient_config :: map(),
  profile :: module() | nil,
  opts :: keyword()
) :: {:ok, binary()} | {:error, ExIcaoVds.Error.t()}

Encrypt the given plaintext bytes for field.

  • field — field definition map (has :name, :tag, :encoding, etc.)
  • plaintext — the CBOR-encoded field value to encrypt
  • recipient_config — map with recipient public key and key_id
  • profile — the calling profile module (may be nil)
  • opts — keyword options

Returns {:ok, encrypted_bytes} or {:error, ExIcaoVds.Error.t()}.

mode(config)

@callback mode(config :: map()) :: atom()

Return the encryption mode atom (e.g. :hpke, :none).