e2e_api.h

//
// Copyright Aliaksei Levin (levlam@telegram.org), Arseny Smirnov (arseny30@gmail.com) 2014-2026
//
// Distributed under the Boost Software License, Version 1.0. (See accompanying
// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
//
#pragma once
 
#include "td/e2e/e2e_errors.h"
 
#include <array>
#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <tuple>
#include <utility>
#include <variant>
#include <vector>
 
namespace td {
template <class T>
class Result;
class Status;
}  // namespace td
 
namespace tde2e_api {
//
//  Result and Error helper classes
//
 
struct Error {
  ErrorCode code;
  std::string message;
};
 
template <typename T>
class Result {
 public:
  Result(const T &value) : data_(value) {
  }
  Result(T &&value) : data_(std::move(value)) {
  }
 
  Result(const Error &error) : data_(error) {
  }
  Result(Error &&error) : data_(std::move(error)) {
  }
 
  Result(td::Result<T> &&value);
  Result(td::Status &&status);
 
  // Check if the result is a success
  bool is_ok() const {
    return std::holds_alternative<T>(data_);
  }
 
  // Check if the result is an error
  bool is_error() const {
    return std::holds_alternative<Error>(data_);
  }
 
  T &value() {
    return std::get<T>(data_);
  }
  const T &value() const {
    return std::get<T>(data_);
  }
 
  Error &error() {
    return std::get<Error>(data_);
  }
  const Error &error() const {
    return std::get<Error>(data_);
  }
 
