Namespaces
	anonymous_namespace{lime_double_ratchet.cpp}

	anonymous_namespace{lime_manager.cpp}

	double_ratchet_protocol
	Group in this namespace all the functions related to building or parsing double ratchet packets.

	settings
	Hold constants definition used as settings in all components of the lime library.

	x3dh_protocol
	Group in this namespace all the functions related to building or parsing x3dh packets.

Classes
struct	AES256GCM
	AES256GCM buffers size definition. More...

struct	ARKeys
	structure to hold the keys used in asymmetric ratchet For EC only DR, it holds More...

struct	ARrKey

struct	ARrKey< Algo, true >

struct	ARrKey< Curve, false >

struct	ARsKey

struct	ARsKey< Algo, true >

struct	ARsKey< Curve, false >

class	bctbx_ECDH
	a wrapper around bctoolbox key exchange algorithms, implements the keyExchange interface More...

class	bctbx_EDDSA
	a wrapper around bctoolbox signature algorithms, implements the Signature interface More...

class	bctbx_RNG
	A wrapper around the bctoolbox Random Number Generator, implements the RNG interface. More...

struct	C255
	curve 25519 data types size definition More...

struct	C448
	curve 448-goldilocks data types size definition More...

struct	callbackUserData
	structure holding user data while waiting for callback from X3DH server response processing More...

class	Db
	Database access class. More...

class	DeviceId

class	DR
	A virtual class to define the Double Ratchet interface. More...

class	DRi
	a Double Rachet session, implements the DR interface. More...

class	DSA
	Base buffer definition for DSA data structure. More...

class	DSApair
	Key pair structure for DSA algorithm. More...

struct	EncryptionContext

struct	genericKEM

class	K
	Base buffer definition for KEM data structure. More...

class	KEM
	Key Encapsulation Mechanism interface. More...

class	keyExchange
	Key exchange interface. More...

class	Kpair
	Key pair structure for key exchange algorithm. More...

class	Lime
	Implement the abstract class LimeGeneric. More...

class	LimeGeneric
	A pure abstract class defining the API to encrypt/decrypt/manage user and its keys. More...

class	LimeManager
	Manage several Lime objects(one is needed for each local user). More...

struct	OneTimePreKey

struct	OneTimePreKey< Algo, true >

struct	OneTimePreKey< Curve, false >

struct	RecipientData
	The encrypt function input/output data structure. More...

struct	RecipientInfos
	extend the RecipientData to add a Double Ratchet session shared with the recipient More...

class	RNG
	Random number generator interface. More...

struct	sBuffer
	auto clean fixed size buffer(std::array based) More...

struct	SHA512
	SHA512 buffer size definition. More...

class	Signature
	Digital Signature interface. More...

struct	SignedPreKey

struct	SignedPreKey< Algo, true >

struct	SignedPreKey< Curve, false >

class	X
	Base buffer definition for Key Exchange data structure. More...

class	X3DH

struct	X3DH_peerBundle
	Holds everything found in a key bundle received from X3DH server. More...

class	X3DHi
	a X3DH engine, implements the X3DH interface. More...

class	Xpair
	Key pair structure for key exchange algorithm. More...

Typedefs
using	limeRandomSeedCallback = std::function< bool(const bool get, std::shared_ptr< std::vector< uint8_t >> &randomSeed)>
	define a callback function type used to get or set the random seed when performing multiple encryption (different algo) of the same message More...

using	DRChainKey = lime::sBuffer< lime::settings::DRChainKeySize >

using	SharedADBuffer = std::array< uint8_t, lime::settings::DRSessionSharedADSize >

using	limeCallback = std::function< void(const lime::CallbackReturn status, const std::string message)>
	Callback use to give a status on asynchronous operation. More...

using	limeX3DHServerResponseProcess = std::function< void(int responseCode, const std::vector< uint8_t > &responseBody)>
	Get the response from server. The external service providing secure communication to the X3DH server shall forward to lime library the server's response. More...

using	limeX3DHServerPostData = std::function< void(const std::string &url, const std::string &from, std::vector< uint8_t > &&message, const limeX3DHServerResponseProcess &reponseProcess)>
	Post a message to the X3DH server. More...

