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