trunks/tpm_utility.h

// Copyright 2014 The Chromium OS 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 TRUNKS_TPM_UTILITY_H_
#define TRUNKS_TPM_UTILITY_H_

#include <string>

#include <base/macros.h>
#include <chromeos/chromeos_export.h>

#include "trunks/tpm_generated.h"

namespace trunks {

// These handles will be used by TpmUtility to create storage root keys.
const TPMI_DH_PERSISTENT kRSAStorageRootKey = PERSISTENT_FIRST;
const TPMI_DH_PERSISTENT kECCStorageRootKey = PERSISTENT_FIRST + 1;

// An interface which provides convenient methods for common TPM operations.
class CHROMEOS_EXPORT TpmUtility {
 public:
  enum AsymmetricKeyUsage {
    kDecryptKey,
    kSignKey,
    kDecryptAndSignKey
  };

  TpmUtility() {}
  virtual ~TpmUtility() {}

  // Synchronously performs a TPM startup sequence and self tests. Typically
  // this is done by the platform firmware. Returns the result of the startup
  // and self-tests or, if already started, just the result of the self-tests.
  virtual TPM_RC Startup() = 0;

  // Synchronously prepares a TPM for use by Chromium OS. Typically this is done
  // by the platform firmware and, in that case, this method has no effect.
  virtual TPM_RC InitializeTpm() = 0;

  // Stir the tpm random generation module with some random entropy data.
  virtual TPM_RC StirRandom(const std::string& entropy_data) = 0;

  // This method returns |num_bytes| of random data generated by the tpm.
  virtual TPM_RC GenerateRandom(int num_bytes, std::string* random_data) = 0;

  // This method extends the pcr specified by |pcr_index| with the SHA256
  // hash of |extend_data|. The exact action performed is
  // TPM2_PCR_Extend(Sha256(extend_data));
  virtual TPM_RC ExtendPCR(int pcr_index, const std::string& extend_data) = 0;

  // This method reads the pcr specified by |pcr_index| and returns its value
  // in |pcr_value|. NOTE: it assumes we are using SHA256 as our hash alg.
  virtual TPM_RC ReadPCR(int pcr_index, std::string* pcr_value) = 0;

  // Synchronously takes ownership of the TPM with the given passwords as
  // authorization values.
  virtual TPM_RC TakeOwnership(const std::string& owner_password,
                               const std::string& endorsement_password,
                               const std::string& lockout_password) = 0;

  // Synchronously derives storage root keys for RSA and ECC and persists the
  // keys in the TPM. This operation must be authorized by the |owner_password|
  // and, on success, KRSAStorageRootKey and kECCStorageRootKey can be used
  // with an empty authorization value until the TPM is cleared.
  virtual TPM_RC CreateStorageRootKeys(const std::string& owner_password) = 0;

  // This method performs an encryption operation using a LOADED RSA key
  // referrenced by its handle |key_handle|. The |plaintext| is then encrypted
  // to give us the |ciphertext|. |scheme| refers to the encryption scheme
  // to be used. By default keys use OAEP, but can also use TPM_ALG_RSAES.
  virtual TPM_RC AsymmetricEncrypt(TPM_HANDLE key_handle,
                                   TPM_ALG_ID scheme,
                                   TPM_ALG_ID hash_alg,
                                   const std::string& plaintext,
                                   std::string* ciphertext) = 0;

  // This method performs a decyption operating using a loaded RSA key
  // referenced by its handle |key_handle|. The |ciphertext| is then decrypted
  // to give us the |plaintext|. We need |password| to authorize use of the
  // key. |scheme| refers to the decryption scheme used. By default it is
  // OAEP, but TPM_ALG_RSAES can be specified.
  virtual TPM_RC AsymmetricDecrypt(TPM_HANDLE key_handle,
                                   TPM_ALG_ID scheme,
                                   TPM_ALG_ID hash_alg,
                                   const std::string& password,
                                   const std::string& ciphertext,
                                   std::string* plaintext) = 0;

  // This method takes an unrestricted signing key referenced by |key_handle|
  // and uses it to sign the value of |digest|. The signature produced is
  // returned using the |signature| argument. We use the |password| argument
  // to authorize use of the key. |scheme| is used to specify the signature
  // scheme used. By default it is TPM_ALG_RSASSA, but TPM_ALG_RSAPPS can
  // be specified. hash_alg is the algorithm used in the signing operation.
  // It is by default TPM_ALG_SHA256.
  virtual TPM_RC Sign(TPM_HANDLE key_handle,
                      TPM_ALG_ID scheme,
                      TPM_ALG_ID hash_alg,
                      const std::string& password,
                      const std::string& digest,
                      std::string* signature) = 0;

  // This method verifies that the signature produced on the digest was
  // performed by |key_handle|. |scheme| and |hash| refer to the signature
  // scheme used to sign |digest| and produce the signature. This value is by
  // default TPM_ALG_RSASSA with TPM_ALG_SHA256 but can take the value of
  // TPM_ALG_RSAPPS with other hash algorithms supported by the tpm.
  // Returns TPM_RC_SUCCESS when the signature is correct.
  virtual TPM_RC Verify(TPM_HANDLE key_handle,
                        TPM_ALG_ID scheme,
                        TPM_ALG_ID hash_alg,
                        const std::string& digest,
                        const std::string& signature) = 0;

  // This method creates an RSA key. It creates a 2048 bit RSA key with
  // public exponent of 0x10001. |key_type| determines whether the key is
  // a signing key, a decryption key, or both. The |password| parameter
  // is used as the authorization for the created key. The created key
  // is then loaded and its handle is returned as |key_handle|.
  virtual TPM_RC CreateRSAKey(AsymmetricKeyUsage key_type,
                              const std::string& password,
                              TPM_HANDLE* key_handle) = 0;

 private:
  DISALLOW_COPY_AND_ASSIGN(TpmUtility);
};

}  // namespace trunks

#endif  // TRUNKS_TPM_UTILITY_H_