Implement the abstract class LimeGeneric. More...

Inheritance diagram for lime::Lime< Curve >:

Public Member Functions
	Lime (std::shared_ptr< lime::Db > localStorage, const std::string &deviceId, const std::string &url, const limeX3DHServerPostData &X3DH_post_data, const long int Uid=0)
	Load or Create user constructor. More...

	~Lime ()

	Lime (Lime< Curve > &a)=delete

Lime< Curve > &	operator= (Lime< Curve > &a)=delete

void	publish_user (const std::shared_ptr< limeCallback > callback, const uint16_t OPkInitialBatchSize) override
	Publish on X3DH server the user, it is performed just after creation in local storage this will, on success, trigger generation and sending of SPk and OPks for our new user. More...

void	delete_user (const std::shared_ptr< limeCallback > callback) override
	Delete user from local Storage and from X3DH server. More...

void	delete_peerDevice (const std::string &peerDeviceId) override
	Purge cached sessions for a given peer Device (used when a peer device is being deleted) More...

void	update_SPk (const std::shared_ptr< limeCallback > callback) override
	Check if the current SPk needs to be updated, if yes, generate a new one and publish it on server. More...

void	update_OPk (const std::shared_ptr< limeCallback > callback, uint16_t OPkServerLowLimit, uint16_t OPkBatchSize) override
	check if we shall upload more OPks on X3DH server More...

void	get_Ik (std::vector< uint8_t > &Ik) override
	Retrieve self public Identity key. More...

void	encrypt (std::shared_ptr< lime::EncryptionContext > encryptionContext, const std::shared_ptr< limeCallback > callback, const std::shared_ptr< limeRandomSeedCallback > randomSeedCallback) override
	Encrypt a buffer (text or file) for a given list of recipient devices. More...

lime::PeerDeviceStatus	decrypt (const std::vector< uint8_t > &recipientUserId, const std::string &senderDeviceId, const std::vector< uint8_t > &DRmessage, const std::vector< uint8_t > &cipherMessage, std::vector< uint8_t > &plainMessage) override
	Decrypt the given message. More...

void	set_x3dhServerUrl (const std::string &x3dhServerUrl) override
	Set the X3DH key server URL for this identified user. More...

std::string	get_x3dhServerUrl () override
	Get the X3DH key server URL for this identified user. More...

void	stale_sessions (const std::string &peerDeviceId) override
	Stale all sessions between localDeviceId and peerDevice. If peerDevice keep using this session to encrypt and we decrypt with success, the session will be reactivated but to encrypt a message to this peerDevice, a new session will be created. If no session is active between the given device, this call has no effect. More...

void	processEncryptionQueue (void) override
	Check if we have queued encryption to process, if yes, do it. More...

void	DRcache_delete (const std::string &deviceId) override
	delete an entry (if found) from the DR session cache More...

void	DRcache_insert (const std::string &deviceId, std::shared_ptr< DR > DRsession) override
	insert an entry in the DR session cache if an entry with the same key already exists, do nothing More...

std::shared_ptr< X3DH >	get_X3DH (void) override
	accessor to the internal X3DH engine More...

std::unique_lock< std::mutex >	lock (void) override

Public Member Functions inherited from lime::LimeGeneric
virtual	~LimeGeneric ()

Detailed Description

template<typename Curve>
class lime::Lime< Curve >

Implement the abstract class LimeGeneric.

Template Parameters

Curve The elliptic curve to use: C255 or C448

Constructor & Destructor Documentation

template<typename Curve >

lime::Lime< Curve >::Lime	(	std::shared_ptr< lime::Db >	localStorage,
		const std::string &	deviceId,
		const std::string &	url,
		const limeX3DHServerPostData &	X3DH_post_data,
		const long int	Uid = `0`
	)

Load or Create user constructor.

before calling this constructor, user existence in DB is checked and its Uid retrieved

with an Uid : load the user infos in Lime/X3DH object
with an Uid to 0 : create the user en DB (only its identity) and set its data in Lime/X3DH object. The publish_user will the create the needed keys (SPk, OPk) and upload everything to the server

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 DB. If set to 0 -> create the user

