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

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

## Enumerations

enum class | x3dh_message_type : uint8_t { deprecated_registerUser =0x01 , deleteUser =0x02 , postSPk =0x03 , postOPks =0x04 , getPeerBundle =0x05 , peerBundle =0x06 , getSelfOPks =0x07 , selfOPks =0x08 , registerUser =0x09 , error =0xff }
| the x3dh message type exchanged with the X3DH server More...
enum class | x3dh_error_code : uint8_t { bad_content_type =0x00 , bad_curve =0x01 , missing_senderId =0x02 , bad_x3dh_protocol_version =0x03 , bad_size =0x04 , user_already_in =0x05 , user_not_found =0x06 , db_error =0x07 , bad_request =0x08 , server_failure =0x09 , resource_limit_reached =0x0a , unknown_error_code =0xfe , unset_error_code =0xff }
| the error codes included in the x3dh error message received from the X3DH server More...

## Functions

static std::string | x3dh_messageTypeString (const x3dh_message_type message_type)
| Helper function to get human readable trace of x3dh messages types.
static std::vector< uint8_t > | X3DH_makeHeader (const x3dh_message_type message_type, const lime::CurveId curve) noexcept
| Build X3DH message header using current protocol Version byte.
template<typename Curve>
void | buildMessage_registerUser (std::vector< uint8_t > &message, const DSA< Curve, lime::DSAtype::publicKey > &Ik, const X< Curve, lime::Xtype::publicKey > &SPk, const DSA< Curve, lime::DSAtype::signature > &Sig, const uint32_t SPk_id, const std::vector< X< Curve, lime::Xtype::publicKey > > &OPks, const std::vector< uint32_t > &OPk_ids) noexcept
| build a registerUser message : Identity Key<EDDSA Public Key length>
template<typename Curve>
void | buildMessage_deleteUser (std::vector< uint8_t > &message) noexcept
| build a deleteUser message
template<typename Curve>
void | buildMessage_publishSPk (std::vector< uint8_t > &message, const X< Curve, lime::Xtype::publicKey > &SPk, const DSA< Curve, lime::DSAtype::signature > &Sig, const uint32_t SPk_id) noexcept
| build a postSPk message
template<typename Curve>
void | buildMessage_publishOPks (std::vector< uint8_t > &message, const std::vector< X< Curve, lime::Xtype::publicKey > > &OPks, const std::vector< uint32_t > &OPk_ids) noexcept
| build a postOPks message
template<typename Curve>
void | buildMessage_getPeerBundles (std::vector< uint8_t > &message, std::vector< std::string > &peer_device_ids) noexcept
| build a getPeerBundle message
template<typename Curve>
void | buildMessage_getSelfOPks (std::vector< uint8_t > &message) noexcept
| build a getSelfOPks message
template<typename Curve>
bool | parseMessage_getType (const std::vector< uint8_t > &body, x3dh_message_type &message_type, x3dh_error_code &error_code, const limeCallback callback) noexcept
template<typename Curve>
bool | parseMessage_getPeerBundles (const std::vector< uint8_t > &body, std::vector< X3DH_peerBundle< Curve > > &peersBundle) noexcept
| Parse a peerBundles message and populate a vector of peerBundles.
template<typename Curve>
bool | parseMessage_selfOPks (const std::vector< uint8_t > &body, std::vector< uint32_t > &selfOPkIds) noexcept
| Parse a selfOPk message and populate a self OPk ids.

## Variables

constexpr uint8_t | X3DH_protocolVersion = 0x01
constexpr size_t | X3DH_headerSize = 3

## Detailed Description

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

Protocol Version 0x01:
  Header is : Protccol Version Number<1 byte> || Message type<1 byte> || Curve id<1 byte> Messages are : header<3 bytes> || Message content

If not an error the server responds with a message holding just a header of the same message type except for getPeerBundle which shall be answered with a peerBundle message

Message types description :

- registerUser : Identity Key<EDDSA Public Key length>
  SPk< ECDH Public key length > ||
  SPk Signature< Signature Length > ||
  SPk Id < 4 bytes>
  OPk Keys Count<2 bytes unsigned integer Big endian> ||
  ( OPk< ECDH Public key length > || OPk Id <4 bytes>){Keys Count}
- deleteUser : empty message, user to delete is retrieved from header From
- postSPk : SPk< ECDH Public key length > || SPk Signature< Signature Length > || SPk Id < 4 bytes>
- postOPks : Keys Count<2 bytes unsigned integer Big endian> ||
  ( OPk< ECDH Public key length > || OPk Id <4 bytes>){Keys Count}
