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