e2ee.h

/*
 * Copyright 2025 LiveKit
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an “AS IS” BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#pragma once
 
#include <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <vector>
 
#include "livekit/visibility.h"
 
namespace livekit {
 
enum class EncryptionType {
  NONE = 0,
  GCM = 1,
  CUSTOM = 2,
};
 
enum class KeyDerivationFunction {
  PBKDF2 = 0,
  HKDF = 1,
};
 
inline constexpr const char* kDefaultRatchetSalt = "LKFrameEncryptionKey";
inline constexpr int kDefaultRatchetWindowSize = 16;
inline constexpr int kDefaultFailureTolerance = -1;
inline constexpr int kDefaultKeyRingSize = 16;
inline constexpr KeyDerivationFunction kDefaultKeyDerivationFunction = KeyDerivationFunction::PBKDF2;
 
struct KeyProviderOptions {
  std::optional<std::vector<std::uint8_t>> shared_key;
 
  std::vector<std::uint8_t> ratchet_salt = std::vector<std::uint8_t>(
      kDefaultRatchetSalt, kDefaultRatchetSalt + std::char_traits<char>::length(kDefaultRatchetSalt));
 
  int ratchet_window_size = kDefaultRatchetWindowSize;
 
  int failure_tolerance = kDefaultFailureTolerance;
 
  int key_ring_size = kDefaultKeyRingSize;
 
  KeyDerivationFunction key_derivation_function = kDefaultKeyDerivationFunction;
};
 
struct E2EEOptions {
  KeyProviderOptions key_provider_options{};
  EncryptionType encryption_type = EncryptionType::GCM; // default & recommended
};
 
class LIVEKIT_API E2EEManager {
public:
  class LIVEKIT_API KeyProvider {
  public:
    ~KeyProvider() = default;
 
    KeyProvider(const KeyProvider&) = delete;
    KeyProvider& operator=(const KeyProvider&) = delete;
    KeyProvider(KeyProvider&&) noexcept = default;
    KeyProvider& operator=(KeyProvider&&) noexcept = default;
 
    const KeyProviderOptions& options() const;
 
    void setSharedKey(const std::vector<std::uint8_t>& key, int key_index = 0);
 
    std::vector<std::uint8_t> exportSharedKey(int key_index = 0) const;
 
    std::vector<std::uint8_t> ratchetSharedKey(int key_index = 0);
 
    void setKey(const std::string& participant_identity, const std::vector<std::uint8_t>& key, int key_index = 0);
 
    std::vector<std::uint8_t> exportKey(const std::string& participant_identity, int key_index = 0) const;
 
    std::vector<std::uint8_t> ratchetKey(const std::string& participant_identity, int key_index = 0);
 
  private:
    friend class E2EEManager;
    KeyProvider(std::uint64_t room_handle, KeyProviderOptions options);
    std::uint64_t room_handle_{0};
    KeyProviderOptions options_;
  };
 
  class LIVEKIT_API FrameCryptor {
  public:
    FrameCryptor(std::uint64_t room_handle, std::string participant_identity, int key_index, bool enabled);
    ~FrameCryptor() = default;
    FrameCryptor(const FrameCryptor&) = delete;
    FrameCryptor& operator=(const FrameCryptor&) = delete;
    FrameCryptor(FrameCryptor&&) noexcept = default;
    FrameCryptor& operator=(FrameCryptor&&) noexcept = default;
 
    const std::string& participantIdentity() const;
    int keyIndex() const;
    bool enabled() const;
 
    void setEnabled(bool enabled);
 
    void setKeyIndex(int key_index);
 
  private:
    std::uint64_t room_handle_{0};
    bool enabled_{false};
    std::string participant_identity_;
    int key_index_{0};
  };
 
  ~E2EEManager() = default;
  E2EEManager(const E2EEManager&) = delete;
  E2EEManager& operator=(const E2EEManager&) = delete;
  E2EEManager(E2EEManager&&) noexcept = delete;
  E2EEManager& operator=(E2EEManager&&) noexcept = delete;
 
  bool enabled() const;
 
  void setEnabled(bool enabled);
 
  std::weak_ptr<KeyProvider> keyProvider();
  std::weak_ptr<const KeyProvider> keyProvider() const;
 
  std::vector<E2EEManager::FrameCryptor> frameCryptors() const;
 
protected:
  explicit E2EEManager(std::uint64_t room_handle, const E2EEOptions& options);
  friend class Room;
 
private:
  std::uint64_t room_handle_{0};
  bool enabled_{false};
  E2EEOptions options_;
  std::shared_ptr<KeyProvider> key_provider_;
};
 
} // namespace livekit