Loading...
Searching...
No Matches
lime Namespace Reference

## Namespaces

namespace | settings
| Hold constants definition used as settings in all components of the lime library.
namespace | double_ratchet_protocol
| Group in this namespace all the functions related to building or parsing double ratchet packets.
namespace | x3dh_protocol
| Group in this namespace all the functions related to building or parsing x3dh packets.

## Classes

class | bctbx_RNG
| A wrapper around the bctoolbox Random Number Generator, implements the RNG interface. More...
class | bctbx_EDDSA
| a wrapper around bctoolbox signature algorithms, implements the Signature interface More...
class | bctbx_ECDH
| a wrapper around bctoolbox key exchange algorithms, implements the keyExchange interface More...
struct | sBuffer
| auto clean fixed size buffer(std::array based) More...
class | X
| Base buffer definition for Key Exchange data structure. More...
class | Xpair
| Key pair structure for key exchange algorithm. More...
class | DSA
| Base buffer definition for DSA data structure. More...
class | DSApair
| Key pair structure for DSA algorithm. More...
class | RNG
| Random number generator interface. More...
class | keyExchange
| Key exchange interface. More...
class | Signature
| Digital Signature interface. More...
struct | ReceiverKeyChain
| Chain storing the DH and MKs associated with Nr(uint16_t map index). More...
class | DR
| store a Double Rachet session. More...
struct | RecipientInfos
| extend the RecipientData to add a Double Ratchet session shared with the recipient More...
struct | callbackUserData
| structure holding user data while waiting for callback from X3DH server response processing More...
class | Lime
| Implement the abstract class LimeGeneric. More...
struct | C255
| curve 25519 data types size definition More...
struct | C448
| curve 448-goldilocks data types size definition More...
struct | SHA512
| SHA512 buffer size definition. More...
struct | AES256GCM
| AES256GCM buffers size definition. More...
class | LimeGeneric
| A pure abstract class defining the API to encrypt/decrypt/manage user and its keys. More...
class | Db
| Database access class. More...
struct | X3DH_peerBundle
| Holds everything found in a key bundle received from X3DH server. More...
struct | RecipientData
| The encrypt function input/output data structure. More...
class | LimeManager
| Manage several Lime objects(one is needed for each local user). More...

## Typedefs

using | DRChainKey = lime::sBuffer<lime::settings::DRChainKeySize>
using | DRMKey = lime::sBuffer<lime::settings::DRMessageKeySize+lime::settings::DRMessageIVSize>
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.
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.
using | limeX3DHServerPostData = std::function<void(const std::string &url, const std::string &from, const std::vector<uint8_t> &message, const limeX3DHServerResponseProcess &reponseProcess)>
| Post a message to the X3DH server.

## Enumerations

enum class | DRSessionDbStatus : uint8_t { clean , dirty_encrypt , dirty_decrypt , dirty_ratchet , dirty }
| the possible status of session regarding the Local Storage More...
enum class | network_state : uint8_t { done =0x00 , sendSPk =0x01 , sendOPk =0x02 }
enum class | Xtype { publicKey , privateKey , sharedSecret }
| List of data types used by key Echange algorithm. More...
enum class | DSAtype { publicKey , privateKey , signature }
| List of data types used by Signature algorithm. More...
enum class | X3DHKeyBundleFlag : uint8_t { noOPk =0 , OPk =1 , noBundle =2 }
| Set possible values for a flag in the keyBundle X3DH packet. More...
enum class | CurveId : uint8_t { unset =0 , c25519 =1 , c448 =2 }
enum class | EncryptionPolicy { DRMessage , cipherMessage , optimizeUploadSize , optimizeGlobalBandwidth }
enum class | PeerDeviceStatus : uint8_t { untrusted =0 , trusted =1 , unsafe =2 , fail , unknown }
enum class | CallbackReturn : uint8_t { success , fail }

## Functions

