google_apis/cup/client_update_protocol.h

// Copyright 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"

// Forward declare types for NSS.
#if defined(USE_NSS) || defined(OS_WIN) || defined(OS_MACOSX)
typedef struct SECKEYPublicKeyStr SECKEYPublicKey;
#endif

// 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
//
// Each ClientUpdateProtocol represents a single update check in flight -- a
// call to SignRequest() generates internal state used by ValidateResponse().
//
// 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 a NULL pointer on failure.
  static scoped_ptr<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 |client_proof| receives a Base64-encoded
  // client proof, which should be sent in the If-Match HTTP header. On
  // failure, returns false, and |client_proof| 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);

 private:
  friend class CupTest;

  explicit ClientUpdateProtocol(int key_version);

  // Decodes |public_key| into the appropriate internal structures. Returns
  // the length of the public key (modulus) in bytes, or 0 on failure.
  bool LoadPublicKey(const base::StringPiece& public_key);

  // Returns the size of the public key in bytes, or 0 on failure.
  size_t PublicKeyLength();

  // Helper function for BuildSharedKey() -- encrypts |key_source| (r) using
  // the loaded public key, filling out |encrypted_key_source_| (w).
  // Returns true on success.
  bool EncryptKeySource(const std::vector<uint8>& key_source);

  // Generates a random key source and passes it to DeriveSharedKey().
  // Returns true on success.
  bool BuildRandomSharedKey();

  // Sets a fixed key source from a character string and passes it to
  // DeriveSharedKey(). Used for unit testing only. Returns true on success.
  bool SetSharedKeyForTesting(const base::StringPiece& fixed_key_source);

  // Given a key source (r), derives the values of |shared_key_| (sk') and
  // encrypted_key_source_ (w).  Returns true on success.
  bool DeriveSharedKey(const std::vector<uint8>& 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]".)
#if defined(USE_NSS) || defined(OS_WIN) || defined(OS_MACOSX)
  SECKEYPublicKey* public_key_;
#endif

  DISALLOW_IMPLICIT_CONSTRUCTORS(ClientUpdateProtocol);
};

#endif  // GOOGLE_APIS_CUP_CLIENT_UPDATE_PROTOCOL_H_