crypto/p224_spake.h

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