Enumerations
enum	network_state : uint8_t { network_state::done =0x00, network_state::sendSPk =0x01, network_state::sendOPk =0x02 }

enum	Xtype { Xtype::publicKey, Xtype::privateKey, Xtype::sharedSecret }
	List of data types used by key Echange algorithm. More...

enum	Ktype { Ktype::publicKey, Ktype::privateKey, Ktype::cipherText, Ktype::sharedSecret }
	List of data types used by key encapsulation mechanism algorithm. More...

enum	DSAtype { DSAtype::publicKey, DSAtype::privateKey, DSAtype::signature }
	List of data types used by Signature algorithm. More...

enum	X3DHKeyBundleFlag : uint8_t { X3DHKeyBundleFlag::noOPk =0, X3DHKeyBundleFlag::OPk =1, X3DHKeyBundleFlag::noBundle =2 }
	Set possible values for a flag in the keyBundle X3DH packet. More...

enum	CurveId : uint8_t { CurveId::unset =0, CurveId::c25519 =1, CurveId::c448 =2, CurveId::c25519k512 =3, CurveId::c25519mlk512 =4, CurveId::c448mlk1024 =5 }

enum	EncryptionPolicy { EncryptionPolicy::DRMessage, EncryptionPolicy::cipherMessage, EncryptionPolicy::optimizeUploadSize, EncryptionPolicy::optimizeGlobalBandwidth }

enum	PeerDeviceStatus : uint8_t { PeerDeviceStatus::untrusted =0, PeerDeviceStatus::trusted =1, PeerDeviceStatus::unsafe =2, PeerDeviceStatus::fail, PeerDeviceStatus::unknown }

enum	CallbackReturn : uint8_t { CallbackReturn::success, CallbackReturn::fail }

Functions
std::shared_ptr< LimeGeneric >	insert_LimeUser (std::shared_ptr< lime::Db > localStorage, const DeviceId &deviceId, const std::string &url, const uint16_t OPkInitialBatchSize, const limeX3DHServerPostData &X3DH_post_data, const std::shared_ptr< limeCallback > callback)
	: Insert user in database and return a pointer to the control class instanciating the appropriate Lime children class More...

std::shared_ptr< LimeGeneric >	load_LimeUser (std::shared_ptr< lime::Db > localStorage, const DeviceId &deviceId, const limeX3DHServerPostData &X3DH_post_data, const bool allStatus)
	: Load user from database and return a pointer to the control class instanciating the appropriate Lime children class More...

std::shared_ptr< RNG >	make_RNG ()

template<typename Curve >
bctbx_EDDSAContext_t *	bctbx_EDDSAInit (void)

template<typename Curve >
bctbx_ECDHContext_t *	bctbx_ECDHInit (void)

template<typename Curve >
std::shared_ptr< keyExchange< Curve > >	make_keyExchange ()

template<typename Curve >
std::shared_ptr< Signature< Curve > >	make_Signature ()

template<typename hashAlgo >
void	HMAC (const uint8_t const key, const size_t keySize, const uint8_t const input, const size_t inputSize, uint8_t *hash, size_t hashSize)
	templated HMAC More...

template<>
void	HMAC< SHA512 > (const uint8_t const key, const size_t keySize, const uint8_t const input, const size_t inputSize, uint8_t *hash, size_t hashSize)

template<typename hashAlgo >
void	HMAC_KDF (const uint8_t const salt, const size_t saltSize, const uint8_t const ikm, const size_t ikmSize, const char info, const size_t infoSize, uint8_t output, size_t outputSize)
	HKDF as described in RFC5869. More...

template<>
void	HMAC_KDF< SHA512 > (const uint8_t const salt, const size_t saltSize, const uint8_t const ikm, const size_t ikmSize, const char info, const size_t infoSize, uint8_t output, size_t outputSize)

template<typename AEADAlgo >
void	AEAD_encrypt (const uint8_t const key, const size_t keySize, const uint8_t const IV, const size_t IVSize, const uint8_t const plain, const size_t plainSize, const uint8_t const AD, const size_t ADSize, uint8_t tag, const size_t tagSize, uint8_t cipher)
	Encrypt and tag using scheme given as template parameter. More...

