fizz::KeyScheduler Class Reference

#include <KeyScheduler.h>

Inheritance diagram for fizz::KeyScheduler:

Classes
struct	AppTrafficSecret
struct	EarlySecret
struct	HandshakeSecret
struct	MasterSecret

Public Member Functions
	KeyScheduler (std::unique_ptr< KeyDerivation > deriver)
virtual	~KeyScheduler ()=default
virtual void	deriveEarlySecret (folly::ByteRange psk)
virtual void	deriveHandshakeSecret ()
virtual void	deriveHandshakeSecret (folly::ByteRange ecdhe)
virtual void	deriveMasterSecret ()
virtual void	deriveAppTrafficSecrets (folly::ByteRange transcript)
virtual void	clearMasterSecret ()
virtual uint32_t	clientKeyUpdate ()
virtual uint32_t	serverKeyUpdate ()
virtual std::vector< uint8_t >	getSecret (EarlySecrets s, folly::ByteRange transcript) const
virtual std::vector< uint8_t >	getSecret (HandshakeSecrets s, folly::ByteRange transcript) const
virtual std::vector< uint8_t >	getSecret (MasterSecrets s, folly::ByteRange transcript) const
virtual std::vector< uint8_t >	getSecret (AppTrafficSecrets s) const
virtual TrafficKey	getTrafficKey (folly::ByteRange trafficSecret, size_t keyLength, size_t ivLength) const
virtual Buf	getResumptionSecret (folly::ByteRange resumptionMasterSecret, folly::ByteRange ticketNonce) const

Private Attributes
folly::Optional< boost::variant< EarlySecret, HandshakeSecret, MasterSecret > >	secret_
folly::Optional< AppTrafficSecret >	appTrafficSecret_
std::unique_ptr< KeyDerivation >	deriver_

Detailed Description

Keeps track of the TLS 1.3 key derivation schedule.

Definition at line 33 of file KeyScheduler.h.

Constructor & Destructor Documentation

fizz::KeyScheduler::KeyScheduler ( std::unique_ptr< KeyDerivation >  deriver )

inlineexplicit

Definition at line 35 of file KeyScheduler.h.

References s, and uint32_t.

      : deriver_(std::move(deriver)) {}

virtual fizz::KeyScheduler::~KeyScheduler ( )

virtualdefault

Member Function Documentation

void fizz::KeyScheduler::clearMasterSecret ( )

virtual

Clears the master secret. Must be in master secret state.

Definition at line 85 of file KeyScheduler.cpp.

References folly::none.

Referenced by fizz::sm::generateTicket(), and fizz::sm::handleCertMsg().

                                     {
  boost::get<MasterSecret>(*secret_);
  secret_ = folly::none;
}

uint32_t fizz::KeyScheduler::clientKeyUpdate ( )

virtual

Performs a key update on the client traffic key. Traffic secrets must be derived.

Definition at line 90 of file KeyScheduler.cpp.

References appTrafficSecret_, folly::IOBuf::create(), deriver_, kTrafficKeyUpdate, and folly::range().

Referenced by fizz::sm::generateTicket(), and fizz::sm::getMaxEarlyDataSize().

                                       {
  auto& appTrafficSecret = *appTrafficSecret_;
  auto buf = deriver_->expandLabel(
      folly::range(appTrafficSecret.client),
      kTrafficKeyUpdate,
      folly::IOBuf::create(0),
      deriver_->hashLength());
  buf->coalesce();
  appTrafficSecret.client = std::vector<uint8_t>(buf->data(), buf->tail());
  return ++appTrafficSecret.clientGeneration;
}

void fizz::KeyScheduler::deriveAppTrafficSecrets ( folly::ByteRange  transcript )

virtual

Derives the app traffic secrets given the handshake context. Must be in master secret state. Note that this does not clear the master secret.

Definition at line 75 of file KeyScheduler.cpp.

References appTrafficSecret_, fizz::KeyScheduler::AppTrafficSecret::client, deriver_, kClientAppTraffic, kServerAppTraffic, folly::gen::move, folly::range(), and fizz::KeyScheduler::AppTrafficSecret::server.

Referenced by fizz::sm::handleCertMsg().

                                                                    {
  auto& masterSecret = boost::get<MasterSecret>(*secret_);
  AppTrafficSecret trafficSecret;
  trafficSecret.client = deriver_->deriveSecret(
      folly::range(masterSecret.secret), kClientAppTraffic, transcript);
  trafficSecret.server = deriver_->deriveSecret(
      folly::range(masterSecret.secret), kServerAppTraffic, transcript);
  appTrafficSecret_ = std::move(trafficSecret);
}

void fizz::KeyScheduler::deriveEarlySecret ( folly::ByteRange  psk )

virtual

Derives the early secret. Must be in uninitialized state.

Definition at line 32 of file KeyScheduler.cpp.

References deriver_, folly::range(), and secret_.

Referenced by fizz::sm::encodeAndAddBinders().

                                                       {
  if (secret_) {
    throw std::runtime_error("secret already set");
  }

  auto zeros = std::vector<uint8_t>(deriver_->hashLength(), 0);
  secret_ = EarlySecret{deriver_->hkdfExtract(folly::range(zeros), psk)};
}

