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