template<typename Curve >

lime::Lime< Curve >::~Lime ( )

template<typename Curve>

lime::Lime< Curve >::Lime ( Lime< Curve > & a )

delete

Member Function Documentation

template<typename Curve >

lime::PeerDeviceStatus lime::Lime< Curve >::decrypt	(	const std::vector< uint8_t > &	recipientUserId,
		const std::string &	senderDeviceId,
		const std::vector< uint8_t > &	DRmessage,
		const std::vector< uint8_t > &	cipherMessage,
		std::vector< uint8_t > &	plainMessage
	)

overridevirtual

Decrypt the given message.

Parameters

[in]	recipientUserId	the Id of intended recipient, shall be a sip:uri of user or conference, is used as associated data to ensure no-one can mess with intended recipient it is not necessarily the sip:uri base of the GRUU as this could be a message from alice first device intended to bob being decrypted on alice second device
[in]	senderDeviceId	the device Id (GRUU) of the message sender
[in]	DRmessage	the Double Ratchet message targeted to current device
[in]	cipherMessage	part of cipher routed to all recipient devices(it may be actually empty depending on sender encryption policy and message characteristics)
[out]	plainMessage	the output buffer

Returns: true if the decryption is successfull, false otherwise

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::delete_peerDevice ( const std::string & peerDeviceId )

overridevirtual

Purge cached sessions for a given peer Device (used when a peer device is being deleted)

Parameters

[in] peerDeviceId The peer device to remove from cache

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::delete_user ( const std::shared_ptr< limeCallback > callback )

overridevirtual

Delete user from local Storage and from X3DH server.

Parameters

[in] callback call when completed

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::DRcache_delete ( const std::string & deviceId )

overridevirtual

delete an entry (if found) from the DR session cache

Parameters

[in] deviceId the key in the DR session cache

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::DRcache_insert	(	const std::string &	deviceId,
		std::shared_ptr< DR >	DRsession
	)

overridevirtual

insert an entry in the DR session cache if an entry with the same key already exists, do nothing

Parameters

[in]	deviceId	the key in the DR session cache
[in]	DRsession	the DR session to insert

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::encrypt	(	std::shared_ptr< lime::EncryptionContext >	encryptionContext,
		const std::shared_ptr< limeCallback >	callback,
		const std::shared_ptr< limeRandomSeedCallback >	randomSeedCallback
	)

overridevirtual

Encrypt a buffer (text or file) for a given list of recipient devices.

Clarification on recipients:

recipients information needed are a list of the device Id and one userId. The device Id shall be their GRUU while the userId is a sip:uri.

recipient User Id is used to identify the actual intended recipient. Example: alice have two devices and is signed up on a conference having bob and claire as other members. The recipientUserId will be the conference sip:uri and device list will include:

alice other device
bob devices
claire devices If Alice write to Bob only, the recipientUserId will be bob sip:uri and recipient devices list :
alice other device
bob devices

In all cases, the identified source of the message will be the localDeviceId

If the X3DH server can't provide keys for a peer device, its status is set to fail and its DRmessage is empty. Other devices get their encrypted message If no peer device could get encrypted for all of them are missing keys on the X3DH server, the callback will be called with fail exit status

Note: encryptionContext is shared pointers as the process being asynchronous, the ownership will be taken internally exempting caller to manage the buffers.

Parameters

[in,out]	encryptionContext	This context must persist during asynchronous calls to the lime X3DH server. It holds associated Data (recipientUserId or other) is used as associated data to ensure no-one can mess with intended recipient (when the recipientUserId is given) recipients a list of RecipientData holding: the recipient device Id(GRUU) an empty buffer to store the DRmessage which must then be routed to that recipient the peer Status. If peerStatus is set to fail, this entry is ignored otherwise the peerStatus is set by the encrypt, see PeerDeviceStatus definition for details plainMessage: a buffer holding the message to encrypt, can be text or data. cipherMessage: points to the buffer to store the encrypted message which must be routed to all recipients(if one is produced, depends on encryption policy) 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 upload size mode.
[in]	callback	Performing encryption may involve the X3DH server and is thus asynchronous, when the operation is completed, this callback will be called giving the exit status and an error message in case of failure. It is advised to capture a copy of cipherMessage and recipients shared_ptr in this callback so they can access the output of encryption as it won't be part of the callback parameters.
[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)

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::get_Ik ( std::vector< uint8_t > & Ik )