template<typename AEADAlgo >
bool	AEAD_decrypt (const uint8_t const key, const size_t keySize, const uint8_t const IV, const size_t IVSize, const uint8_t const cipher, const size_t cipherSize, const uint8_t const AD, const size_t ADSize, const uint8_t const tag, const size_t tagSize, uint8_t plain)
	Authenticate and Decrypt using scheme given as template parameter. More...

template<>
void	AEAD_encrypt< AES256GCM > (const uint8_t const key, const size_t keySize, const uint8_t const IV, const size_t IVSize, const uint8_t const plain, const size_t plainSize, const uint8_t const AD, const size_t ADSize, uint8_t tag, const size_t tagSize, uint8_t cipher)

template<>
bool	AEAD_decrypt< AES256GCM > (const uint8_t const key, const size_t keySize, const uint8_t const IV, const size_t IVSize, const uint8_t const cipher, const size_t cipherSize, const uint8_t const AD, const size_t ADSize, const uint8_t const tag, const size_t tagSize, uint8_t plain)

void	cleanBuffer (uint8_t *buffer, size_t size)
	force a buffer values to zero in a way that shall prevent the compiler from optimizing it out More...

template<typename Algo >
std::shared_ptr< KEM< Algo > >	make_KEM ()

template<typename Algo >
std::shared_ptr< DR >	make_DR_from_localStorage (std::shared_ptr< lime::Db > localStorage, long sessionId, std::shared_ptr< RNG > RNG_context)

template<typename Algo >
std::shared_ptr< DR >	make_DR_for_sender (std::shared_ptr< lime::Db > localStorage, const DRChainKey &SK, const SharedADBuffer &AD, const ARrKey< Algo > &peerPublicKey, long int peerDid, const std::string &peerDeviceId, const DSA< typename Algo::EC, lime::DSAtype::publicKey > &peerIk, long int selfDid, const std::vector< uint8_t > &X3DH_initMessage, std::shared_ptr< RNG > RNG_context)

template<typename Algo >
std::shared_ptr< DR >	make_DR_for_receiver (std::shared_ptr< lime::Db > localStorage, const DRChainKey &SK, const SharedADBuffer &AD, const ARsKey< Algo > &selfKeyPair, long int peerDid, const std::string &peerDeviceId, const uint32_t OPk_id, const DSA< typename Algo::EC, lime::DSAtype::publicKey > &peerIk, long int selfDeviceId, std::shared_ptr< RNG > RNG_context)

void	encryptMessage (std::vector< RecipientInfos > &recipients, const std::vector< uint8_t > &plaintext, const std::vector< uint8_t > &recipientUserId, const std::string &sourceDeviceId, std::vector< uint8_t > &cipherMessage, const lime::EncryptionPolicy encryptionPolicy, std::shared_ptr< lime::Db > localStorage, const std::shared_ptr< limeRandomSeedCallback > randomSeedCallback)
	Encrypt a message to all recipients, identified by their device id. More...

std::shared_ptr< DR >	decryptMessage (const std::string &sourceDeviceId, const std::string &recipientDeviceId, const std::vector< uint8_t > &recipientUserId, std::vector< std::shared_ptr< DR >> &DRSessions, const std::vector< uint8_t > &DRmessage, const std::vector< uint8_t > &cipherMessage, std::vector< uint8_t > &plaintext)
	Decrypt a message. More...

void	hexStr (std::ostringstream &os, const uint8_t *data, size_t len, size_t digest)

lime::CurveId	string2CurveId (const std::string &algo)

std::string	CurveId2String (const lime::CurveId algo)

std::string	CurveId2String (const std::vector< lime::CurveId > algos, const std::string separator)

std::string	PeerDeviceStatus2String (const lime::PeerDeviceStatus status)

bool	lime_is_PQ_available (void)

template<typename Algo >
std::shared_ptr< X3DH >	make_X3DH (std::shared_ptr< lime::Db > localStorage, const std::string &selfDeviceId, const std::string &X3DHServerURL, const limeX3DHServerPostData &X3DH_post_data, std::shared_ptr< RNG > RNG_context, const long Uid)

Typedef Documentation

using lime::DRChainKey = typedef lime::sBuffer<lime::settings::DRChainKeySize>

