Home | History | Annotate | Download | only in crypto 
      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_
    115