std::shared_ptr< LimeGeneric > | insert_LimeUser (std::shared_ptr< lime::Db > localStorage, const std::string &deviceId, const std::string &url, const lime::CurveId curve, const uint16_t OPkInitialBatchSize, const limeX3DHServerPostData &X3DH_post_data, const limeCallback &callback)
| : Insert user in database and return a pointer to the control class instanciating the appropriate Lime children class
std::shared_ptr< LimeGeneric > | load_LimeUser (std::shared_ptr< lime::Db > localStorage, const std::string &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
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
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, typename infoType>
void | HMAC_KDF (const uint8_t *const salt, const size_t saltSize, const uint8_t *const ikm, const size_t ikmSize, const infoType &info, uint8_t *output, size_t outputSize)
template<typename hashAlgo, typename infoType>
void | HMAC_KDF (const std::vector< uint8_t > &salt, const std::vector< uint8_t > &ikm, const infoType &info, uint8_t *okm, size_t okmSize)
| HKDF as described in RFC5869.
template void | HMAC_KDF< SHA512, std::vector< uint8_t > > (const uint8_t *const salt, const size_t saltSize, const uint8_t *const ikm, const size_t ikmSize, const std::vector< uint8_t > &info, uint8_t *output, size_t outputSize)
template void | HMAC_KDF< SHA512, std::string > (const uint8_t *const salt, const size_t saltSize, const uint8_t *const ikm, const size_t ikmSize, const std::string &info, uint8_t *output, size_t outputSize)
template void | HMAC_KDF< SHA512, std::vector< uint8_t > > (const std::vector< uint8_t > &salt, const std::vector< uint8_t > &ikm, const std::vector< uint8_t > &info, uint8_t *output, size_t outputSize)
template void | HMAC_KDF< SHA512, std::string > (const std::vector< uint8_t > &salt, const std::vector< uint8_t > &ikm, const std::string &info, 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.
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.
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
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<>
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)
template<typename Curve>
static void | KDF_RK (DRChainKey &RK, DRChainKey &CK, const X< Curve, lime::Xtype::sharedSecret > &dh_out) noexcept
| Key Derivation Function used in Root key/Diffie-Hellman Ratchet chain.
static void | KDF_CK (DRChainKey &CK, DRMKey &MK) noexcept
| Key Derivation Function used in Symmetric key ratchet chain.
static bool | decrypt (const lime::DRMKey &MK, const std::vector< uint8_t > &ciphertext, const size_t headerSize, std::vector< uint8_t > &AD, std::vector< uint8_t > &plaintext)
| Decrypt as described is spec section 3.1.
static bool | decrypt (const lime::DRMKey &MK, const std::vector< uint8_t > &ciphertext, const size_t headerSize, std::vector< uint8_t > &AD, sBuffer< lime::settings::DRrandomSeedSize > &plaintext)
template<typename Curve>
void | encryptMessage (std::vector< RecipientInfos< Curve > > &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)
| Encrypt a message to all recipients, identified by their device id.
template<typename Curve>
std::shared_ptr< DR< Curve > > | decryptMessage (const std::string &sourceDeviceId, const std::string &recipientDeviceId, const std::vector< uint8_t > &recipientUserId, std::vector< std::shared_ptr< DR< Curve > > > &DRSessions, const std::vector< uint8_t > &DRmessage, const std::vector< uint8_t > &cipherMessage, std::vector< uint8_t > &plaintext)
| Decrypt a message.

## Variables

const std::array< uint8_t, 1 > | hkdf_ck_info {{0x02}}
const std::array< uint8_t, 1 > | hkdf_mk_info {{0x01}}

## Typedef Documentation

## DRChainKey

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

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

## DRMKey

using lime::DRMKey = lime::sBuffer<lime::settings::DRMessageKeySize+lime::settings::DRMessageIVSize>

Double Ratchet Message keys : 32 bytes of encryption key followed by 16 bytes of IV

## limeCallback

using lime::limeCallback = 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

## limeX3DHServerPostData

using lime::limeX3DHServerPostData = std::function<void(const std::string &url, const std::string &from, const 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

## limeX3DHServerResponseProcess

using lime::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.

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

## SharedADBuffer

using lime::SharedADBuffer = 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

## CallbackReturn

enum class 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

## CurveId

enum class 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

## DRSessionDbStatus

enum class lime::DRSessionDbStatus : uint8_t

strong

the possible status of session regarding the Local Storage

used to pick a subset of session to be saved in DB

Enumerator
clean | session in cache match the one in local storage
dirty_encrypt | an encrypt was performed modifying part of the cached session
dirty_decrypt | a dencrypt was performed modifying part of the cached session
dirty_ratchet | a ratchet step was performed modifying part of cached session
dirty | the whole session data must be saved to local storage

## DSAtype

enum class lime::DSAtype

strong

List of data types used by Signature algorithm.

public key, private key and signature

Enumerator
publicKey |
privateKey |
signature |

## EncryptionPolicy

enum class 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.

## network_state

enum class lime::network_state : uint8_t

strong

Enumerator
done |
sendSPk |
sendOPk |

## PeerDeviceStatus

enum class 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

## X3DHKeyBundleFlag

enum class 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 |

## Xtype

enum class 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

## AEAD_decrypt()

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

## AEAD_decrypt< AES256GCM >() [1/2]

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 )

## AEAD_decrypt< AES256GCM >() [2/2]

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 )

