google_apis/cup/client_update_protocol.h

   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