crypto/p224_spake.h

   1 // Copyright 2012 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef CRYPTO_P224_SPAKE_H_
   6 #define CRYPTO_P224_SPAKE_H_
   7
   8 #include <stdint.h>
   9
  10 #include <string>
  11 #include <string_view>
  12
  13 #include "base/gtest_prod_util.h"
  14 #include "crypto/sha2.h"
  15
  16 namespace crypto {
  17
  18 // P224EncryptedKeyExchange implements SPAKE2, a variant of Encrypted
  19 // Key Exchange. It allows two parties that have a secret common
  20 // password to establish a common secure key by exchanging messages
  21 // over an insecure channel without disclosing the password.
  22 //
  23 // The password can be low entropy as authenticating with an attacker only
  24 // gives the attacker a one-shot password oracle. No other information about
  25 // the password is leaked. (However, you must be sure to limit the number of
  26 // permitted authentication attempts otherwise they get many one-shot oracles.)
  27 //
  28 // The protocol requires several RTTs (actually two, but you shouldn't assume
  29 // that.) To use the object, call GetNextMessage() and pass that message to the
  30 // peer. Get a message from the peer and feed it into ProcessMessage. Then
  31 // examine the return value of ProcessMessage:
  32 //   kResultPending: Another round is required. Call GetNextMessage and repeat.
  33 //   kResultFailed: The authentication has failed. You can get a human readable
  34 //       error message by calling error().
  35 //   kResultSuccess: The authentication was successful.
  36 //
  37 // In each exchange, each peer always sends a message.
  38 class CRYPTO_EXPORT P224EncryptedKeyExchange {
  39  public:
  40   enum Result {
  41     kResultPending,
  42     kResultFailed,
  43     kResultSuccess,
  44   };
  45
  46   // PeerType's values are named client and server due to convention. But
  47   // they could be called "A" and "B" as far as the protocol is concerned so
  48   // long as the two parties don't both get the same label.
  49   enum PeerType {
  50     kPeerTypeClient,
  51     kPeerTypeServer,
  52   };
  53
  54   // peer_type: the type of the local authentication party.
  55   // password: secret session password. Both parties to the
  56   //     authentication must pass the same value. For the case of a
  57   //     TLS connection, see RFC 5705.
  58   P224EncryptedKeyExchange(PeerType peer_type, std::string_view password);
  59
  60   // GetNextMessage returns a byte string which must be passed to the other
  61   // party in the authentication.
  62   const std::string& GetNextMessage();
  63
  64   // ProcessMessage processes a message which must have been generated by a
  65   // call to GetNextMessage() by the other party.
  66   Result ProcessMessage(std::string_view message);
  67
  68   // In the event that ProcessMessage() returns kResultFailed, error will
  69   // return a human readable error message.
  70   const std::string& error() const;
  71
  72   // The key established as result of the key exchange. Must be called
  73   // at then end after ProcessMessage() returns kResultSuccess.
  74   const std::string& GetKey() const;
  75
  76   // The key established as result of the key exchange. Can be called after
  77   // the first ProcessMessage()
  78   const std::string& GetUnverifiedKey() const;
  79
  80  private:
  81   // The authentication state machine is very simple and each party proceeds
  82   // through each of these states, in order.
  83   enum State {
  84     kStateInitial,
  85     kStateRecvDH,
  86     kStateSendHash,
  87     kStateRecvHash,
  88     kStateDone,
  89   };
  90
  91   FRIEND_TEST_ALL_PREFIXES(MutualAuth, ExpectedValues);
  92
  93   void Init();
  94
  95   // Sets internal random scalar. Should be used by tests only.
  96   void SetXForTesting(const std::string& x);
  97
  98   State state_;
  99   const bool is_server_;
 100   // next_message_ contains a value for GetNextMessage() to return.
 101   std::string next_message_;
 102   std::string error_;
 103
 104   // CalculateHash computes the verification hash for the given peer and writes
 105   // |kSHA256Length| bytes at |out_digest|.
 106   void CalculateHash(PeerType peer_type,
 107                      const std::string& client_masked_dh,
 108                      const std::string& server_masked_dh,
 109                      const std::string& k,
 110                      uint8_t* out_digest);
 111
 112   // kScalarBytes is the number of bytes in a P-224 scalar.
 113   static constexpr size_t kScalarBytes = 28;
 114   // x_ is the secret Diffie-Hellman exponent (see paper referenced in .cc
 115   // file).
 116   uint8_t x_[kScalarBytes];
 117   // pw_ is SHA256(P(password), P(session))[:28] where P() prepends a uint32_t,
 118   // big-endian length prefix (see paper referenced in .cc file).
 119   uint8_t pw_[kScalarBytes];
 120   // expected_authenticator_ is used to store the hash value expected from the
 121   // other party.
 122   uint8_t expected_authenticator_[kSHA256Length];
 123
 124   std::string key_;
 125 };
 126
 127 }  // namespace crypto
 128
 129 #endif  // CRYPTO_P224_SPAKE_H_