void fizz::KeyScheduler::deriveHandshakeSecret ( )

virtual

Derives the master secert. Must be in early secret state.

Definition at line 41 of file KeyScheduler.cpp.

References deriver_, kDerivedSecret, and folly::range().

Referenced by fizz::sm::doKex().

                                         {
  auto& earlySecret = boost::get<EarlySecret>(*secret_);
  auto zeros = std::vector<uint8_t>(deriver_->hashLength(), 0);
  auto preSecret = deriver_->deriveSecret(
      folly::range(earlySecret.secret), kDerivedSecret, deriver_->blankHash());
  secret_ = HandshakeSecret{
      deriver_->hkdfExtract(folly::range(preSecret), folly::range(zeros))};
}

void fizz::KeyScheduler::deriveHandshakeSecret ( folly::ByteRange  ecdhe )

virtual

Derives the master secret with a DH secret. Must be in uninitialized or early secret state.

Definition at line 50 of file KeyScheduler.cpp.

References deriver_, kDerivedSecret, folly::range(), and secret_.

                                                             {
  if (!secret_) {
    auto zeros = std::vector<uint8_t>(deriver_->hashLength(), 0);
    secret_ = EarlySecret{
        deriver_->hkdfExtract(folly::range(zeros), folly::range(zeros))};
  }

  auto& earlySecret = boost::get<EarlySecret>(*secret_);
  auto preSecret = deriver_->deriveSecret(
      folly::range(earlySecret.secret), kDerivedSecret, deriver_->blankHash());
  secret_ =
      HandshakeSecret{deriver_->hkdfExtract(folly::range(preSecret), ecdhe)};
}

void fizz::KeyScheduler::deriveMasterSecret ( )

virtual

Derives the master secert. Must be in handshake secret state.

Definition at line 64 of file KeyScheduler.cpp.

References deriver_, kDerivedSecret, and folly::range().

Referenced by fizz::sm::handleCertMsg().

                                      {
  auto zeros = std::vector<uint8_t>(deriver_->hashLength(), 0);
  auto& handshakeSecret = boost::get<HandshakeSecret>(*secret_);
  auto preSecret = deriver_->deriveSecret(
      folly::range(handshakeSecret.secret),
      kDerivedSecret,
      deriver_->blankHash());
  secret_ = MasterSecret{
      deriver_->hkdfExtract(folly::range(preSecret), folly::range(zeros))};
}

Buf fizz::KeyScheduler::getResumptionSecret ( folly::ByteRange  resumptionMasterSecret, folly::ByteRange  ticketNonce  ) const

virtual

Derive a resumption secret with a particular ticket nonce. Does not require being in master secret state.

Definition at line 204 of file KeyScheduler.cpp.

References deriver_, kResumption, and folly::IOBuf::wrapBuffer().

Referenced by fizz::sm::generateTicket(), and fizz::sm::getMaxEarlyDataSize().

                                      {
  return deriver_->expandLabel(
      resumptionMasterSecret,
      kResumption,
      folly::IOBuf::wrapBuffer(ticketNonce),
      deriver_->hashLength());
}

std::vector< uint8_t > fizz::KeyScheduler::getSecret ( EarlySecrets  s, folly::ByteRange  transcript  ) const

virtual

Retreive a secret from the scheduler. Must be in the appropriate state.

Reimplemented in fizz::LoggingKeyScheduler.

Definition at line 114 of file KeyScheduler.cpp.

References fizz::ClientEarlyTraffic, deriver_, fizz::EarlyExporter, fizz::ExternalPskBinder, kClientEarlyTraffic, kEarlyExporter, kExternalPskBinder, kResumptionPskBinder, fizz::test::label, folly::range(), and fizz::ResumptionPskBinder.

Referenced by fizz::sm::encodeAndAddBinders(), fizz::sm::generateTicket(), fizz::sm::getMaxEarlyDataSize(), fizz::LoggingKeyScheduler::getSecret(), and fizz::sm::handleCertMsg().

                                     {
  StringPiece label;
  switch (s) {
    case EarlySecrets::ExternalPskBinder:
      label = kExternalPskBinder;
      break;
    case EarlySecrets::ResumptionPskBinder:
      label = kResumptionPskBinder;
      break;
    case EarlySecrets::ClientEarlyTraffic:
      label = kClientEarlyTraffic;
      break;
    case EarlySecrets::EarlyExporter:
      label = kEarlyExporter;
      break;
    default:
      LOG(FATAL) << "unknown secret";
  }

  auto& earlySecret = boost::get<EarlySecret>(*secret_);
  return deriver_->deriveSecret(
      folly::range(earlySecret.secret), label, transcript);
}

std::vector< uint8_t > fizz::KeyScheduler::getSecret ( HandshakeSecrets  s, folly::ByteRange  transcript  ) const

virtual

Reimplemented in fizz::LoggingKeyScheduler.

Definition at line 140 of file KeyScheduler.cpp.

