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