Double Rachet chain keys: Root key, Sender and receiver keys are 32 bytes arrays

using lime::limeCallback = typedef std::function<void(const lime::CallbackReturn status, const std::string message)>

Callback use to give a status on asynchronous operation.

it returns a code and may return a string (could actually be empty) to detail what's happening callback is used on every operation possibly involving a connection to X3DH server: create_user, delete_user, encrypt and update

Parameters

[in]	status	success or fail
[in]	message	in case of failure, an explanation, it may be empty

using lime::limeRandomSeedCallback = typedef std::function<bool(const bool get, std::shared_ptr<std::vector<uint8_t>> &randomSeed)>

define a callback function type used to get or set the random seed when performing multiple encryption (different algo) of the same message

Parameters

[in]	get	when true try to get the RandomSeed and cipherText, if false set the RandomSeed anf CipherText
[out]	randomSeed	a buffer holding the randomSeed

Returns: false on get when data was not set before

using lime::limeX3DHServerPostData = typedef std::function<void(const std::string &url, const std::string &from, std::vector<uint8_t> &&message, const limeX3DHServerResponseProcess &reponseProcess)>

Post a message to the X3DH server.

Parameters

[in]	url	X3DH server's URL
[in]	from	User identification on X3DH server (which shall challenge for password digest, this is not however part of lime)
[in]	message	The message to post to the X3DH server
[in]	responseProcess	Function to be called with server's response

using lime::limeX3DHServerResponseProcess = typedef std::function<void(int responseCode, const std::vector<uint8_t> &responseBody)>

Get the response from server. The external service providing secure communication to the X3DH server shall forward to lime library the server's response.

Parameters

[in]	responseCode	Lime expects communication with server to be over HTTPS, this shall be the response code. Lime expects 200 for successfull response from server. Any other response code is treated as an error and response ignored(but it is still usefull to forward it in order to perform internal cleaning)
[in]	responseBody	The actual response from X3DH server

using lime::SharedADBuffer = typedef std::array<uint8_t, lime::settings::DRSessionSharedADSize>

Shared Associated Data : stored at session initialisation, given by upper level(X3DH), shall be derived from Identity and Identity keys of sender and recipient, fixed size for storage convenience

Enumeration Type Documentation

enum lime::CallbackReturn : uint8_t

strong

what a Lime callback could possibly say

Enumerator
success	operation completed successfully
fail	operation failed, we shall have an explanation string too

enum lime::CurveId : uint8_t

strong

Identifies the elliptic curve used in lime, the values assigned are used in localStorage and X3DH server so do not modify it or we'll loose sync with existing DB and X3DH server

Enumerator
unset	used as default to detected incorrect behavior
c25519	Curve 25519
c448	Curve 448-goldilocks
c25519k512	Hybrid KEM kyber512/curve 25519
c25519mlk512	Hybrid MLKEM 512/curve 25519
c448mlk1024	Hybrid MLKEM 1024/curve 448

enum lime::DSAtype

strong

List of data types used by Signature algorithm.

public key, private key and signature

Enumerator
publicKey
privateKey
signature

enum lime::EncryptionPolicy

strong

Manage the encryption policy : how is the user's plaintext encrypted

Enumerator
DRMessage	the plaintext input is encrypted inside the Double Ratchet message (each recipient get a different encryption): not optimal for messages with numerous recipient
cipherMessage	the plaintext input is encrypted with a random key and this random key is encrypted to each participant inside the Double Ratchet message(for a single recipient the overhead is 48 bytes)
optimizeUploadSize	optimize upload size: encrypt in DR message if plaintext is short enougth to beat the overhead introduced by cipher message scheme, otherwise use cipher message. Selection is made on upload size only. This is the default policy used
optimizeGlobalBandwidth	optimize bandwith usage: encrypt in DR message if plaintext is short enougth to beat the overhead introduced by cipher message scheme, otherwise use cipher message. Selection is made on uploadand download (from server to recipients) sizes added.

enum lime::Ktype

strong

List of data types used by key encapsulation mechanism algorithm.

public key, private key, cipher text and shared secret

Enumerator
publicKey
privateKey
cipherText
sharedSecret

enum lime::network_state : uint8_t

strong

Enumerator
done
sendSPk
sendOPk

