// Copyright (c) 2012 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 CHAPS_TPM_UTILITY_H_
#define CHAPS_TPM_UTILITY_H_

#include <string>

#include <brillo/secure_blob.h>

#include "chaps/chaps_utility.h"

namespace chaps {

enum class TPMVersion {
  TPM1_2,
  TPM2_0,
  TPM_VERSION_COUNT,
};

// TPMUtility is a high-level interface to TPM services. In practice, only a
// single instance of this class is necessary to provide TPM services across
// multiple logical tokens and sessions.
class TPMUtility {
 public:
  virtual ~TPMUtility() {}

  // Returns the minimum supported RSA key size (in bits).
  virtual size_t MinRSAKeyBits() = 0;

  // Returns the maximum supported RSA key size (in bits).
  virtual size_t MaxRSAKeyBits() = 0;

  // Performs initialization tasks including the loading of the storage root key
  // (SRK). This may be called multiple times.
  // Returns true on success.
  virtual bool Init() = 0;

  // Returns true if a TPM exists and is enabled.
  virtual bool IsTPMAvailable() = 0;

  // Return the TPM version, as in TPMVersion::TPM1_2 or TPMVersion::TPM2_0.
  virtual TPMVersion GetTPMVersion() = 0;

  // Authenticates a user by decrypting the user's root key with the user's
  // authorization key.
  //   auth_data - The user's authorization data (which is derived from the
  //               the user's password).
  //   auth_key_blob - The authorization key blob as provided by the TPM when
  //                   the key was generated.
  //   encrypted_root_key - The root key encrypted with the authorization
  //                          key.
  //   root_key - Will be populated with the decrypted root key.
  // Returns true on success.
  virtual bool Authenticate(const brillo::SecureBlob& auth_data,
                            const std::string& auth_key_blob,
                            const std::string& encrypted_root_key,
                            brillo::SecureBlob* root_key) = 0;

  // Changes authorization data for a user's authorization key. Returns true on
  // success.
  virtual bool ChangeAuthData(const brillo::SecureBlob& old_auth_data,
                              const brillo::SecureBlob& new_auth_data,
                              const std::string& old_auth_key_blob,
                              std::string* new_auth_key_blob) = 0;

  // Provides hardware-generated random data. Returns true on success.
  virtual bool GenerateRandom(int num_bytes, std::string* random_data) = 0;

  // Adds entropy to the hardware random number generator. This is like seeding
  // the generator except the provided entropy is mixed with existing state and
  // the resulting random numbers generated are not deterministic. Returns true
  // on success.
  virtual bool StirRandom(const std::string& entropy_data) = 0;

  // Generates an RSA key pair in the TPM and wraps it with the SRK. The key
  // type will be set to TSS_KEY_TYPE_LEGACY.
  //   slot - The slot associated with this key.
  //   modulus_bits - The size of the key to be generated (usually 2048).
  //   public_exponent - The RSA public exponent (usually {1, 0, 1} which is
  //                     65537).
  //   auth_data - Authorization data which will be associated with the new key.
  //   key_blob - Will be populated with the wrapped key blob as provided by the
  //              TPM. This should be saved so the key can be loaded again
  //              in the future.
  //   key_handle - A handle to the new key. This will be valid until keys are
  //                unloaded for the given slot.
  // Returns true on success.
  virtual bool GenerateRSAKey(int slot,
                              int modulus_bits,
                              const std::string& public_exponent,
                              const brillo::SecureBlob& auth_data,
                              std::string* key_blob,
                              int* key_handle) = 0;

  // Retrieves the public components of an RSA key pair. Returns true on
  // success.
  virtual bool GetRSAPublicKey(int key_handle,
                               std::string* public_exponent,
                               std::string* modulus) = 0;

  // Return supports |curve_nid| or not. |curve_nid| is the NID of OpenSSL.
  // TPM 1.2 doesn't support ECC.
  // TPM 2.0 current only support P-256 curve (NID_X9_62_prime256v1).
  virtual bool IsECCurveSupported(int curve_nid) = 0;

