Opaque Data

Some features require your backend and YAXI to exchange data through the frontend. To prevent the frontend from accessing this data, it is encrypted using your API secret key (the same key used to issue tickets and verify results).

For instance, your backend may need to pass a stored IBAN to a service call without revealing it to the frontend, where you cannot (yet) verify who is operating it. Similarly, data returned by YAXI may need to reach your backend without being readable by the frontend.

Protocol backend

The scheme derives a unique key for each context using HKDF key derivation and encrypts data with ChaCha20-Poly1305 authenticated encryption.

To encrypt data:

  1. Derive a 32-byte key using HKDF (RFC 5869) with BLAKE2b-512 (RFC 7693) as the cryptographic hash function:

    • Use your API secret key as the input

    • 32 bytes output length

    • No salt

    • Use the applicable context value (UTF-8 encoded bytes) as the info parameter (see Contexts)

  2. Generate a 12-byte secure random nonce (also referred to as an initialization vector, or IV). Never reuse a nonce.

  3. Encrypt the plaintext using ChaCha20-Poly1305 (RFC 8439) with the derived key and the nonce from the previous steps.

  4. Concatenate the nonce and the resulting ciphertext.

  5. Base64-encode the concatenated result.

To decrypt, reverse steps 5 through 3: Base64-decode, split off the first 12 bytes as the nonce, and decrypt the remainder with ChaCha20-Poly1305.

Contexts

Each context uses a different value for the info parameter, so a separate key is derived for each and cannot be used interchangeably.

Context Description

on-file-data

Encrypt data you already have (e.g., a debtor IBAN) before sending it through the frontend to a service call.

result-data

Decrypt encrypted fields returned in service results (e.g., an encrypted debtor IBAN from Collect Payment).