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