  // Generates an ECC key pair in the TPM and wraps it with the SRK.
  //   slot - The slot associated with this key.
  //   nid - the OpenSSL NID for the curve.
  //   auth_data - Authorization data which will be associated with the new key.
  //   key_blob - Will be populated with the wrapped key blob as provided by the
  //              TPM. This should be saved so the key can be loaded again
  //              in the future.
  //   key_handle - A handle to the new key. This will be valid until keys are
  //                unloaded for the given slot.
  // Returns true on success.
  virtual bool GenerateECCKey(int slot,
                              int nid,
                              const brillo::SecureBlob& auth_data,
                              std::string* key_blob,
                              int* key_handle) = 0;

  // Retrieves the public point of ECC key pair. Returns true on success.
  //   key_handle - A TPM key handle
  //   public_point - A DER-encoded string of EC_Point.
  virtual bool GetECCPublicKey(int key_handle, std::string* public_point) = 0;

  // Wraps an RSA key pair with the SRK. The key type will be set to
  // TSS_KEY_TYPE_LEGACY.
  //   slot - The slot associated with this key.
  //   public_exponent - The RSA public exponent (e).
  //   modulus - The RSA modulus (n).
  //   prime_factor - One of the prime factors of the modulus (p or q).
  //   auth_data - Authorization data which will be associated with the new key.
  //   key_blob - Will be populated with the wrapped key blob as provided by the
  //              TPM. This should be saved so the key can be loaded again
  //              in the future.
  //   key_handle - A handle to the new key. This will be valid until keys are
  //                unloaded for the given slot.
  // Returns true on success.
  virtual bool WrapRSAKey(int slot,
                          const std::string& public_exponent,
                          const std::string& modulus,
                          const std::string& prime_factor,
                          const brillo::SecureBlob& auth_data,
                          std::string* key_blob,
                          int* key_handle) = 0;

  // Wraps an RSA key pair with the SRK.
  //   slot - The slot associated with this key.
  //   curve_nid - The OpenSSL NID of the ECC curve.
  //   public_point_x - The x coordinate of ECC public key point on the curve.
  //   public_point_y - The y coordinate of ECC public key point on the curve.
  //   private_value - The ECC private key value.
  //   auth_data - Authorization data which will be associated with the new key.
  //   key_blob - Will be populated with the wrapped key blob as provided by the
  //              TPM. This should be saved so the key can be loaded again
  //              in the future.
  //   key_handle - A handle to the new key. This will be valid until keys are
  //                unloaded for the given slot.
  // Returns true on success.
  virtual bool WrapECCKey(int slot,
                          int curve_nid,
                          const std::string& public_point_x,
                          const std::string& public_point_y,
                          const std::string& private_value,
                          const brillo::SecureBlob& auth_data,
                          std::string* key_blob,
                          int* key_handle) = 0;

  // Loads a key by blob into the TPM.
  //   slot - The slot associated with this key.
  //   key_blob - The key blob as provided by GenerateKey or WrapRSAKey.
  //   auth_data - Authorization data for the key.
  //   key_handle - A handle to the loaded key. This will be valid until keys
  //                are unloaded for the given slot.
  // Returns true on success.
  virtual bool LoadKey(int slot,
                       const std::string& key_blob,
                       const brillo::SecureBlob& auth_data,
                       int* key_handle) = 0;

  // Loads a key by blob into the TPM that has a parent key that is not the SRK.
  //   slot - The slot associated with this key.
  //   key_blob - The key blob as provided by GenerateKey or WrapRSAKey.
  //   auth_data - Authorization data for the key.
  //   parent_key_handle - The key handle of the parent key.
  //   key_handle - A handle to the loaded key. This will be valid until keys
  //                are unloaded for the given slot.
  // Returns true on success.
  virtual bool LoadKeyWithParent(int slot,
                                 const std::string& key_blob,
                                 const brillo::SecureBlob& auth_data,
                                 int parent_key_handle,
                                 int* key_handle) = 0;

