lime
Lime is a C++ library implementing Open Whisper System Signal protocol
lime.hpp
Go to the documentation of this file.
1/*
2 lime.hpp
3 @author Johan Pascal
4 @copyright Copyright (C) 2017 Belledonne Communications SARL
5
6 This program is free software: you can redistribute it and/or modify
7 it under the terms of the GNU General Public License as published by
8 the Free Software Foundation, either version 3 of the License, or
9 (at your option) any later version.
10
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU General Public License for more details.
15
16 You should have received a copy of the GNU General Public License
17 along with this program. If not, see <http://www.gnu.org/licenses/>.
18*/
19#ifndef lime_hpp
20#define lime_hpp
21
22#include <memory> //smart ptrs
23#include <unordered_map>
24#include <vector>
25#include <functional>
26#include <string>
27#include <mutex>
28
29namespace lime {
30
34 enum class CurveId : uint8_t {
35 unset=0,
36 c25519=1,
37 c448=2
38 };
39
41 enum class EncryptionPolicy {
42 DRMessage,
46 };
47
53 enum class PeerDeviceStatus : uint8_t {
54 untrusted=0,
55 trusted=1,
56 unsafe=2,
57 fail,
59 unknown
61 };
62
68 const std::string deviceId;
75 std::vector<uint8_t> DRmessage;
81 };
82
84 enum class CallbackReturn : uint8_t {
85 success,
86 fail
87 };
95 using limeCallback = std::function<void(const lime::CallbackReturn status, const std::string message)>;
96
97 /* X3DH server communication : these functions prototypes are used to post data and get response from/to the X3DH server */
105 using limeX3DHServerResponseProcess = std::function<void(int responseCode, const std::vector<uint8_t> &responseBody)>;
106
115 using limeX3DHServerPostData = std::function<void(const std::string &url, const std::string &from, const std::vector<uint8_t> &message, const limeX3DHServerResponseProcess &reponseProcess)>;
116
117 /* Forward declare the class managing one lime user*/
118 class LimeGeneric;
119
127 private :
128 std::unordered_map<std::string, std::shared_ptr<LimeGeneric>> m_users_cache; // cache of already opened Lime Session, identified by user Id (GRUU)
129 std::mutex m_users_mutex; // m_users_cache mutex
130 std::string m_db_access; // DB access information forwarded to SOCI to correctly access database
131 std::shared_ptr<std::recursive_mutex> m_db_mutex; // database access mutex
132 limeX3DHServerPostData m_X3DH_post_data; // send data to the X3DH key server
133 void load_user(std::shared_ptr<LimeGeneric> &user, const std::string &localDeviceId, const bool allStatus=false); // helper function, get from m_users_cache of local Storage the requested Lime object
134
135 public :
136
154 void create_user(const std::string &localDeviceId, const std::string &x3dhServerUrl, const lime::CurveId curve, const uint16_t OPkInitialBatchSize, const limeCallback &callback);
158 void create_user(const std::string &localDeviceId, const std::string &x3dhServerUrl, const lime::CurveId curve, const limeCallback &callback);
159
169 void delete_user(const std::string &localDeviceId, const limeCallback &callback);
170
178 bool is_user(const std::string &localDeviceId);
179
220 void encrypt(const std::string &localDeviceId, std::shared_ptr<const std::string> recipientUserId, std::shared_ptr<std::vector<RecipientData>> recipients, std::shared_ptr<const std::vector<uint8_t>> plainMessage, std::shared_ptr<std::vector<uint8_t>> cipherMessage, const limeCallback &callback, lime::EncryptionPolicy encryptionPolicy=lime::EncryptionPolicy::optimizeUploadSize);
221
237 lime::PeerDeviceStatus decrypt(const std::string &localDeviceId, const std::string &recipientUserId, const std::string &senderDeviceId, const std::vector<uint8_t> &DRmessage, const std::vector<uint8_t> &cipherMessage, std::vector<uint8_t> &plainMessage);
242 lime::PeerDeviceStatus decrypt(const std::string &localDeviceId, const std::string &recipientUserId, const std::string &senderDeviceId, const std::vector<uint8_t> &DRmessage, std::vector<uint8_t> &plainMessage);
243
262 void update(const limeCallback &callback, uint16_t OPkServerLowLimit, uint16_t OPkBatchSize);
266 void update(const limeCallback &callback);
267
277 void get_selfIdentityKey(const std::string &localDeviceId, std::vector<uint8_t> &Ik);
278
307 void set_peerDeviceStatus(const std::string &peerDeviceId, const std::vector<uint8_t> &Ik, lime::PeerDeviceStatus status);
308
323 void set_peerDeviceStatus(const std::string &peerDeviceId, lime::PeerDeviceStatus status);
324
332 lime::PeerDeviceStatus get_peerDeviceStatus(const std::string &peerDeviceId);
333
341 bool is_localUser(const std::string &deviceId);
342
350 void delete_peerDevice(const std::string &peerDeviceId);
351
361 void stale_sessions(const std::string &localDeviceId, const std::string &peerDeviceId);
362
371 void set_x3dhServerUrl(const std::string &localDeviceId, const std::string &x3dhServerUrl);
372
382 std::string get_x3dhServerUrl(const std::string &localDeviceId);
383
384 LimeManager() = delete; // no manager without Database and http provider
385 LimeManager(const LimeManager&) = delete; // no copy constructor
386 LimeManager operator=(const LimeManager &) = delete; // nor copy operator
387
395 LimeManager(const std::string &db_access, const limeX3DHServerPostData &X3DH_post_data, std::shared_ptr<std::recursive_mutex> db_mutex);
399 LimeManager(const std::string &db_access, const limeX3DHServerPostData &X3DH_post_data);
400
401 ~LimeManager() = default;
402 };
403} //namespace lime
404#endif /* lime_hpp */
A pure abstract class defining the API to encrypt/decrypt/manage user and its keys.
Definition: lime_lime.hpp:35
Manage several Lime objects(one is needed for each local user).
Definition: lime.hpp:126
LimeManager operator=(const LimeManager &)=delete
void delete_user(const std::string &localDeviceId, const limeCallback &callback)
Delete a user from local database and from the X3DH server.
Definition: lime_manager.cpp:83
lime::PeerDeviceStatus get_peerDeviceStatus(const std::string &peerDeviceId)
get the status of a peer device: unknown, untrusted, trusted, unsafe
Definition: lime_manager.cpp:217
void set_peerDeviceStatus(const std::string &peerDeviceId, const std::vector< uint8_t > &Ik, lime::PeerDeviceStatus status)
set the peer device status flag in local storage: unsafe, trusted or untrusted.
Definition: lime_manager.cpp:203
void delete_peerDevice(const std::string &peerDeviceId)
delete a peerDevice from local storage
Definition: lime_manager.cpp:231
LimeManager()=delete
bool is_user(const std::string &localDeviceId)
Check if a user is present and active in local storage.
Definition: lime_manager.cpp:101
void encrypt(const std::string &localDeviceId, std::shared_ptr< const std::string > recipientUserId, std::shared_ptr< std::vector< RecipientData > > recipients, std::shared_ptr< const std::vector< uint8_t > > plainMessage, std::shared_ptr< std::vector< uint8_t > > cipherMessage, const limeCallback &callback, lime::EncryptionPolicy encryptionPolicy=lime::EncryptionPolicy::optimizeUploadSize)
Encrypt a buffer (text or file) for a given list of recipient devices.
Definition: lime_manager.cpp:115
std::string get_x3dhServerUrl(const std::string &localDeviceId)
Get the X3DH key server URL for this identified user.
Definition: lime_manager.cpp:265
void get_selfIdentityKey(const std::string &localDeviceId, std::vector< uint8_t > &Ik)
retrieve self Identity Key, an EdDSA formatted public key
Definition: lime_manager.cpp:196
~LimeManager()=default
void set_x3dhServerUrl(const std::string &localDeviceId, const std::string &x3dhServerUrl)
Set the X3DH key server URL for this identified user.
Definition: lime_manager.cpp:256
lime::PeerDeviceStatus decrypt(const std::string &localDeviceId, const std::string &recipientUserId, const std::string &senderDeviceId, const std::vector< uint8_t > &DRmessage, const std::vector< uint8_t > &cipherMessage, std::vector< uint8_t > &plainMessage)
Decrypt the given message.
Definition: lime_manager.cpp:124
LimeManager(const LimeManager &)=delete
void create_user(const std::string &localDeviceId, const std::string &x3dhServerUrl, const lime::CurveId curve, const uint16_t OPkInitialBatchSize, const limeCallback &callback)
Create a user in local database and publish it on the given X3DH server.
Definition: lime_manager.cpp:60
void update(const limeCallback &callback, uint16_t OPkServerLowLimit, uint16_t OPkBatchSize)
Update: shall be called once a day at least, performs checks, updates and cleaning operations.
Definition: lime_manager.cpp:151
void stale_sessions(const std::string &localDeviceId, const std::string &peerDeviceId)
Stale all sessions between localDeviceId and peerDevice. If peerDevice keep using this session to enc...
Definition: lime_manager.cpp:244
bool is_localUser(const std::string &deviceId)
checks if a device iD exists in the local users
Definition: lime_manager.cpp:224
Definition: lime.cpp:30
CallbackReturn
Definition: lime.hpp:84
EncryptionPolicy
Definition: lime.hpp:41
std::function< void(const lime::CallbackReturn status, const std::string message)> limeCallback
Callback use to give a status on asynchronous operation.
Definition: lime.hpp:95
CurveId
Definition: lime.hpp:34
PeerDeviceStatus
Definition: lime.hpp:53
std::function< void(int responseCode, const std::vector< uint8_t > &responseBody)> limeX3DHServerResponseProcess
Get the response from server. The external service providing secure communication to the X3DH server ...
Definition: lime.hpp:105
std::function< void(const std::string &url, const std::string &from, const std::vector< uint8_t > &message, const limeX3DHServerResponseProcess &reponseProcess)> limeX3DHServerPostData
Post a message to the X3DH server.
Definition: lime.hpp:115
The encrypt function input/output data structure.
Definition: lime.hpp:67
std::vector< uint8_t > DRmessage
Definition: lime.hpp:75
lime::PeerDeviceStatus peerStatus
Definition: lime.hpp:69
const std::string deviceId
Definition: lime.hpp:68
RecipientData(const std::string &deviceId)
Definition: lime.hpp:80