 private:
  std::variant<T, Error> data_;
};
 
//
//                  Encryption
//
 
using Int256 = std::array<unsigned char, 32>;
using Int512 = std::array<unsigned char, 64>;
//TODO: strong typed ids
using PublicKey = std::string;
using HandshakeId = std::int64_t;
using LoginId = std::int64_t;
using UserId = std::int64_t;
using AnyKeyId = std::int64_t;
using PrivateKeyId = std::int64_t;
using PublicKeyId = std::int64_t;
using SymmetricKeyId = std::int64_t;
using Bytes = std::string;
using SecureBytes = std::string;
using Slice = std::string_view;
using SecureSlice = std::string_view;
struct Ok {};
 
struct EncryptedMessageForMany {
  std::vector<std::string> encrypted_headers;
  std::string encrypted_message;
};
 
Result<Ok> set_log_verbosity_level(int level);
 
// Keys management
// private keys will stay inside the library when it is possible
// all keys are stored only in memory and should be created or imported before usage
Result<PrivateKeyId> key_generate_private_key();
Result<PrivateKeyId> key_generate_temporary_private_key();
Result<SymmetricKeyId> key_derive_secret(PrivateKeyId key_id, Slice tag);
Result<SymmetricKeyId> key_from_bytes(SecureSlice secret);
Result<Bytes> key_to_encrypted_private_key(PrivateKeyId key_id, SymmetricKeyId secret_id);
Result<PrivateKeyId> key_from_encrypted_private_key(Slice encrypted_key, SymmetricKeyId secret_id);
Result<PublicKeyId> key_from_public_key(Slice public_key);
Result<SymmetricKeyId> key_from_ecdh(PrivateKeyId key_id, PublicKeyId other_public_key_id);
Result<PublicKey> key_to_public_key(PrivateKeyId key_id);
Result<SecureBytes> key_to_words(PrivateKeyId key_id);
Result<PrivateKeyId> key_from_words(SecureSlice words);
Result<Int512> key_sign(PrivateKeyId key, Slice data);
Result<Ok> key_destroy(AnyKeyId key_id);
Result<Ok> key_destroy_all();
 
// Used to encrypt key between processes, secret_id must be generated with key_from_ecdh
Result<Bytes> key_to_encrypted_private_key_internal(PrivateKeyId key_id, SymmetricKeyId secret_id);
Result<PrivateKeyId> key_from_encrypted_private_key_internal(Slice encrypted_key, SymmetricKeyId secret_id);
 
Result<EncryptedMessageForMany> encrypt_message_for_many(const std::vector<SymmetricKeyId> &key_ids,
                                                         SecureSlice message);
// keeps encrypted_message empty in result
Result<EncryptedMessageForMany> re_encrypt_message_for_many(SymmetricKeyId decrypt_key_id,
                                                            const std::vector<SymmetricKeyId> &encrypt_key_ids,
                                                            Slice encrypted_header, Slice encrypted_message);
Result<SecureBytes> decrypt_message_for_many(SymmetricKeyId key_id, Slice encrypted_header, Slice encrypted_message);
Result<Bytes> encrypt_message_for_one(SymmetricKeyId key_id, SecureSlice message);
Result<SecureBytes> decrypt_message_for_one(SymmetricKeyId key_id, Slice encrypted_message);
 
// Utilities for secret key verification/transfer via qr (or any other alternative channel)
// Requires:
//  - alternative channel to reliably transfer 'start' message from Bob to Alice (scanning QR is such channel)
//
// Alice:
//   - knows shared secret right after the handshake creation
//   - Bob's secret key is verified after finish is received
//
// Bob:
//   - knows shared secret right after accept is received
//   - Alice's secret key is verified after accept is received
//
// Use cases:
//  - Transfer of the key from old device to the new device
//  - Verification of other person's public key
//  - Contact sharing
//
Result<HandshakeId> handshake_create_for_bob(UserId bob_user_id, PrivateKeyId bob_private_key_id);
Result<HandshakeId> handshake_create_for_alice(UserId alice_user_id, PrivateKeyId alice_private_key_id,
                                               UserId bob_user_id, const PublicKey &bob_public_key, Slice start);
 
Result<Bytes> handshake_bob_send_start(HandshakeId bob_handshake_id);
Result<Bytes> handshake_alice_send_accept(HandshakeId alice_handshake_id);
Result<Bytes> handshake_bob_receive_accept_send_finish(HandshakeId bob_handshake_id, UserId alice_id,
                                                       const PublicKey &alice_public_key, Slice accept);
Result<Ok> handshake_alice_receive_finish(HandshakeId alice_handshake_id, Slice finish);
Result<SymmetricKeyId> handshake_get_shared_key_id(HandshakeId handshake_id);
Result<Ok> handshake_destroy(HandshakeId handshake_id);
Result<Ok> handshake_destroy_all();
 
// Helper to get QR-code identifier
Result<Bytes> handshake_start_id(Slice start);
 
// There is wrapper for login
Result<LoginId> login_create_for_bob();
Result<Bytes> login_bob_send_start(LoginId bob_login_id);
Result<Bytes> login_create_for_alice(UserId alice_user_id, PrivateKeyId alice_private_key_id, Slice start);
Result<PrivateKeyId> login_finish_for_bob(LoginId bob_login_id, UserId alice_user_id, const PublicKey &alice_public_key,
                                          Slice data);
Result<Ok> login_destroy(LoginId login_id);
Result<Ok> login_destroy_all();
 
// Personal info
 
// 1. Each entry stored and signed separately
// 2. Signature is never stored, but always is verified
// 3. It should be possible to save data without signature (but it can't override data with signature)
// 4. We should keep source of entry. Our, Server, Contact+Ts
// 5. We must keep is_contact flag.
 
template <class T>
struct Entry {
  enum Source { Self, Server, Contact };
  Source source;
  std::uint32_t timestamp;
  T value;
 
  Entry() : source(Self), timestamp(0), value() {
  }
  Entry(Source source, std::uint32_t timestamp, T &&value)
      : source(source), timestamp(timestamp), value(std::move(value)) {
  }
};
 
template <class T>
struct SignedEntry {
  Int512 signature;
  std::uint32_t timestamp{0};
  T value;
};
 
struct Name {
  std::string first_name;
  std::string last_name;
};
 
struct PhoneNumber {
  std::string phone_number;
};
 
struct EmojiNonces {
  std::optional<Int256> self_nonce;
  std::optional<Int256> contact_nonce_hash;
  std::optional<Int256> contact_nonce;
};
 
struct ContactState {
  enum State { Unknown, Contact, NotContact };
  State state{Unknown};
 
  ContactState() = default;
 
  explicit ContactState(State state) : state(state) {
  }
};
 
struct Contact {
  // Each contact has both public_key and user_id
  // how it is stored internally is not clients library user's concern
  std::uint32_t generation{0};
 