  // Unloads all keys loaded for a particular slot. All key handles for the
  // given slot will not be valid after this method returns.
  virtual void UnloadKeysForSlot(int slot) = 0;

  // Performs a 'bind' operation using the TSS_ES_RSAESPKCSV15 scheme. This
  // effectively performs PKCS #1 v1.5 RSA encryption (using PKCS #1 'type 2'
  // padding).
  //   key_handle - The key handle, as provided by LoadKey, WrapRSAKey, or
  //                GenerateKey.
  //   input - Data to be encrypted. The length of this data must not exceed
  //           'N - 11' where N is the length in bytes of the RSA key modulus.
  //   output - The encrypted data. The length will always match the length of
  //            the RSA key modulus.
  // Returns true on success.
  virtual bool Bind(int key_handle,
                    const std::string& input,
                    std::string* output) = 0;

  // Performs a 'unbind' operation using the TSS_ES_RSAESPKCSV15 scheme. This
  // effectively performs PKCS #1 v1.5 RSA decryption (using PKCS #1 'type 2'
  // padding).
  //   key_handle - The key handle, as provided by LoadKey, WrapRSAKey or
  //                GenerateKey.
  //   input - Data to be encrypted. The length of this data must not exceed
  //           'N - 11' where N is the length in bytes of the RSA key modulus.
  //   output - The encrypted data. The length will always match the length of
  //            the RSA key modulus.
  // Returns true on success.
  virtual bool Unbind(int key_handle,
                      const std::string& input,
                      std::string* output) = 0;

  // Generates a digital signature.
  //   key_handle - The key handle, as provided by LoadKey, WrapRSAKey or
  //                GenerateKey.
  //   signing_mechanism - The mechanism (i.e. asymmetric cipher type and
  //                       padding scheme, if applicable) that is used for
  //                       signing.
  //   mechanism_parameter - The parameter to the signing mechanism, if any is
  //                         required, such as in RSA PSS.
  //   input - The raw data we want to sign. For RSASSA, the DER encoding of the
  //           DigestInfo value (see PKCS #1 v.2.1: 9.2) will be added
  //           internally according to |digest_algorithm|.
  //           For padding only scheme (ex. CKM_RSA_PKCS), the DigestInfo should
  //           be added by PKCS#11 API caller.
  //   signature - Receives the generated signature. The signature length will
  //               always match the length of the RSA key modulus.
  // Returns true on success.
  virtual bool Sign(int key_handle,
                    CK_MECHANISM_TYPE signing_mechanism,
                    const std::string& mechanism_parameter,
                    const std::string& input,
                    std::string* signature) = 0;

  // Returns true iff the Storage Root Key is initialized and ready.  The SRK is
  // expected to not be ready until ownership of the TPM has been taken.
  virtual bool IsSRKReady() = 0;

  // Seals the data to TPM and wraps it with the SRK.
  //   unsealed_data - The data that needs to be sealed.
  //   auth_data - Authorization data which will be associated with the sealed
  //   data. key_blob - Will be populated with the wrapped key blob as provided
  //   by the
  //              TPM. This should be saved so the key can be loaded again
  //              in the future.
  //   encrypted_data - The data that is needed to retrieve the unsealed data.
  // Returns true on success.
  virtual bool SealData(const std::string& unsealed_data,
                        const brillo::SecureBlob& auth_value,
                        std::string* key_blob,
                        std::string* encrypted_data) = 0;

  // Unseals the data from TPM.
  //   key_blob - The key blob as provided by SealData.
  //   encrypted_data - The data that is needed to retrieve the unsealed data.
  //   auth_data - Authorization data that associated with the sealed data.
  //   unsealed_data - The unsealed data.
  // Returns true on success.
  virtual bool UnsealData(const std::string& key_blob,
                          const std::string& encrypted_data,
                          const brillo::SecureBlob& auth_value,
                          brillo::SecureBlob* unsealed_data) = 0;
};

}  // namespace chaps

#endif  // CHAPS_TPM_UTILITY_H_