enum lime::PeerDeviceStatus : uint8_t

strong

A peer device status returned after encrypt, decrypt or when directly asking for the peer device status to spot new devices and give information on our trust on this device The values explicitely mapped to specific integers(untrusted, trusted, unsafe) are stored in local storage as integer Do not modify the mapping or we will loose backward compatibility with existing databases

Enumerator
untrusted	we know this device but do not trust it, that information shall be displayed to the end user, a colour code shall be enough
trusted	this peer device already got its public identity key validated, that information shall be displayed to the end user too
unsafe	this status is a helper for the library user. It is used only by the peerDeviceStatus accessor functions
fail	when returned by decrypt : we could not decrypt the incoming message when returned by encrypt in the peerStatus: we could not encrypt to this recipient(probably because it does not published keys on the X3DH server)
unknown	when returned after encryption or decryption, means it is the first time we communicate with this device (and thus create a DR session with it) when returned by a get_peerDeviceStatus: this device is not in localStorage

enum lime::X3DHKeyBundleFlag : uint8_t

strong

Set possible values for a flag in the keyBundle X3DH packet.

Note: Do not modify values or we'll loose sync with existing X3DH server

Enumerator
noOPk	This bundle does not contain an OPk
OPk	This bundle contains an OPk
noBundle

enum lime::Xtype

strong

List of data types used by key Echange algorithm.

public key, private key and shared secret

Enumerator
publicKey
privateKey
sharedSecret

Function Documentation

template<typename AEADAlgo >

bool lime::AEAD_decrypt	(	const uint8_t *const	key,
		const size_t	keySize,
		const uint8_t *const	IV,
		const size_t	IVSize,
		const uint8_t *const	cipher,
		const size_t	cipherSize,
		const uint8_t *const	AD,
		const size_t	ADSize,
		const uint8_t *const	tag,
		const size_t	tagSize,
		uint8_t *	plain
	)

Authenticate and Decrypt using scheme given as template parameter.

Parameters

[in]	key	Encryption key
[in]	keySize	Key buffer length, it must match the selected AEAD scheme or an exception is generated
[in]	IV	Buffer holding the initialisation vector
[in]	IVSize	Initialisation vector length in bytes
[in]	cipher	Buffer holding the data to be decrypted
[in]	cipherSize	Length in bytes of buffer to be decrypted
[in]	AD	Buffer holding additional data to be used in tag computation
[in]	ADSize	Additional data length in bytes
[in]	tag	Buffer holding the authentication tag
[in]	tagSize	Length for the generated tag, it must match the selected AEAD scheme or an exception is generated
[out]	plain	buffer holding the plain output, shall be at least the length of plainText buffer

Returns: true if authentication tag match and decryption was successful

template<>

bool lime::AEAD_decrypt< AES256GCM >	(	const uint8_t *const	key,
		const size_t	keySize,
		const uint8_t *const	IV,
		const size_t	IVSize,
		const uint8_t *const	cipher,
		const size_t	cipherSize,
		const uint8_t *const	AD,
		const size_t	ADSize,
		const uint8_t *const	tag,
		const size_t	tagSize,
		uint8_t *	plain
	)

template<typename AEADAlgo >

void lime::AEAD_encrypt	(	const uint8_t *const	key,
		const size_t	keySize,
		const uint8_t *const	IV,
		const size_t	IVSize,
		const uint8_t *const	plain,
		const size_t	plainSize,
		const uint8_t *const	AD,
		const size_t	ADSize,
		uint8_t *	tag,
		const size_t	tagSize,
		uint8_t *	cipher
	)

Encrypt and tag using scheme given as template parameter.

Parameters

[in]	key	Encryption key
[in]	keySize	Key buffer length, it must match the selected AEAD scheme or an exception is generated
[in]	IV	Buffer holding the initialisation vector
[in]	IVSize	Initialisation vector length in bytes
[in]	plain	buffer to be encrypted
[in]	plainSize	Length in bytes of buffer to be encrypted
[in]	AD	Buffer holding additional data to be used in tag computation
[in]	ADSize	Additional data length in bytes
[out]	tag	Buffer holding the generated tag
[in]	tagSize	Requested length for the generated tag, it must match the selected AEAD scheme or an exception is generated
[out]	cipher	Buffer holding the output, shall be at least the length of plainText buffer

