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
12namespace 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.
34class 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