## AEAD_encrypt()

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

## AEAD_encrypt< AES256GCM >() [1/2]

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 )

## AEAD_encrypt< AES256GCM >() [2/2]

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 )

## bctbx_ECDHInit()

template<typename Curve>

bctbx_ECDHContext_t * lime::bctbx_ECDHInit | ( | void |  | ) |

## bctbx_EDDSAInit()

template<typename Curve>

bctbx_EDDSAContext_t * lime::bctbx_EDDSAInit | ( | void |  | ) |

## cleanBuffer()

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

## decrypt() [1/2]

bool lime::decrypt | ( | const lime::DRMKey & | MK,
|  | const std::vector< uint8_t > & | ciphertext,
|  | const size_t | headerSize,
|  | std::vector< uint8_t > & | AD,
|  | sBuffer< lime::settings::DRrandomSeedSize > & | plaintext )

static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

used when the ouput is a fixed buffer: we decrypt the random seed used to generate the cipherMessage keys No need to resize the plaintext buffer when it has a fixed size.

## decrypt() [2/2]

bool lime::decrypt | ( | const lime::DRMKey & | MK,
|  | const std::vector< uint8_t > & | ciphertext,
|  | const size_t | headerSize,
|  | std::vector< uint8_t > & | AD,
|  | std::vector< uint8_t > & | plaintext )

static

Decrypt as described is spec section 3.1.

Parameters

  [in] | MK | A buffer holding key<32 bytes> || IV<16 bytes>
  [in] | ciphertext | buffer holding: header<size depends on Curve type> || ciphertext || auth tag<16 bytes>
  [in] | headerSize | Size of the header included in ciphertext
  [in] | AD | Associated data
  [out] | plaintext | the output message : a vector resized to hold the plaintext.

Returns
  false if authentication failed

## decryptMessage()

template<typename Curve>

std::shared_ptr< DR< Curve > > lime::decryptMessage | ( | const std::string & | sourceDeviceId,
|  | const std::string & | recipientDeviceId,
|  | const std::vector< uint8_t > & | recipientUserId,
|  | std::vector< std::shared_ptr< DR< Curve > > > & | 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

## encryptMessage()

template<typename Curve>

void lime::encryptMessage | ( | std::vector< RecipientInfos< Curve > > & | 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 )

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

## HMAC()

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

## HMAC< SHA512 >() [1/2]

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 )

## HMAC< SHA512 >() [2/2]

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 )

## HMAC_KDF() [1/2]

template<typename hashAlgo, typename infoType>

void lime::HMAC_KDF | ( | const std::vector< uint8_t > & | salt,
|  | const std::vector< uint8_t > & | ikm,
|  | const infoType & | info,
|  | uint8_t * | okm,
|  | size_t | okmSize )

HKDF as described in RFC5869.

Compute:
  PRK = HMAC-Hash(salt, IKM)
  N = ceil(L/HashLen)
  T = T(1) | T(2) | T(3) | ... | T(N)
  OKM = first L octets of T
  where:
  T(0) = empty string (zero length)
  T(1) = HMAC-Hash(PRK, T(0) | info | 0x01)
  T(2) = HMAC-Hash(PRK, T(1) | info | 0x02)
  T(3) = HMAC-Hash(PRK, T(2) | info | 0x03)
  ...

Template Parameters

  hashAlgo | the hash algorithm to use (SHA512 available for now)
  infoType | the info parameter can be passed as a string or a std::vector<uint8_t>

Parameters

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

## HMAC_KDF() [2/2]

template<typename hashAlgo, typename infoType>

void lime::HMAC_KDF | ( | const uint8_t *const | salt,
|  | const size_t | saltSize,
|  | const uint8_t *const | ikm,
|  | const size_t | ikmSize,
|  | const infoType & | info,
|  | uint8_t * | output,
|  | size_t | outputSize )

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. use pointer to uint8_t and size arguments instead of std::vector<uint8_t>

