1 // Copyright 2013 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 GOOGLE_APIS_CUP_CLIENT_UPDATE_PROTOCOL_H_ 6 #define GOOGLE_APIS_CUP_CLIENT_UPDATE_PROTOCOL_H_ 7 8 #include <string> 9 #include <vector> 10 11 #include "base/basictypes.h" 12 #include "base/memory/scoped_ptr.h" 13 #include "base/strings/string_piece.h" 14 15 // Forward declare types for NSS. 16 #if defined(USE_NSS) || defined(OS_WIN) || defined(OS_MACOSX) 17 typedef struct SECKEYPublicKeyStr SECKEYPublicKey; 18 #endif 19 20 // Client Update Protocol, or CUP, is used by Google Update (Omaha) servers to 21 // ensure freshness and authenticity of update checks over HTTP, without the 22 // overhead of HTTPS -- namely, no PKI, no guarantee of privacy, and no request 23 // replay protection (since update checks are idempotent). 24 // 25 // http://omaha.googlecode.com/svn/wiki/cup.html 26 // 27 // Each ClientUpdateProtocol represents a single update check in flight -- a 28 // call to SignRequest() generates internal state used by ValidateResponse(). 29 // 30 // This implementation does not persist client proofs by design. 31 class ClientUpdateProtocol { 32 public: 33 ~ClientUpdateProtocol(); 34 35 // Initializes this instance of CUP with a versioned public key. |key_version| 36 // must be non-negative. |public_key| is expected to be a DER-encoded ASN.1 37 // Subject Public Key Info. Returns a NULL pointer on failure. 38 static scoped_ptr<ClientUpdateProtocol> Create( 39 int key_version, const base::StringPiece& public_key); 40 41 // Returns a versioned encrypted secret (v|w) in a URL-safe Base64 encoding. 42 // Add to your URL before calling SignRequest(). 43 std::string GetVersionedSecret() const; 44 45 // Generates freshness/authentication data for an outgoing update check. 46 // |url| contains the the URL that the request will be sent to; it should 47 // include GetVersionedSecret() in its query string. This needs to be 48 // formatted in the way that the Omaha server expects: omit the scheme and 49 // any port number. (e.g. "//tools.google.com/service/update2?w=1:abcdef") 50 // |request_body| contains the body of the update check request in UTF-8. 51 // 52 // On success, returns true, and |client_proof| receives a Base64-encoded 53 // client proof, which should be sent in the If-Match HTTP header. On 54 // failure, returns false, and |client_proof| is not modified. 55 // 56 // This method will store internal state in this instance used by calls to 57 // ValidateResponse(); if you need to have multiple update checks in flight, 58 // initialize a separate CUP instance for each one. 59 bool SignRequest(const base::StringPiece& url, 60 const base::StringPiece& request_body, 61 std::string* client_proof); 62 63 // Validates a response given to a update check request previously signed 64 // with SignRequest(). |request_body| contains the body of the response in 65 // UTF-8. |server_cookie| contains the persisted credential cookie provided 66 // by the server. |server_proof| contains the Base64-encoded server proof, 67 // which is passed in the ETag HTTP header. Returns true if the response is 68 // valid. 69 // This method uses internal state that is set by a prior SignRequest() call. 70 bool ValidateResponse(const base::StringPiece& response_body, 71 const base::StringPiece& server_cookie, 72 const base::StringPiece& server_proof); 73 74 private: 75 friend class CupTest; 76 77 explicit ClientUpdateProtocol(int key_version); 78 79 // Decodes |public_key| into the appropriate internal structures. Returns 80 // the length of the public key (modulus) in bytes, or 0 on failure. 81 bool LoadPublicKey(const base::StringPiece& public_key); 82 83 // Returns the size of the public key in bytes, or 0 on failure. 84 size_t PublicKeyLength(); 85 86 // Helper function for BuildSharedKey() -- encrypts |key_source| (r) using 87 // the loaded public key, filling out |encrypted_key_source_| (w). 88 // Returns true on success. 89 bool EncryptKeySource(const std::vector<uint8>& key_source); 90 91 // Generates a random key source and passes it to DeriveSharedKey(). 92 // Returns true on success. 93 bool BuildRandomSharedKey(); 94 95 // Sets a fixed key source from a character string and passes it to 96 // DeriveSharedKey(). Used for unit testing only. Returns true on success. 97 bool SetSharedKeyForTesting(const base::StringPiece& fixed_key_source); 98 99 // Given a key source (r), derives the values of |shared_key_| (sk') and 100 // encrypted_key_source_ (w). Returns true on success. 101 bool DeriveSharedKey(const std::vector<uint8>& source); 102 103 // The server keeps multiple private keys; a version must be sent so that 104 // the right private key is used to decode the versioned secret. (The CUP 105 // specification calls this "v".) 106 int pub_key_version_; 107 108 // Holds the shared key, which is used to generate an HMAC signature for both 109 // the update check request and the update response. The client builds it 110 // locally, but sends the server an encrypted copy of the key source to 111 // synthesize it on its own. (The CUP specification calls this "sk'".) 112 std::vector<uint8> shared_key_; 113 114 // Holds the original contents of key_source_ that have been encrypted with 115 // the server's public key. The client sends this, along with the version of 116 // the keypair that was used, to the server. The server decrypts it using its 117 // private key to get the contents of key_source_, from which it recreates the 118 // shared key. (The CUP specification calls this "w".) 119 std::vector<uint8> encrypted_key_source_; 120 121 // Holds the hash of the update check request, the URL that it was sent to, 122 // and the versioned secret. This is filled out by a successful call to 123 // SignRequest(), and used by ValidateResponse() to confirm that the server 124 // has successfully decoded the versioned secret and signed the response using 125 // the same shared key as our own. (The CUP specification calls this "hw".) 126 std::vector<uint8> client_challenge_hash_; 127 128 // The public key used to encrypt the key source. (The CUP specification 129 // calls this "pk[v]".) 130 #if defined(USE_NSS) || defined(OS_WIN) || defined(OS_MACOSX) 131 SECKEYPublicKey* public_key_; 132 #endif 133 134 DISALLOW_IMPLICIT_CONSTRUCTORS(ClientUpdateProtocol); 135 }; 136 137 #endif // GOOGLE_APIS_CUP_CLIENT_UPDATE_PROTOCOL_H_ 138 139
