Base

`config_add_key`

Adds an encryption/decryption key, without removing existing keys. They key must be exactly 32 bytes long. The newly added key becomes the highest priority key: it will be used for encryption of config pushes after the call, and will be tried first when decrypting, followed by keys present (if any) before this call. If the given key is already present in the key list then this call moves it to the front of the list (if not already at the front).

Declaration

BOOL config_add_key(
    [in, out]       config_object*          conf,
    [in]            const unsigned char*    key
);

Parameters

conf — [in, out] Pointer to config_object object
key — [in] Pointer to the binary key object, must be 32 bytes

Returns

bool — Returns true if the call succeeds, false if an error occurs.

`config_add_key_low_prio`

Adds an encryption/decryption key, without removing existing keys. They key must be exactly 32 bytes long. The newly added key becomes the lowest priority key

Declaration

BOOL config_add_key_low_prio(
    [in, out]       config_object*          conf,
    [in]            const unsigned char*    key
);

Parameters

conf — [in, out] Pointer to config_object object
key — [in] Pointer to the binary key object, must be 32 bytes

Returns

bool — Returns true if the call succeeds, false if an error occurs.

`config_clear_keys`

Clears all stored encryption/decryption keys. This is typically immediately followed with one or more add_key call to replace existing keys. Returns the number of keys removed.

Declaration