References fizz::ClientHandshakeTraffic, deriver_, kClientHandshakeTraffic, kServerHandshakeTraffic, fizz::test::label, folly::range(), and fizz::ServerHandshakeTraffic.

                                     {
  StringPiece label;
  switch (s) {
    case HandshakeSecrets::ClientHandshakeTraffic:
      label = kClientHandshakeTraffic;
      break;
    case HandshakeSecrets::ServerHandshakeTraffic:
      label = kServerHandshakeTraffic;
      break;
    default:
      LOG(FATAL) << "unknown secret";
  }

  auto& handshakeSecret = boost::get<HandshakeSecret>(*secret_);
  return deriver_->deriveSecret(
      folly::range(handshakeSecret.secret), label, transcript);
}

std::vector< uint8_t > fizz::KeyScheduler::getSecret ( MasterSecrets  s, folly::ByteRange  transcript  ) const

virtual

Definition at line 160 of file KeyScheduler.cpp.

References deriver_, fizz::ExporterMaster, kExporterMaster, kResumptionMaster, fizz::test::label, folly::range(), and fizz::ResumptionMaster.

                                     {
  StringPiece label;
  switch (s) {
    case MasterSecrets::ExporterMaster:
      label = kExporterMaster;
      break;
    case MasterSecrets::ResumptionMaster:
      label = kResumptionMaster;
      break;
    default:
      LOG(FATAL) << "unknown secret";
  }

  auto& masterSecret = boost::get<MasterSecret>(*secret_);
  return deriver_->deriveSecret(
      folly::range(masterSecret.secret), label, transcript);
}

std::vector< uint8_t > fizz::KeyScheduler::getSecret ( AppTrafficSecrets  s ) const

virtual

Reimplemented in fizz::LoggingKeyScheduler.

Definition at line 180 of file KeyScheduler.cpp.

References appTrafficSecret_, fizz::ClientAppTraffic, and fizz::ServerAppTraffic.

                                                                    {
  auto& appTrafficSecret = *appTrafficSecret_;
  switch (s) {
    case AppTrafficSecrets::ClientAppTraffic:
      return appTrafficSecret.client;
    case AppTrafficSecrets::ServerAppTraffic:
      return appTrafficSecret.server;
    default:
      LOG(FATAL) << "unknown secret";
  }
}

TrafficKey fizz::KeyScheduler::getTrafficKey ( folly::ByteRange  trafficSecret, size_t  keyLength, size_t  ivLength  ) const

virtual

Derive a traffic key and iv from a traffic secret.

Definition at line 192 of file KeyScheduler.cpp.

References folly::IOBuf::create(), deriver_, fizz::TrafficKey::iv, fizz::TrafficKey::key, kTrafficIv, and kTrafficKey.

Referenced by fizz::Protocol::setAead().

                           {
  TrafficKey trafficKey;
  trafficKey.key = deriver_->expandLabel(
      trafficSecret, kTrafficKey, folly::IOBuf::create(0), keyLength);
  trafficKey.iv = deriver_->expandLabel(
      trafficSecret, kTrafficIv, folly::IOBuf::create(0), ivLength);
  return trafficKey;
}

uint32_t fizz::KeyScheduler::serverKeyUpdate ( )

virtual

Performs a key update on the server traffic key. Traffic secrets must be derived.

Definition at line 102 of file KeyScheduler.cpp.

References appTrafficSecret_, folly::IOBuf::create(), deriver_, kTrafficKeyUpdate, and folly::range().

Referenced by fizz::sm::generateTicket(), and fizz::sm::getMaxEarlyDataSize().

                                       {
  auto& appTrafficSecret = *appTrafficSecret_;
  auto buf = deriver_->expandLabel(
      folly::range(appTrafficSecret.server),
      kTrafficKeyUpdate,
      folly::IOBuf::create(0),
      deriver_->hashLength());
  buf->coalesce();
  appTrafficSecret.server = std::vector<uint8_t>(buf->data(), buf->tail());
  return ++appTrafficSecret.serverGeneration;
}

Member Data Documentation

folly::Optional<AppTrafficSecret> fizz::KeyScheduler::appTrafficSecret_

private

Definition at line 132 of file KeyScheduler.h.

Referenced by clientKeyUpdate(), deriveAppTrafficSecrets(), getSecret(), and serverKeyUpdate().

std::unique_ptr<KeyDerivation> fizz::KeyScheduler::deriver_

private

Definition at line 134 of file KeyScheduler.h.

Referenced by clientKeyUpdate(), deriveAppTrafficSecrets(), deriveEarlySecret(), deriveHandshakeSecret(), deriveMasterSecret(), getResumptionSecret(), getSecret(), getTrafficKey(), and serverKeyUpdate().

folly::Optional<boost::variant<EarlySecret, HandshakeSecret, MasterSecret> > fizz::KeyScheduler::secret_

private

Definition at line 131 of file KeyScheduler.h.

Referenced by deriveEarlySecret(), and deriveHandshakeSecret().

---

The documentation for this class was generated from the following files:

• proxygen/fizz/fizz/protocol/KeyScheduler.h
• proxygen/fizz/fizz/protocol/KeyScheduler.cpp