template<>

void lime::AEAD_encrypt< AES256GCM >	(	const uint8_t *const	key,
		const size_t	keySize,
		const uint8_t *const	IV,
		const size_t	IVSize,
		const uint8_t *const	plain,
		const size_t	plainSize,
		const uint8_t *const	AD,
		const size_t	ADSize,
		uint8_t *	tag,
		const size_t	tagSize,
		uint8_t *	cipher
	)

template<typename Curve >

bctbx_ECDHContext_t* lime::bctbx_ECDHInit ( void )

template<typename Curve >

bctbx_EDDSAContext_t* lime::bctbx_EDDSAInit ( void )

void lime::cleanBuffer	(	uint8_t *	buffer,
		size_t	size
	)

force a buffer values to zero in a way that shall prevent the compiler from optimizing it out

Parameters

[in,out]	buffer	the buffer to be cleared
[in]	size	buffer size

std::string lime::CurveId2String ( const lime::CurveId algo )

convert a CurveId into a string

Parameters

[in] algo the CurveId to be converted

Returns: the matching string, "unset" if the CurveId is invalid

std::string lime::CurveId2String	(	const std::vector< lime::CurveId >	algos,
		const std::string	separator = `","`
	)

convert a vector of CurveId into a comma separated string list

Parameters

[in]	algos	the vector of CurveId to be converted
[in]	separator	when specified use this separator, comma is the default

Returns: a CSV list in a string

std::shared_ptr< DR > lime::decryptMessage	(	const std::string &	sourceDeviceId,
		const std::string &	recipientDeviceId,
		const std::vector< uint8_t > &	recipientUserId,
		std::vector< std::shared_ptr< DR >> &	DRSessions,
		const std::vector< uint8_t > &	DRmessage,
		const std::vector< uint8_t > &	cipherMessage,
		std::vector< uint8_t > &	plaintext
	)

Decrypt a message.

Decrypts the DR message and if applicable and the DR message was successfully decrypted, decrypt the cipherMessage

Parameters

[in]	sourceDeviceId	the device Id of sender(gruu)
[in]	recipientDeviceId	the recipient ID, specific to current device(gruu)
[in]	recipientUserId	the recipient ID, not specific to a device(could be a sip-uri) or a user(could be a group sip-uri)
[in,out]	DRSessions	list of DR Sessions linked to sender device, first one shall be the one registered as active
[out]	DRmessage	Double Ratcher message holding as payload either the encrypted plaintext or the random key used to encrypt it encrypted by the DR session
[out]	cipherMessage	if not zero lenght, plain text encrypted with a random generated key(and IV)
[out]	plaintext	decrypted message

Returns: a shared pointer towards the session used to decrypt, nullptr if we couldn't find one to do it

void lime::encryptMessage	(	std::vector< RecipientInfos > &	recipients,
		const std::vector< uint8_t > &	plaintext,
		const std::vector< uint8_t > &	recipientUserId,
		const std::string &	sourceDeviceId,
		std::vector< uint8_t > &	cipherMessage,
		const lime::EncryptionPolicy	encryptionPolicy,
		std::shared_ptr< lime::Db >	localStorage,
		const std::shared_ptr< limeRandomSeedCallback >	randomSeedCallback
	)

Encrypt a message to all recipients, identified by their device id.

The plaintext is first encrypted by one randomly generated key using aes-gcm The key and IV are then encrypted with DR Session specific to each device

Parameters

[in,out]	recipients	vector of recipients device id(gruu) and linked DR Session, DR Session are modified by the encryption The recipients struct also hold after encryption the double ratchet message targeted to that particular recipient
[in]	plaintext	data to be encrypted
[in]	recipientUserId	the recipient ID, not specific to a device(could be a sip-uri) or a user(could be a group sip-uri)
[in]	sourceDeviceId	the Id of sender device(gruu)
[out]	cipherMessage	message encrypted with a random generated key(and IV). May be an empty buffer depending on encryptionPolicy, recipients and plaintext characteristics
[in]	encryptionPolicy	select how to manage the encryption: direct use of Double Ratchet message or encrypt in the cipher message and use the DR message to share the cipher message key default is optimized output size mode.
[in]	localStorage	pointer to the local storage, used to get lock and start transaction on all DR sessions at once
[in]	randomSeedCallback	when provided and encryption policy ends to be cipherMessage, allow to set/get the random seed and cipher text tag this is needed to encrypt the same message with differents lime users (for multi base algorithm purpose)

