Skip to content

Encrypt

decrypt

Takes a value produced by encrypt() and decrypts it. key_base and domain must be the same given to encrypt or else decryption fails. Upon decryption failure a decrypt_error exception is thrown.

Declaration

ustring decrypt(ustring_view ciphertext, ustring_view key_base, std::string_view domain);

Parameters

  • ciphertext — message to decrypt
  • key_base — Fixed key that all clients, must be 32 bytes.
  • domain — short string for the keyed hash

Returns

  • ustring — Returns the decrypt message bytes

decrypt_inplace

Same as above decrypt(), but does in in-place. The string gets shortend to the plaintext after this call.

Declaration

void decrypt_inplace(ustring& ciphertext, ustring_view key_base, std::string_view domain);

Parameters

  • ciphertext — message to decrypt
  • key_base — Fixed key that all clients, must be 32 bytes.
  • domain — short string for the keyed hash

Returns

encrypt

Encrypts a config message using XChaCha20-Poly1305, using a blake2b keyed hash of the message for the nonce (rather than pure random) so that different clients will encrypt the same data to the same encrypted value (thus allowing for server-side deduplication of identical messages).

key_base must be 32 bytes. This value is a fixed key that all clients that might receive this message can calculate independently (for instance a value derived from a secret key, or a shared random key). This key will be hashed with the message size and domain suffix (see below) to determine the actual encryption key.

domain is a short string (1-24 chars) used for the keyed hash. Typically this is the type of config, e.g. "closed-group" or "contacts". The full key will be "session-config-encrypted-message-[domain]". This value is also used for the encrypted key (see above).

The returned result will consist of encrypted data with authentication tag and appended nonce, suitable for being passed to decrypt() to authenticate and decrypt.

Throw std::invalid_argument on bad input (i.e. from invalid key_base or domain).

Declaration

ustring encrypt(ustring_view message, ustring_view key_base, std::string_view domain);

Parameters

  • message — message to encrypt
  • key_base — Fixed key that all clients, must be 32 bytes.
  • domain — short string for the keyed hash

Returns

  • ustring — Returns the encrypted message bytes

encrypt_inplace

Same as above encrypt, but modifies message in place. message gets encrypted plus has the extra data and nonce appended.

Declaration

void encrypt_inplace(ustring& message, ustring_view key_base, std::string_view domain);

Parameters

  • message — message to encrypt
  • key_base — Fixed key that all clients, must be 32 bytes.
  • domain — short string for the keyed hash

Returns

pad_message

Inserts null byte padding to the beginning of a message to make the final message size granular. See the above function for the sizes.

\param data - the data; this is modified in place. \param overhead -

Declaration

void pad_message(ustring& data, size_t overhead = ENCRYPT_DATA_OVERHEAD);

Parameters

  • data — the data; this is modified in place
  • overhead — encryption overhead to account for to reach the desired padded size. The default, if omitted, is the space used by the encrypt() function defined above.

Returns