## HMAC_KDF< SHA512, std::string >() [1/2]

template void lime::HMAC_KDF< SHA512, std::string > | ( | const std::vector< uint8_t > & | salt,
|  | const std::vector< uint8_t > & | ikm,
|  | const std::string & | info,
|  | uint8_t * | output,
|  | size_t | outputSize )

## HMAC_KDF< SHA512, std::string >() [2/2]

template void lime::HMAC_KDF< SHA512, std::string > | ( | const uint8_t *const | salt,
|  | const size_t | saltSize,
|  | const uint8_t *const | ikm,
|  | const size_t | ikmSize,
|  | const std::string & | info,
|  | uint8_t * | output,
|  | size_t | outputSize )

## HMAC_KDF< SHA512, std::vector< uint8_t > >() [1/2]

template void lime::HMAC_KDF< SHA512, std::vector< uint8_t > > | ( | const std::vector< uint8_t > & | salt,
|  | const std::vector< uint8_t > & | ikm,
|  | const std::vector< uint8_t > & | info,
|  | uint8_t * | output,
|  | size_t | outputSize )

## HMAC_KDF< SHA512, std::vector< uint8_t > >() [2/2]

template void lime::HMAC_KDF< SHA512, std::vector< uint8_t > > | ( | const uint8_t *const | salt,
|  | const size_t | saltSize,
|  | const uint8_t *const | ikm,
|  | const size_t | ikmSize,
|  | const std::vector< uint8_t > & | info,
|  | uint8_t * | output,
|  | size_t | outputSize )

## insert_LimeUser()

std::shared_ptr< LimeGeneric > lime::insert_LimeUser | ( | std::shared_ptr< lime::Db > | localStorage,
|  | const std::string & | deviceId,
|  | const std::string & | url,
|  | const lime::CurveId | curve,
|  | const uint16_t | OPkInitialBatchSize,
|  | const limeX3DHServerPostData & | X3DH_post_data,
|  | const 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 create in DB, deviceId shall be the GRUU
  [in] | url | URL of X3DH key server to be used to publish our keys
  [in] | curve | Which curve shall we use for this account, select the implemenation to instanciate when using this user
  [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

## KDF_CK()

void lime::KDF_CK | ( | DRChainKey & | CK,
|  | DRMKey & | MK )

static noexcept

Key Derivation Function used in Symmetric key ratchet chain.

     Implemented according to Double Ratchet spec section 5.2 using HMAC-SHA512
     @code{.unparsed}
    MK = HMAC-SHA512(CK, hkdf_mk_info) // get 48 bytes of it: first 32 to be key and last 16 to be IV
    CK = HMAC-SHA512(CK, hkdf_ck_info)
             hkdf_ck_info and hldf_mk_info being a distincts constants (0x02 and 0x01 as suggested in double ratchet - section 5.2)
     @endcode

Parameters

  [in,out] | CK | Input/output buffer used as key to compute MK and then next CK
  [out] | MK | Message Key(32 bytes) and IV(16 bytes) computed from HMAC_SHA512 keyed with CK

## KDF_RK()

template<typename Curve>

void lime::KDF_RK | ( | DRChainKey & | RK,
|  | DRChainKey & | CK,
|  | const X< Curve, lime::Xtype::sharedSecret > & | dh_out )

static noexcept

Key Derivation Function used in Root key/Diffie-Hellman Ratchet chain.

     Use HKDF (see RFC5869) to derive CK and RK in one derivation

Parameters

  [in,out] | RK | Input buffer used as salt also to store the 32 first byte of output key material
  [out] | CK | Output buffer, last 32 bytes of output key material
  [in] | dh_out | Buffer used as input key material

## load_LimeUser()

std::shared_ptr< LimeGeneric > lime::load_LimeUser | ( | std::shared_ptr< lime::Db > | localStorage,
|  | const std::string & | 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
  [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

## make_keyExchange()

template<typename Curve>

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

## make_RNG()

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

## make_Signature()

template<typename Curve>

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

## Variable Documentation

## hkdf_ck_info

const std::array<uint8_t,1> lime::hkdf_ck_info {{0x02}}

constant used as input of HKDF like function, see double ratchet spec section 5.2 - KDF_CK

## hkdf_mk_info

const std::array<uint8_t,1> lime::hkdf_mk_info {{0x01}}

constant used as input of HKDF like function, see double ratchet spec section 5.2 - KDF_CK