15821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Copyright (c) 2012 The Chromium Authors. All rights reserved. 25821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Use of this source code is governed by a BSD-style license that can be 35821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// found in the LICENSE file. 45821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 55821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#ifndef CRYPTO_P224_SPAKE_H_ 65821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#define CRYPTO_P224_SPAKE_H_ 75821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 8c2e0dbddbe15c98d52c4786dac06cb8952a8ae6dTorne (Richard Coles)#include <base/strings/string_piece.h> 95821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <crypto/p224.h> 105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#include <crypto/sha2.h> 115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)namespace crypto { 135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// P224EncryptedKeyExchange implements SPAKE2, a variant of Encrypted 155821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// Key Exchange. It allows two parties that have a secret common 165821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// password to establish a common secure key by exchanging messages 175821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// over unsecure channel without disclosing the password. 185821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 195821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The password can be low entropy as authenticating with an attacker only 205821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// gives the attacker a one-shot password oracle. No other information about 215821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// the password is leaked. (However, you must be sure to limit the number of 225821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// permitted authentication attempts otherwise they get many one-shot oracles.) 235821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 245821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// The protocol requires several RTTs (actually two, but you shouldn't assume 255821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// that.) To use the object, call GetMessage() and pass that message to the 265821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// peer. Get a message from the peer and feed it into ProcessMessage. Then 275821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// examine the return value of ProcessMessage: 285821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// kResultPending: Another round is required. Call GetMessage and repeat. 295821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// kResultFailed: The authentication has failed. You can get a human readable 305821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// error message by calling error(). 315821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// kResultSuccess: The authentication was successful. 325821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// 335821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)// In each exchange, each peer always sends a message. 345821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)class CRYPTO_EXPORT P224EncryptedKeyExchange { 355821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) public: 365821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) enum Result { 375821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kResultPending, 385821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kResultFailed, 395821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kResultSuccess, 405821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 415821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 425821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // PeerType's values are named client and server due to convention. But 435821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // they could be called "A" and "B" as far as the protocol is concerned so 445821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // long as the two parties don't both get the same label. 455821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) enum PeerType { 465821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kPeerTypeClient, 475821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kPeerTypeServer, 485821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 495821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 505821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // peer_type: the type of the local authentication party. 515821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // password: secret session password. Both parties to the 525821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // authentication must pass the same value. For the case of a 535821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // TLS connection, see RFC 5705. 545821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) P224EncryptedKeyExchange(PeerType peer_type, 555821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const base::StringPiece& password); 565821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 575821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // GetMessage returns a byte string which must be passed to the other party 585821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // in the authentication. 595821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& GetMessage(); 605821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 615821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // ProcessMessage processes a message which must have been generated by a 625821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // call to GetMessage() by the other party. 635821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) Result ProcessMessage(const base::StringPiece& message); 645821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 655821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // In the event that ProcessMessage() returns kResultFailed, error will 665821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // return a human readable error message. 675821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& error() const; 685821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 695821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The key established as result of the key exchange. Must be called 705821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // at then end after ProcessMessage() returns kResultSuccess. 715821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& GetKey(); 725821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 735821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) private: 745821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // The authentication state machine is very simple and each party proceeds 755821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // through each of these states, in order. 765821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) enum State { 775821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kStateInitial, 785821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kStateRecvDH, 795821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kStateSendHash, 805821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kStateRecvHash, 815821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) kStateDone, 825821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) }; 835821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 845821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) State state_; 855821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const bool is_server_; 865821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // next_message_ contains a value for GetMessage() to return. 875821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) std::string next_message_; 885821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) std::string error_; 895821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 905821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // CalculateHash computes the verification hash for the given peer and writes 915821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // |kSHA256Length| bytes at |out_digest|. 925821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) void CalculateHash( 935821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) PeerType peer_type, 945821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& client_masked_dh, 955821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& server_masked_dh, 965821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) const std::string& k, 975821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) uint8* out_digest); 985821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 995821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // x_ is the secret Diffie-Hellman exponent (see paper referenced in .cc 1005821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // file). 1015821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) uint8 x_[p224::kScalarBytes]; 1025821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // pw_ is SHA256(P(password), P(session))[:28] where P() prepends a uint32, 1035821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // big-endian length prefix (see paper refereneced in .cc file). 1045821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) uint8 pw_[p224::kScalarBytes]; 1055821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // expected_authenticator_ is used to store the hash value expected from the 1065821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) // other party. 1075821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) uint8 expected_authenticator_[kSHA256Length]; 1085821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1095821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) std::string key_; 1105821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)}; 1115821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1125821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)} // namespace crypto 1135821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles) 1145821806d5e7f356e8fa4b058a389a808ea183019Torne (Richard Coles)#endif // CRYPTO_P224_SPAKE_H_ 115