Chromium Code Reviews| Index: google_apis/cup/client_update_protocol.h |
| =================================================================== |
| --- google_apis/cup/client_update_protocol.h (revision 0) |
| +++ google_apis/cup/client_update_protocol.h (revision 0) |
| @@ -0,0 +1,132 @@ |
| +// Copyright (c) 2013 The Chromium Authors. All rights reserved. |
| +// Use of this source code is governed by a BSD-style license that can be |
| +// found in the LICENSE file. |
| + |
| +#ifndef GOOGLE_APIS_CUP_CLIENT_UPDATE_PROTOCOL_H_ |
| +#define GOOGLE_APIS_CUP_CLIENT_UPDATE_PROTOCOL_H_ |
| + |
| +#include <string> |
| +#include <vector> |
| + |
| +#include "base/basictypes.h" |
| +#include "base/memory/scoped_ptr.h" |
| +#include "base/strings/string_piece.h" |
| + |
| +// Client Update Protocol, or CUP, is used by Google Update (Omaha) servers to |
| +// ensure freshness and authenticity of update checks over HTTP, without the |
| +// overhead of HTTPS -- namely, no PKI, no guarantee of privacy, and no request |
| +// replay protection (since update checks are idempotent). |
| +// |
| +// http://omaha.googlecode.com/svn/wiki/cup.html |
| +// |
| +// This implementation does not persist client proofs by design. |
| +class ClientUpdateProtocol { |
| + public: |
| + ~ClientUpdateProtocol(); |
| + |
| + // Initializes this instance of CUP with a versioned public key. |key_version| |
| + // must be non-negative. |public_key| is expected to be a DER-encoded ASN.1 |
| + // Subject Public Key Info. Returns NULL on failure. |
| + static ClientUpdateProtocol* Create(int key_version, |
| + const base::StringPiece& public_key); |
| + |
| + // Returns a versioned encrypted secret (v|w) in a URL-safe Base64 encoding. |
| + // Add to your URL before calling SignRequest(). |
| + std::string GetVersionedSecret() const; |
| + |
| + // Generates freshness/authentication data for an outgoing update check. |
| + // |url| contains the the URL that the request will be sent to; it should |
| + // include GetVersionedSecret() in its query string. This needs to be |
| + // formatted in the way that the Omaha server expects: omit the scheme and |
| + // any port number. (e.g. "//tools.google.com/service/update2?w=1:abcdef") |
| + // |request_body| contains the body of the update check request in UTF-8. |
| + // |
| + // On success, returns true, and |cp_out| receives a Base64-encoded client |
| + // proof, which should be sent in the If-Match HTTP header. On failure, |
| + // returns false, and |cp_out| is not modified. |
| + // |
| + // This method will store internal state in this instance used by calls to |
| + // ValidateResponse(); if you need to have multiple update checks in flight, |
| + // initialize a separate CUP instance for each one. |
| + bool SignRequest(const base::StringPiece& url, |
| + const base::StringPiece& request_body, |
| + std::string* client_proof); |
| + |
| + // Validates a response given to a update check request previously signed |
| + // with SignRequest(). |request_body| contains the body of the response in |
| + // UTF-8. |server_cookie| contains the persisted credential cookie provided |
| + // by the server. |server_proof| contains the Base64-encoded server proof, |
| + // which is passed in the ETag HTTP header. Returns true if the response is |
| + // valid. |
| + // This method uses internal state that is set by a prior SignRequest() call. |
| + bool ValidateResponse(const base::StringPiece& response_body, |
| + const base::StringPiece& server_cookie, |
| + const base::StringPiece& server_proof); |
| + |
| + // Internal interface to the public key used by ClientUpdateProtocol. |
| + // Implemented on a per-platform basis. |
| + class CupKeyImpl { |
| + public: |
| + virtual ~CupKeyImpl() {} |
| + |
| + // Returns the length of the public key's modulus in bytes, 0 on failure. |
| + virtual size_t PublicKeyLength() const = 0; |
| + |
| + // Encrypts |key_source| using the loaded public key. Returns the |
| + // encrypted result on success, or an empty vector on failure. |
| + virtual std::vector<uint8> EncryptKeySource( |
| + const std::vector<uint8>& key_source) = 0; |
|
Ryan Sleevi
2013/06/04 18:58:02
You don't need to do this.
We just use compile-ti
|
| + }; |
| + |
| + private: |
| + friend class CupUnitTest; |
| + |
| + // Constructor is private -- use the Create method above. |
| + explicit ClientUpdateProtocol(int key_version); |
| + |
| + // Generates a key source (r) and uses that to fill out |shared_key_| (sk') |
| + // and encrypted_key_source_ (w). If |opt_key_source| is non-NULL, the key |
| + // source is read from that location instead of being randomly generated. |
| + // (Used for unit testing.) Returns true on success. |
| + bool BuildSharedKey(size_t public_key_length, const uint8* opt_key_source); |
| + |
| + // The server keeps multiple private keys; a version must be sent so that |
| + // the right private key is used to decode the versioned secret. (The CUP |
| + // specification calls this "v".) |
| + int pub_key_version_; |
| + |
| + // Holds the shared key, which is used to generate an HMAC signature for both |
| + // the update check request and the update response. The client builds it |
| + // locally, but sends the server an encrypted copy of the key source to |
| + // synthesize it on its own. (The CUP specification calls this "sk'".) |
| + std::vector<uint8> shared_key_; |
| + |
| + // Holds the original contents of key_source_ that have been encrypted with |
| + // the server's public key. The client sends this, along with the version of |
| + // the keypair that was used, to the server. The server decrypts it using its |
| + // private key to get the contents of key_source_, from which it recreates the |
| + // shared key. (The CUP specification calls this "w".) |
| + std::vector<uint8> encrypted_key_source_; |
| + |
| + // Holds the hash of the update check request, the URL that it was sent to, |
| + // and the versioned secret. This is filled out by a successful call to |
| + // SignRequest(), and used by ValidateResponse() to confirm that the server |
| + // has successfully decoded the versioned secret and signed the response using |
| + // the same shared key as our own. (The CUP specification calls this "hw".) |
| + std::vector<uint8> client_challenge_hash_; |
| + |
| + // The public key used to encrypt the key source. (The CUP specification |
| + // calls this "pk[v]".) |
| + scoped_ptr<CupKeyImpl> public_key_impl_; |
| + |
| + // Helper function to generate an appropriate ClientUpdateProtocolKeyImpl for |
| + // this platform and load a public key into it. |public_key| should be a |
| + // DER-encoded ASN.1 Subject Public Key Info. Returns a pointer on the heap |
| + // (which the caller owns) on success, NULL on failure. |
| + static CupKeyImpl* GetCupKeyImpl(const base::StringPiece& public_key); |
| + |
| + DISALLOW_COPY_AND_ASSIGN(ClientUpdateProtocol); |
| +}; |
| + |
| +#endif // GOOGLE_APIS_CUP_CLIENT_UPDATE_PROTOCOL_H_ |
| + |