overridevirtual

Retrieve self public Identity key.

Parameters

[out] Ik the public EdDSA formatted Identity key

Implements lime::LimeGeneric.

template<typename Curve>

std::shared_ptr<X3DH> lime::Lime< Curve >::get_X3DH ( void )

inlineoverridevirtual

accessor to the internal X3DH engine

Returns: the internal X3DH engine

Implements lime::LimeGeneric.

template<typename Curve >

std::string lime::Lime< Curve >::get_x3dhServerUrl ( )

overridevirtual

Get the X3DH key server URL for this identified user.

Returns: The complete url(including port) of the X3DH key server

Implements lime::LimeGeneric.

template<typename Curve>

std::unique_lock<std::mutex> lime::Lime< Curve >::lock ( void )

inlineoverridevirtual

Get the lock on the Lime object ressources (mostly DR session cache and encryption queue This is a unique lock, release it by destroying the object

Implements lime::LimeGeneric.

template<typename Curve>

Lime<Curve>& lime::Lime< Curve >::operator= ( Lime< Curve > & a )

delete

template<typename Curve >

void lime::Lime< Curve >::processEncryptionQueue ( void )

overridevirtual

Check if we have queued encryption to process, if yes, do it.

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::publish_user	(	const std::shared_ptr< limeCallback >	callback,
		const uint16_t	OPkInitialBatchSize
	)

overridevirtual

Publish on X3DH server the user, it is performed just after creation in local storage this will, on success, trigger generation and sending of SPk and OPks for our new user.

Parameters

[in]	callback	call when completed
[in]	OPkInitialBatchSize	Number of OPks in the first batch uploaded to X3DH server

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::set_x3dhServerUrl ( const std::string & x3dhServerUrl )

overridevirtual

Set the X3DH key server URL for this identified user.

Parameters

[in] x3dhServerUrl The complete url(including port) of the X3DH key server

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::stale_sessions ( const std::string & peerDeviceId )

overridevirtual

Stale all sessions between localDeviceId and peerDevice. If peerDevice keep using this session to encrypt and we decrypt with success, the session will be reactivated but to encrypt a message to this peerDevice, a new session will be created. If no session is active between the given device, this call has no effect.

Parameters

[in] peerDeviceId The device Id of peer, shall be its GRUU

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::update_OPk	(	const std::shared_ptr< limeCallback >	callback,
		uint16_t	OPkServerLowLimit,
		uint16_t	OPkBatchSize
	)

overridevirtual

check if we shall upload more OPks on X3DH server

ask server four our keys (returns the count and all their Ids)
check if it's under the low limit, if yes, generate a batch of keys and upload them

Parameters

[in]	callback	Called with success or failure when operation is completed.
[in]	OPkServerLowLimit	If server holds less OPk than this limit, generate and upload a batch of OPks
[in]	OPkBatchSize	Number of OPks in a batch uploaded to server

Implements lime::LimeGeneric.

template<typename Curve >

void lime::Lime< Curve >::update_SPk ( const std::shared_ptr< limeCallback > callback )

overridevirtual

Check if the current SPk needs to be updated, if yes, generate a new one and publish it on server.

Parameters

[in] callback Called with success or failure when operation is completed.

Implements lime::LimeGeneric.

The documentation for this class was generated from the following files:

/tmp/B.4283tfon/BUILD/lime-5.4.38-build/lime-5.4.38/src/lime_impl.hpp
/tmp/B.4283tfon/BUILD/lime-5.4.38-build/lime-5.4.38/src/lime.cpp

Public Member Functions

Detailed Description

template<typename Curve> class lime::Lime< Curve >

Constructor & Destructor Documentation

Member Function Documentation

template<typename Curve>
class lime::Lime< Curve >