1 // Copyright (c) 2011 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.
5 #ifndef CRYPTO_P224_SPAKE_H_
6 #define CRYPTO_P224_SPAKE_H_
9 #include <base/string_piece.h>
10 #include <crypto/p224.h>
11 #include <crypto/sha2.h>
15 // P224EncryptedKeyExchange implements SPAKE2, a variant of Encrypted
16 // Key Exchange. It allows two parties that have a secret common
17 // password to establish a common secure key by exchanging messages
18 // over unsecure channel without disclosing the password.
20 // The password can be low entropy as authenticating with an attacker only
21 // gives the attacker a one-shot password oracle. No other information about
22 // the password is leaked. (However, you must be sure to limit the number of
23 // permitted authentication attempts otherwise they get many one-shot oracles.)
25 // The protocol requires several RTTs (actually two, but you shouldn't assume
26 // that.) To use the object, call GetMessage() and pass that message to the
27 // peer. Get a message from the peer and feed it into ProcessMessage. Then
28 // examine the return value of ProcessMessage:
29 // kResultPending: Another round is required. Call GetMessage and repeat.
30 // kResultFailed: The authentication has failed. You can get a human readable
31 // error message by calling error().
32 // kResultSuccess: The authentication was successful.
34 // In each exchange, each peer always sends a message.
35 class CRYPTO_EXPORT P224EncryptedKeyExchange
{
43 // PeerType's values are named client and server due to convention. But
44 // they could be called "A" and "B" as far as the protocol is concerned so
45 // long as the two parties don't both get the same label.
51 // peer_type: the type of the local authentication party.
52 // password: secret session password. Both parties to the
53 // authentication must pass the same value. For the case of a
54 // TLS connection, see RFC 5705.
55 P224EncryptedKeyExchange(PeerType peer_type
,
56 const base::StringPiece
& password
);
58 // GetMessage returns a byte string which must be passed to the other party
59 // in the authentication.
60 const std::string
& GetMessage();
62 // ProcessMessage processes a message which must have been generated by a
63 // call to GetMessage() by the other party.
64 Result
ProcessMessage(const base::StringPiece
& message
);
66 // In the event that ProcessMessage() returns kResultFailed, error will
67 // return a human readable error message.
68 const std::string
& error() const;
70 // The key established as result of the key exchange. Must be called
71 // at then end after ProcessMessage() returns kResultSuccess.
72 const std::string
& GetKey();
75 // The authentication state machine is very simple and each party proceeds
76 // through each of these states, in order.
86 const bool is_server_
;
87 // next_message_ contains a value for GetMessage() to return.
88 std::string next_message_
;
91 // CalculateHash computes the verification hash for the given peer and writes
92 // |kSHA256Length| bytes at |out_digest|.
95 const std::string
& client_masked_dh
,
96 const std::string
& server_masked_dh
,
100 // x_ is the secret Diffie-Hellman exponent (see paper referenced in .cc
102 uint8 x_
[p224::kScalarBytes
];
103 // pw_ is SHA256(P(password), P(session))[:28] where P() prepends a uint32,
104 // big-endian length prefix (see paper refereneced in .cc file).
105 uint8 pw_
[p224::kScalarBytes
];
106 // expected_authenticator_ is used to store the hash value expected from the
108 uint8 expected_authenticator_
[kSHA256Length
];
113 } // namespace crypto
115 #endif // CRYPTO_P224_SPAKE_H_