void lime::hexStr	(	std::ostringstream &	os,
		const uint8_t *	data,
		size_t	len,
		size_t	digest = `0`
	)

convert a byte buffer into hexadecimal string if digest is > 0, only print the first and last digest bytes

template<typename hashAlgo >

void lime::HMAC	(	const uint8_t *const	key,
		const size_t	keySize,
		const uint8_t *const	input,
		const size_t	inputSize,
		uint8_t *	hash,
		size_t	hashSize
	)

templated HMAC

Template Parameters

hashAlgo the hash algorithm used (only SHA512 available for now)

Parameters

[in]	key	HMAC key
[in]	keySize	previous buffer size
[in]	input	HMAC input
[in]	inputSize	previous buffer size
[out]	hash	pointer to the output, this buffer must be able to hold as much data as requested
[in]	hashSize	amount of expected data, if more than selected Hash algorithm can compute, silently ignored and maximum output size is generated

template<>

void lime::HMAC< SHA512 >	(	const uint8_t *const	key,
		const size_t	keySize,
		const uint8_t *const	input,
		const size_t	inputSize,
		uint8_t *	hash,
		size_t	hashSize
	)

template<typename hashAlgo >

void lime::HMAC_KDF	(	const uint8_t *const	salt,
		const size_t	saltSize,
		const uint8_t *const	ikm,
		const size_t	ikmSize,
		const char *	info,
		const size_t	infoSize,
		uint8_t *	output,
		size_t	outputSize
	)

HKDF as described in RFC5869.

Compute:: 1 PRK = HMAC-Hash(salt, IKM)

2

3 N = ceil(L/HashLen)

4 T = T(1) | T(2) | T(3) | ... | T(N)

5 OKM = first L octets of T

6

7 where:

8 T(0) = empty string (zero length)

9 T(1) = HMAC-Hash(PRK, T(0) | info | 0x01)

10 T(2) = HMAC-Hash(PRK, T(1) | info | 0x02)

11 T(3) = HMAC-Hash(PRK, T(2) | info | 0x03)

12 ...

Template Parameters

hashAlgo the hash algorithm to use (SHA512 available for now)

Parameters

[in]	salt	salt
[in]	saltSize	saltSize
[in]	ikm	input key material
[in]	ikmSize	input key material size
[in]	info	a info string or buffer
[in]	infoSize	the info buffer size
[out]	okm	output key material
[in]	okmSize	requested amount of data, okm buffer must be able to hold it. (L in the RFC doc)

template<>

void lime::HMAC_KDF< SHA512 >	(	const uint8_t *const	salt,
		const size_t	saltSize,
		const uint8_t *const	ikm,
		const size_t	ikmSize,
		const char *	info,
		const size_t	infoSize,
		uint8_t *	output,
		size_t	outputSize
	)

std::shared_ptr< LimeGeneric > lime::insert_LimeUser	(	std::shared_ptr< lime::Db >	localStorage,
		const DeviceId &	deviceId,
		const std::string &	url,
		const uint16_t	OPkInitialBatchSize,
		const limeX3DHServerPostData &	X3DH_post_data,
		const std::shared_ptr< limeCallback >	callback
	)

: Insert user in database and return a pointer to the control class instanciating the appropriate Lime children class

Once created a user cannot be modified, insertion of existing deviceId will raise an exception.

Parameters

[in]	localStorage	Database access
[in]	deviceId	User to lookup in DB, deviceId shall be the GRUU and a base algo
[in]	url	URL of X3DH key server to be used to publish our keys
[in]	OPkInitialBatchSize	Number of OPks in the first batch uploaded to X3DH server
[in]	X3DH_post_data	A function used to communicate with the X3DH server
[in]	callback	To provide caller the operation result

Returns: a pointer to the LimeGeneric class allowing access to API declared in lime_lime.hpp

bool lime::lime_is_PQ_available ( void )