  // we always have public key. Essentially contact is defined by its public key
  PublicKeyId public_key{};
 
  // Personal data, signed by contact. If it is not signed, it has no relations to this public key
  std::optional<Entry<UserId>> o_user_id;
  std::optional<Entry<Name>> o_name;
  std::optional<Entry<PhoneNumber>> o_phone_number;
 
  // Personal data save by user_itself
  // It always exists and it always given but we keep timestamp just in case
  Entry<EmojiNonces> emoji_nonces;
  Entry<ContactState> contact_state;
};
 
// library can't enforce persistency of changes, because it has no persistent state.
// so it is client's responsibility to ensure that each change will be eventually saved to the server
// NB: it is unclear how protect ourself from server ignoring our queries.
 
using StorageId = std::int64_t;
using UpdateId = std::int64_t;
 
struct StorageBlockchainState {
  std::string next_suggested_block;
  std::vector<std::string> required_proofs;
};
struct StorageUpdates {
  std::vector<std::pair<PublicKeyId, std::optional<Contact>>> updates;
};
 
Result<StorageId> storage_create(PrivateKeyId key_id, Slice last_block);
Result<Ok> storage_destroy(StorageId storage_id);
Result<Ok> storage_destroy_all();
 
template <class T>
Result<UpdateId> storage_update_contact(StorageId storage_id, PublicKeyId key, SignedEntry<T> signed_entry);
template <class T>
Result<SignedEntry<T>> storage_sign_entry(PrivateKeyId key, Entry<T> entry);
 
Result<std::optional<Contact>> storage_get_contact(StorageId storage_id, PublicKeyId key);
Result<std::optional<Contact>> storage_get_contact_optimistic(StorageId storage_id, PublicKeyId key);
 
Result<std::int64_t> storage_blockchain_height(StorageId storage_id);
Result<StorageUpdates> storage_blockchain_apply_block(StorageId storage_id, Slice block);
Result<Ok> storage_blockchain_add_proof(StorageId storage_id, Slice proof, const std::vector<std::string> &keys);
 
Result<StorageBlockchainState> storage_get_blockchain_state(StorageId);
 
using CallId = std::int64_t;
using CallChannelId = std::int32_t;
struct CallParticipant {
  UserId user_id{};
  PublicKeyId public_key_id{};
  int permissions{};
};
 
struct CallState {
  int height{};
  std::vector<CallParticipant> participants;
};
 
Result<Bytes> call_create_zero_block(PrivateKeyId private_key_id, const CallState &initial_state);
Result<Bytes> call_create_self_add_block(PrivateKeyId private_key_id, Slice previous_block,
                                         const CallParticipant &self);
Result<CallId> call_create(UserId user_id, PrivateKeyId private_key_id, Slice last_block);
 
Result<std::string> call_describe(CallId call);
Result<std::string> call_describe_block(Slice block);
Result<std::string> call_describe_message(Slice message);
 
Result<Bytes> call_create_change_state_block(CallId call_id, const CallState &new_state);
Result<Bytes> call_encrypt(CallId call_id, CallChannelId channel_id, SecureSlice message,
                           size_t unencrypted_prefix_size);
Result<SecureBytes> call_decrypt(CallId call_id, UserId user_id, CallChannelId channel_id, Slice message);
 
Result<int> call_get_height(CallId call_id);
Result<CallState> call_apply_block(CallId call_id, Slice block);
 
Result<CallState> call_get_state(CallId call_id);
 
struct CallVerificationState {
  int height{};
  std::optional<Bytes> emoji_hash;
};
Result<CallVerificationState> call_get_verification_state(CallId call_id);
Result<CallVerificationState> call_receive_inbound_message(CallId call_id, Slice message);
 
// should be called after:
//   - creation
//   - call_apply_block
//   - call_receive_inbound_messages
Result<std::vector<Bytes>> call_pull_outbound_messages(CallId call_id);
 
struct CallVerificationWords {
  int height{};
  std::vector<std::string> words;
};
 
Result<CallVerificationWords> call_get_verification_words(CallId call_id);
Result<Ok> call_destroy(CallId call_id);
Result<Ok> call_destroy_all();
 
}  // namespace tde2e_api