unexportable_key.h 4.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111
  1. // Copyright (c) 2021 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. #ifndef CRYPTO_UNEXPORTABLE_KEY_H_
  5. #define CRYPTO_UNEXPORTABLE_KEY_H_
  6. #include <memory>
  7. #include "crypto/crypto_export.h"
  8. #include "crypto/signature_verifier.h"
  9. #include "third_party/abseil-cpp/absl/types/optional.h"
  10. namespace crypto {
  11. // UnexportableSigningKey provides a hardware-backed signing oracle on platforms
  12. // that support it. Current support is:
  13. // Windows: RSA_PKCS1_SHA256 via TPM 1.2+ and ECDSA_SHA256 via TPM 2.0.
  14. // Tests: ECDSA_SHA256 via ScopedMockUnexportableSigningKeyForTesting.
  15. class CRYPTO_EXPORT UnexportableSigningKey {
  16. public:
  17. virtual ~UnexportableSigningKey();
  18. // Algorithm returns the algorithm of the key in this object.
  19. virtual SignatureVerifier::SignatureAlgorithm Algorithm() const = 0;
  20. // GetSubjectPublicKeyInfo returns an SPKI that contains the public key of
  21. // this object.
  22. virtual std::vector<uint8_t> GetSubjectPublicKeyInfo() const = 0;
  23. // GetWrappedKey returns the encrypted private key of this object. It is
  24. // encrypted to a key that is kept in hardware and the unencrypted private
  25. // key never exists in the CPU's memory.
  26. //
  27. // A wrapped key may be used with a future instance of this code to recreate
  28. // the key so long as it's running on the same computer.
  29. //
  30. // Note: it is possible to export this wrapped key off machine, but it must be
  31. // sealed with an AEAD first. The wrapped key may contain machine identifiers
  32. // and other values that you wouldn't want to export. Additionally
  33. // |UnexportableKeyProvider::FromWrappedSigningKey| should not be presented
  34. // attacked-controlled input and the AEAD would serve to authenticate the
  35. // wrapped key.
  36. virtual std::vector<uint8_t> GetWrappedKey() const = 0;
  37. // SignSlowly returns a signature of |data|, or |nullopt| if an error occurs
  38. // during signing.
  39. //
  40. // Note: this may take a second or more to run.
  41. virtual absl::optional<std::vector<uint8_t>> SignSlowly(
  42. base::span<const uint8_t> data) = 0;
  43. };
  44. // UnexportableKeyProvider creates |UnexportableSigningKey|s.
  45. class CRYPTO_EXPORT UnexportableKeyProvider {
  46. public:
  47. virtual ~UnexportableKeyProvider();
  48. // SelectAlgorithm returns which signature algorithm from
  49. // |acceptable_algorithms| would be used if |acceptable_algorithms| was passed
  50. // to |GenerateSigningKeySlowly|.
  51. virtual absl::optional<SignatureVerifier::SignatureAlgorithm> SelectAlgorithm(
  52. base::span<const SignatureVerifier::SignatureAlgorithm>
  53. acceptable_algorithms) = 0;
  54. // GenerateSigningKeySlowly creates a new opaque signing key in hardware. The
  55. // first supported value of |acceptable_algorithms| determines the type of the
  56. // key. Returns nullptr if no supported hardware exists, if no value in
  57. // |acceptable_algorithms| is supported, or if there was an error creating the
  58. // key.
  59. //
  60. // Note: this may take one or two seconds to run.
  61. virtual std::unique_ptr<UnexportableSigningKey> GenerateSigningKeySlowly(
  62. base::span<const SignatureVerifier::SignatureAlgorithm>
  63. acceptable_algorithms) = 0;
  64. // FromWrappedSigningKey creates an |UnexportableSigningKey| from
  65. // |wrapped_key|, which must have resulted from calling |GetWrappedKey| on a
  66. // previous instance of |UnexportableSigningKey|. Returns nullptr if
  67. // |wrapped_key| cannot be imported.
  68. //
  69. // Note: this may take up to a second.
  70. //
  71. // Note: do not call this with attacker-controlled data. The underlying
  72. // interfaces to the secure hardware may not be robust. See |GetWrappedKey|.
  73. virtual std::unique_ptr<UnexportableSigningKey> FromWrappedSigningKeySlowly(
  74. base::span<const uint8_t> wrapped_key) = 0;
  75. };
  76. // GetUnexportableKeyProvider returns an |UnexportableKeyProvider|
  77. // for the current platform, or nullptr if there isn't one. This can be called
  78. // from any thread but, in tests, but be sequenced with
  79. // |SetUnexportableSigningKeyProvider|.
  80. CRYPTO_EXPORT std::unique_ptr<UnexportableKeyProvider>
  81. GetUnexportableKeyProvider();
  82. #if BUILDFLAG(IS_WIN)
  83. // MeasureTPMAvailability records UMA metrics of TPM availability.
  84. CRYPTO_EXPORT void MeasureTPMAvailabilityWin();
  85. #endif // BUILDFLAG(IS_WIN)
  86. namespace internal {
  87. CRYPTO_EXPORT void SetUnexportableKeyProviderForTesting(
  88. std::unique_ptr<UnexportableKeyProvider> (*func)());
  89. } // namespace internal
  90. } // namespace crypto
  91. #endif // CRYPTO_UNEXPORTABLE_KEY_H_