Returns: true when PQ algorithms are available

std::shared_ptr< LimeGeneric > lime::load_LimeUser	(	std::shared_ptr< lime::Db >	localStorage,
		const DeviceId &	deviceId,
		const limeX3DHServerPostData &	X3DH_post_data,
		const bool	allStatus
	)

: Load user from database and return a pointer to the control class instanciating the appropriate Lime children class

Fail to find the user will raise an exception If allStatus flag is set to false (default value), raise an exception on inactive users otherwise load inactive user.

Parameters

[in]	localStorage	Database access
[in]	deviceId	User to lookup in DB, deviceId shall be the GRUU and a base algo
[in]	X3DH_post_data	A function used to communicate with the X3DH server
[in]	allStatus	allow loading of inactive user if set to true

Returns: a pointer to the LimeGeneric class allowing access to API declared in lime_lime.hpp

template<typename Algo >

std::shared_ptr<DR> lime::make_DR_for_receiver	(	std::shared_ptr< lime::Db >	localStorage,
		const DRChainKey &	SK,
		const SharedADBuffer &	AD,
		const ARsKey< Algo > &	selfKeyPair,
		long int	peerDid,
		const std::string &	peerDeviceId,
		const uint32_t	OPk_id,
		const DSA< typename Algo::EC, lime::DSAtype::publicKey > &	peerIk,
		long int	selfDeviceId,
		std::shared_ptr< RNG >	RNG_context
	)

template<typename Algo >

std::shared_ptr<DR> lime::make_DR_for_sender	(	std::shared_ptr< lime::Db >	localStorage,
		const DRChainKey &	SK,
		const SharedADBuffer &	AD,
		const ARrKey< Algo > &	peerPublicKey,
		long int	peerDid,
		const std::string &	peerDeviceId,
		const DSA< typename Algo::EC, lime::DSAtype::publicKey > &	peerIk,
		long int	selfDid,
		const std::vector< uint8_t > &	X3DH_initMessage,
		std::shared_ptr< RNG >	RNG_context
	)

template<typename Algo >

std::shared_ptr< DR > lime::make_DR_from_localStorage	(	std::shared_ptr< lime::Db >	localStorage,
		long	sessionId,
		std::shared_ptr< RNG >	RNG_context
	)

template<typename Algo >

std::shared_ptr<KEM<Algo> > lime::make_KEM ( )

template<typename Curve >

std::shared_ptr< keyExchange< Curve > > lime::make_keyExchange ( )

std::shared_ptr< RNG > lime::make_RNG ( )

template<typename Curve >

std::shared_ptr< Signature< Curve > > lime::make_Signature ( )

template<typename Algo >

std::shared_ptr< X3DH > lime::make_X3DH	(	std::shared_ptr< lime::Db >	localStorage,
		const std::string &	selfDeviceId,
		const std::string &	X3DHServerURL,
		const limeX3DHServerPostData &	X3DH_post_data,
		std::shared_ptr< RNG >	RNG_context,
		const long	Uid = `0`
	)

Factory functions : Create an X3DH pointer - instanciate the correct type matching the given template param

Parameters

[in,out]	localStorage	pointer to DB accessor
[in]	deviceId	device Id(shall be GRUU), stored in the structure
[in]	url	URL of the X3DH key server used to publish our keys(retrieved from DB)
[in]	X3DH_post_data	A function used to communicate with the X3DH server
[in]	Uid	the DB internal Id for this user, speed up DB operations by holding it in object, when 0: create the user

Returns: pointer to a generic X3DH object

std::string lime::PeerDeviceStatus2String ( const lime::PeerDeviceStatus status )

convert a PeerDeviceStatus into a string

Parameters

[in] status the peerDeviceStatus to be converted

Returns: the matching string, "invalid" if the CurveId is invalid

lime::CurveId lime::string2CurveId ( const std::string & algo )

convert a string to its curveId equivalent

Parameters

[in] algo the string to be converted. Valid inputs are c25519, c448, c25519k512, c25519mlk512, c448mlk1024

Returns: the converted id, CurveId::unset on invalid input

Namespaces

Classes

Typedefs

Enumerations

Functions

Typedef Documentation

Enumeration Type Documentation

Function Documentation