1 // Copyright 2012 The Chromium Authors
2 // Use of this source code is governed by a BSD-style license that can be
3 // found in the LICENSE file.
5 #ifndef CRYPTO_P224_SPAKE_H_
6 #define CRYPTO_P224_SPAKE_H_
11 #include <string_view>
13 #include "base/gtest_prod_util.h"
14 #include "crypto/sha2.h"
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.
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.)
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.
37 // In each exchange, each peer always sends a message.
38 class CRYPTO_EXPORT P224EncryptedKeyExchange {
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.
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, std::string_view password);
60 // GetNextMessage returns a byte string which must be passed to the other
61 // party in the authentication.
62 const std::string& GetNextMessage();
64 // ProcessMessage processes a message which must have been generated by a
65 // call to GetNextMessage() by the other party.
66 Result ProcessMessage(std::string_view message);
68 // In the event that ProcessMessage() returns kResultFailed, error will
69 // return a human readable error message.
70 const std::string& error() const;
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;
76 // The key established as result of the key exchange. Can be called after
77 // the first ProcessMessage()
78 const std::string& GetUnverifiedKey() const;
81 // The authentication state machine is very simple and each party proceeds
82 // through each of these states, in order.
91 FRIEND_TEST_ALL_PREFIXES(MutualAuth, ExpectedValues);
95 // Sets internal random scalar. Should be used by tests only.
96 void SetXForTesting(const std::string& x);
99 const bool is_server_;
100 // next_message_ contains a value for GetNextMessage() to return.
101 std::string next_message_;
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);
112 // kScalarBytes is the number of bytes in a P-224 scalar.
113 static constexpr size_t kScalarBytes = 28;
114 // x_ is the secret Diffie-Hellman exponent (see paper referenced in .cc
116 uint8_t x_[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_[kScalarBytes];
120 // expected_authenticator_ is used to store the hash value expected from the
122 uint8_t expected_authenticator_[kSHA256Length];
127 } // namespace crypto
129 #endif // CRYPTO_P224_SPAKE_H_