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 <crypto/p224.h>
      9 #include <crypto/sha2.h>
     10 #include <stdint.h>
     11 
     12 #include "base/gtest_prod_util.h"
     13 #include "base/strings/string_piece.h"
     14 
     15 namespace crypto {
     16 
     17 // P224EncryptedKeyExchange implements SPAKE2, a variant of Encrypted
     18 // Key Exchange. It allows two parties that have a secret common
     19 // password to establish a common secure key by exchanging messages
     20 // over an insecure channel without disclosing the password.
     21 //
     22 // The password can be low entropy as authenticating with an attacker only
     23 // gives the attacker a one-shot password oracle. No other information about
     24 // the password is leaked. (However, you must be sure to limit the number of
     25 // permitted authentication attempts otherwise they get many one-shot oracles.)
     26 //
     27 // The protocol requires several RTTs (actually two, but you shouldn't assume
     28 // that.) To use the object, call GetNextMessage() and pass that message to the
     29 // peer. Get a message from the peer and feed it into ProcessMessage. Then
     30 // examine the return value of ProcessMessage:
     31 //   kResultPending: Another round is required. Call GetNextMessage and repeat.
     32 //   kResultFailed: The authentication has failed. You can get a human readable
     33 //       error message by calling error().
     34 //   kResultSuccess: The authentication was successful.
     35 //
     36 // In each exchange, each peer always sends a message.
     37 class CRYPTO_EXPORT P224EncryptedKeyExchange {
     38  public:
     39   enum Result {
     40     kResultPending,
     41     kResultFailed,
     42     kResultSuccess,
     43   };
     44 
     45   // PeerType's values are named client and server due to convention. But
     46   // they could be called "A" and "B" as far as the protocol is concerned so
     47   // long as the two parties don't both get the same label.
     48   enum PeerType {
     49     kPeerTypeClient,
     50     kPeerTypeServer,
     51   };
     52 
     53   // peer_type: the type of the local authentication party.
     54   // password: secret session password. Both parties to the
     55   //     authentication must pass the same value. For the case of a
     56   //     TLS connection, see RFC 5705.
     57   P224EncryptedKeyExchange(PeerType peer_type,
     58                            const base::StringPiece& 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(const base::StringPiece& 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   // x_ is the secret Diffie-Hellman exponent (see paper referenced in .cc
    113   // file).
    114   uint8_t x_[p224::kScalarBytes];
    115   // pw_ is SHA256(P(password), P(session))[:28] where P() prepends a uint32_t,
    116   // big-endian length prefix (see paper referenced in .cc file).
    117   uint8_t pw_[p224::kScalarBytes];
    118   // expected_authenticator_ is used to store the hash value expected from the
    119   // other party.
    120   uint8_t expected_authenticator_[kSHA256Length];
    121 
    122   std::string key_;
    123 };
    124 
    125 }  // namespace crypto
    126 
    127 #endif  // CRYPTO_P224_SPAKE_H_
    128