INT config_clear_keys(
    [in]    config_object*          conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

int — Number of keys removed

`config_clear_sig_keys`

Drops the signature pubkey and/or secret key, if the object has them.

Declaration

LIBSESSION_EXPORT void config_clear_sig_keys(config_object* conf);

Parameters

This endpoint takes no inputs.

Returns

`config_confirm_pushed`

Reports that data obtained from config_push has been successfully stored on the server with message hash msg_hash. The seqno value is the one returned by the config_push call that yielded the config data.

Declaration

VOID config_confirm_pushed(
    [in, out]   config_object*      conf,
    [out]       seqno_t             seqno,
    [out]       const char*         msg_hash
);

Parameters

conf — [in] Pointer to config_object object
seqno — [out] Value returned by config_push call
msg_hash — [out] Value returned by config_push call

Returns

`config_current_hashes`

Obtains the current active hashes. Note that this will be empty if the current hash is unknown or not yet determined (for example, because the current state is dirty or because the most recent push is still pending and we don't know the hash yet).

The returned pointer belongs to the caller and must be freed via free() when done with it.

Declaration

CONFIG_STRING_LIST* config_current_hashes(
    [in]    const config_object*          conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

config_string_list* — pointer to the list of hashes; the pointer belongs to the caller

`config_dump`

Returns a binary dump of the current state of the config object. This dump can be used to resurrect the object at a later point (e.g. after a restart). Allocates a new buffer and sets it in out and the length in outlen. Note that this is binary data, not a null-terminated C string.

NB: It is the caller's responsibility to free() the buffer when done with it.

Immediately after this is called config_needs_dump will start returning true (until the configuration is next modified).

Declaration

VOID config_dump(
    [in]    config_object*          conf
);

Parameters

conf — [in] Pointer to config_object object
out — [out] Pointer to the output location
outlen — [out] Length of output

Returns

bool — Returns true if the call succeeds, false if an error occurs.

`config_encryption_domain`

Returns the encryption domain C-str used to encrypt values for this config object. (This is here only for debugging/testing).

Declaration

CONST CHAR* config_encryption_domain(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

char* — encryption domain C-str used to encrypt values

`config_free`

Frees a config object created with one of the config-dependent ..._init functions (e.g. user_profile_init).

Declaration

VOID config_free(
    [in, out]   config_object*      conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

`config_get_keys`

Obtains the current group decryption keys.

Returns a buffer where each consecutive 32 bytes is an encryption key for the object, in priority order (i.e. the key at 0 is the encryption key, and the first decryption key).

This function is mainly for debugging/diagnostics purposes; most config types have one single key (based on the secret key), and multi-keyed configs such as groups have their own methods for encryption/decryption that are already aware of the multiple keys.

Declaration

LIBSESSION_EXPORT unsigned char* config_get_keys(const config_object* conf, size_t* len);

Parameters

conf — [in] Pointer to the config_object object
len — [out] Pointer where the number of keys will be written (that is: the returned pointer will be to a buffer which has a size of of this value times 32).

Returns

unsigned char* — pointer to newly malloced key data (a multiple of 32 bytes); the pointer belongs to the caller and must be free()d when done with it.

`config_get_sig_pubkey`

Returns a pointer to the 32-byte Ed25519 signing pubkey, if set. Returns nullptr if there is no current signing pubkey.

Declaration

LIBSESSION_EXPORT const unsigned char* config_get_sig_pubkey(const config_object* conf);

Parameters

This endpoint takes no inputs.

Returns

pointer to the 32-byte pubkey, or NULL if not set.

`config_has_key`

Returns a pointer to the 32-byte binary key at position i. This is not null terminated (and is exactly 32 bytes long). i < config_key_count(conf) must be satisfied. Ownership of the data remains in the object (that is: the caller must not attempt to free it).

Declaration

CONST UNSIGNED CHAR* config_key(
    [in]    const config_object*    conf,
    [in]    size_t                  i
);

Parameters

conf — [in] Pointer to config_object object
i — [in] Position of key in config object

Returns

unsigned char* — binary data of the key, exactly 32 bytes and is not null terminated

`config_key_count`

Returns the number of encryption keys.

Declaration

INT config_key_count(
    [in]    const config_object*    conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

int — Number of encryption keys

`config_key_count`

Returns true if the given key is already in the keys list.

Declaration

BOOL config_has_key(
    [in]    const config_object*    conf,
    [in]    const unsigned char*    key
);

Parameters

conf — [in] Pointer to config_object object
key — [in] Pointer to the binary key object, must be 32 bytes

Returns

bool — True if key exists

`config_merge`

Merges the config object with one or more remotely obtained config strings. After this call the config object may be unchanged, complete replaced, or updated and needing a push, depending on the messages that are merged; the caller should check config_needs_push().

Declaration

INT config_merge(
    [in, out]   config_object*          conf,
    [in]        const char**            msg_hashes,
    [in]        const unsigned char**   configs,
    [in]        const size_t*           lengths,
    [in]        size_t                  count
);

Parameters

conf — [in, out] Pointer to config_object object
msg_hashes — [in] is an array of null-terminated C strings containing the hashes of the configs being provided.
configs — [in] is an array of pointers to the start of the (binary) data.
lengths — [in] is an array of lengths of the binary data
count — [in] is the length of all three arrays.

Returns

config_string_list* — pointer to the list of successfully parsed hashes; the pointer belongs to the caller and must be freed when done with it.

`config_needs_dump`

Returns true if something has changed since the last call to dump() that requires calling and saving the config_dump() data again.

Declaration

BOOL config_needs_dump(
    [in]    const config_object*          conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

bool — True if config has changed since last call to dump()

`config_needs_push`

Returns true if this config object contains updated data that has not yet been confirmed stored on the server.

Declaration

BOOL config_needs_push(
    [in]   const config_object*      conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

bool — returns true if object contains updated data

`config_old_hashes`

Obtains the known old hashes. Note that this will be empty if there are no old hashes or the config is in a dirty state (in which case these should be retrieved via the push function). Calling this function, or the push function, will clear the stored old_hashes.

The returned pointer belongs to the caller and must be freed via free() when done with it.

Declaration

CONFIG_STRING_LIST* config_old_hashes(
    [in]    const config_object*          conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

config_string_list* — pointer to the list of hashes; the pointer belongs to the caller

`config_push`

Obtains the configuration data that needs to be pushed to the server.

Generally this call should be guarded by a call to config_needs_push, however it can be used to re-obtain the current serialized config even if no push is needed (for example, if the client wants to re-submit it after a network error).

NB: The returned pointer belongs to the caller: that is, the caller MUST free() it when done with it.

Declaration

CONFIG_PUSH_DATA* config_push(
    [in, out]   config_object*      conf
);

Parameters

conf — [in] Pointer to config_object object

Returns

config_push_data* — pointer to the config object. Pointer belongs to the caller.

`config_remove_key`

Removes the given encryption/decryption key, if present. Returns true if it was found and removed, false if it was not in the key list.

Declaration

BOOL config_remove_key(
    [in]    const config_object*    conf,
    [in]    const unsigned char*    key
),

Parameters

conf — [in] Pointer to config_object object
key — [in] Pointer to the binary key object, must be 32 bytes

Returns

bool — True if key successfully removed

`config_set_sig_keys`

Sets an Ed25519 keypair pair for signing and verifying config messages. When set, this adds an additional signature for verification into the config message (after decryption) that validates a config message.

This is used in config contexts where the encryption/decryption keys are insufficient for permission verification to produce new messages, such as in groups where non-admins need to be able to decrypt group data, but are not permitted to push new group data. In such a case only the admins have the secret key with which messages can be signed; regular users can only read, but cannot write, config messages.

When a signature public key (with or without a secret key) is set the config object enters a "signing-required" mode, which has some implications worth noting: - incoming messages must contain a signature that verifies with the public key; messages without such a signature will be dropped as invalid. - because of the above, a config object cannot push config updates without the secret key: thus any attempt to modify the config message with a pubkey-only config object will raise an exception.

Declaration

LIBSESSION_EXPORT bool config_set_sig_keys(config_object* conf, const unsigned char* secret);

Parameters

secret — pointer to a 64-byte sodium-style Ed25519 "secret key" buffer (technically the seed+precomputed pubkey concatenated together) that sets both the secret key and public key.

Returns

bool — Returns true if the call succeeds, false if an error occurs.

`config_set_sig_pubkey`

Sets a Ed25519 signing pubkey which incoming messages must be signed by to be acceptable. This is intended for use when the secret key is not known (see config_set_sig_keys() to set both secret and pubkey keys together).

Declaration

LIBSESSION_EXPORT bool config_set_sig_pubkey(config_object* conf, const unsigned char* pubkey);

Parameters

pubkey — pointer to the 32-byte Ed25519 pubkey that must have signed incoming messages.

Returns

bool — Returns true if the call succeeds, false if an error occurs.

`config_storage_namespace`

Returns the numeric namespace in which config messages of this type should be stored.

Declaration

LIBSESSION_EXPORT int16_t config_storage_namespace(const config_object* conf);

Parameters

conf — [in] Pointer to config_object object

Returns

int16_t — integer of the namespace

`groups_keys_free`

Frees a config keys object created with groups_keys_init.

Declaration

LIBSESSION_EXPORT void groups_keys_free(config_group_keys* conf);

Parameters

conf — [in] Pointer to config_group_keys object

Returns

`groups_keys_storage_namespace`

Returns the numeric namespace in which config_group_keys messages should be stored.

Declaration

LIBSESSION_EXPORT int16_t groups_keys_storage_namespace(const config_group_keys* conf);

Parameters

conf — [in] Pointer to config_group_keys object

Returns

int16_t — integer of the namespace