- getPeerBundle : request Count < 2 bytes unsigned Big Endian> ||
  (userId Size <2 bytes unsigned Big Endian> || UserId <...> (the GRUU of user we wan't to send a message)) {request Count}
- peerBundle : bundle Count < 2 bytes unsigned Big Endian> ||
  ( deviceId Size < 2 bytes unsigned Big Endian > || deviceId Flag<1 byte: 0 if no OPK in bundle, 1 if OPk is the bundle, 2 if no key bundle is associated to this device> || Ik < EDDSA Public Key Length > || SPk < ECDH Public Key Length > || SPK id <4 bytes> SPk_sig < Signature Length > || (OPk < ECDH Public Key Length > || OPk id <4 bytes>){0,1 in accordance to flag} ) { bundle Count}
- getSelfOPks : empty message, ask server for the OPk Id it still holds for us
- selfOPks : OPk Count <2 bytes unsigned integer Big Endian> ||
  (OPk id <4 bytes uint32_t big endian>){OPk Count}
- error : errorCode<1 byte> || (errorMessage<...>){0,1}

## Enumeration Type Documentation

## x3dh_error_code

enum class lime::x3dh_protocol::x3dh_error_code : uint8_t

strong

the error codes included in the x3dh error message received from the X3DH server

Note
  Do not change the mapped values as they must be synced with X3DH server definition

Enumerator
bad_content_type |
bad_curve |
missing_senderId |
bad_x3dh_protocol_version |
bad_size |
user_already_in |
user_not_found |
db_error |
bad_request |
server_failure |
resource_limit_reached |
unknown_error_code |
unset_error_code |

## x3dh_message_type

enum class lime::x3dh_protocol::x3dh_message_type : uint8_t

strong

the x3dh message type exchanged with the X3DH server

Note
  Do not change the mapped values as they must be synced with X3DH server definition

Enumerator
deprecated_registerUser |
deleteUser |
postSPk |
postOPks |
getPeerBundle |
peerBundle |
getSelfOPks |
selfOPks |
registerUser |
error |

## Function Documentation

## buildMessage_deleteUser()

template<typename Curve>

void lime::x3dh_protocol::buildMessage_deleteUser | ( | std::vector< uint8_t > & | message | ) |

noexcept

build a deleteUser message

    empty message, server retrieves deviceId to delete from authentication header, you cannot delete someone else!

Parameters

  [in,out] | message | an empty buffer to store the message

## buildMessage_getPeerBundles()

template<typename Curve>

void lime::x3dh_protocol::buildMessage_getPeerBundles | ( | std::vector< uint8_t > & | message,
|  | std::vector< std::string > & | peer_device_ids )

noexcept

build a getPeerBundle message

        request Count < 2 bytes unsigned Big Endian> ||\n
        (userId Size <2 bytes unsigned Big Endian> ||
        UserId <...> (the GRUU of user we wan't to send a message)) {request Count}

Parameters

  [in,out] | message | an empty buffer to store the message
  [in] | peer_device_ids | a vector of all devices id for wich we request a key bundle

## buildMessage_getSelfOPks()

template<typename Curve>

void lime::x3dh_protocol::buildMessage_getSelfOPks | ( | std::vector< uint8_t > & | message | ) |

noexcept

build a getSelfOPks message

    empty message, ask server for the OPk Id it still holds for us

Parameters

  [in,out] | message | an empty buffer to store the message

## buildMessage_publishOPks()

template<typename Curve>

void lime::x3dh_protocol::buildMessage_publishOPks | ( | std::vector< uint8_t > & | message,
|  | const std::vector< X< Curve, lime::Xtype::publicKey > > & | OPks,
|  | const std::vector< uint32_t > & | OPk_ids )

noexcept

build a postOPks message

        Keys Count<2 bytes unsigned integer Big endian> ||\n
        ( OPk< ECDH Public key length > ||
        OPk Id <4 bytes>){Keys Count}

Parameters

  [in,out] | message | an empty buffer to store the message
  [in] | OPks | a vector of OPks to be published
  [in] | OPk_ids | Id vector matching the order of the OPks vector

## buildMessage_publishSPk()

template<typename Curve>

void lime::x3dh_protocol::buildMessage_publishSPk | ( | std::vector< uint8_t > & | message,
|  | const X< Curve, lime::Xtype::publicKey > & | SPk,
|  | const DSA< Curve, lime::DSAtype::signature > & | Sig,
|  | const uint32_t | SPk_id )

noexcept

build a postSPk message

    SPk< ECDH Public key length > ||
    SPk Signature< Signature Length > ||
    SPk Id < 4 bytes>

Parameters

  [in,out] | message | an empty buffer to store the message
  [in] | SPk | Public Signed Pre-Key
  [in] | Sig | Signature of Public Signed Pre-Key (signed using self Identity key)
  [in] | SPk_id | SPk id used to retrieve the SPk from local storage

## buildMessage_registerUser()

template<typename Curve>

void lime::x3dh_protocol::buildMessage_registerUser | ( | std::vector< uint8_t > & | message,
|  | const DSA< Curve, lime::DSAtype::publicKey > & | Ik,
|  | const X< Curve, lime::Xtype::publicKey > & | SPk,
|  | const DSA< Curve, lime::DSAtype::signature > & | Sig,
|  | const uint32_t | SPk_id,
|  | const std::vector< X< Curve, lime::Xtype::publicKey > > & | OPks,
|  | const std::vector< uint32_t > & | OPk_ids )

noexcept

build a registerUser message : Identity Key<EDDSA Public Key length>

Parameters

  [in,out] | message | an empty buffer to store the message
  [in] | Ik | Self public identity key (formatted for signature algorithm)
  [in] | SPk | public signed pre-key (ECDH format)
  [in] | Sig | SPk signed using Ik
  [in] | SPk_id | SPk Id in local storage
  [in] | OPks | Vector of one time pre-keys
  [in] | OPk_ids | Ids of the OPk hold by previous vector(in matching indexes)

## parseMessage_getPeerBundles()

template<typename Curve>

bool lime::x3dh_protocol::parseMessage_getPeerBundles | ( | const std::vector< uint8_t > & | body,
|  | std::vector< X3DH_peerBundle< Curve > > & | peersBundle )

noexcept

Parse a peerBundles message and populate a vector of peerBundles.

Warning: no checks are done on message type, they are performed before calling this function

peerBundle : bundle Count < 2 bytes unsigned Big Endian> ||
( deviceId Size < 2 bytes unsigned Big Endian > || deviceId Flag<1 byte: 0 if no OPK in bundle, 1 if present, 2 no key bundle found on server> || Ik < EDDSA Public Key Length > || SPk < ECDH Public Key Length > || SPK id <4 bytes> SPk_sig < Signature Length > || (OPk < ECDH Public Key Length > || OPk id <4 bytes>){0,1 in accordance to flag} ) { bundle Count}

Parameters

  [in] | body | a buffer holding the message
  [out] | peersBundle | a vector to be populated from message content, is empty if none found

Returns
  true if all went ok, false and empty peersBundle otherwise

## parseMessage_getType()

template<typename Curve>

bool lime::x3dh_protocol::parseMessage_getType | ( | const std::vector< uint8_t > & | body,
|  | x3dh_message_type & | message_type,
|  | x3dh_error_code & | error_code,
|  | const limeCallback | callback )

noexcept

## parseMessage_selfOPks()

template<typename Curve>

bool lime::x3dh_protocol::parseMessage_selfOPks | ( | const std::vector< uint8_t > & | body,
|  | std::vector< uint32_t > & | selfOPkIds )

noexcept

Parse a selfOPk message and populate a self OPk ids.

Warning: no checks are done on message type, they are performed before calling this function
selfOPks : OPk Count <2 bytes unsigned integer Big Endian> ||
(OPk id <4 bytes uint32_t big endian>){OPk Count}

Parameters

  [in] | body | a buffer holding the message
  [out] | selfOPkIds | a vector to be populated from message content, is empty if no OPk returned

Returns
  true if all went ok, false otherwise

## X3DH_makeHeader()

std::vector< uint8_t > lime::x3dh_protocol::X3DH_makeHeader | ( | const x3dh_message_type | message_type,
|  | const lime::CurveId | curve )

static noexcept

Build X3DH message header using current protocol Version byte.

Parameters

  [in] | message_type | The message type we are creating
  [in] | curve | The curve Id we're working with

Returns
  a vector holding the well formed header ready to be expanded to include the message body

## x3dh_messageTypeString()

std::string lime::x3dh_protocol::x3dh_messageTypeString | ( | const x3dh_message_type | message_type | ) |

static

Helper function to get human readable trace of x3dh messages types.

Parameters

  [in] | message_type | The message type in enum class format

Returns
  the message type as a human readable string

## Variable Documentation

## X3DH_headerSize

size_t lime::x3dh_protocol::X3DH_headerSize = 3

constexpr

## X3DH_protocolVersion

uint8_t lime::x3dh_protocol::X3DH_protocolVersion = 0x01

constexpr