Botan 3.14.1
Crypto and TLS for C&
tpm2_context.h
Go to the documentation of this file.
1/*
2* TPM 2 interface
3* (C) 2024 Jack Lloyd
4* (C) 2024 René Meusel, Amos Treiber - Rohde & Schwarz Cybersecurity GmbH, financed by LANCOM Systems GmbH
5*
6* Botan is released under the Simplified BSD License (see license.txt)
7*/
8
9#ifndef BOTAN_TPM2_CONTEXT_H_
10#define BOTAN_TPM2_CONTEXT_H_
11
12#include <botan/rng.h>
13
14#include <memory>
15#include <optional>
16#include <vector>
17
18/// Forward declaration of TSS2 type for convenience
19using TPM2_HANDLE = uint32_t;
20
21/// Forward declaration of TSS2 type for convenience
22using ESYS_TR = uint32_t;
23
24struct ESYS_CONTEXT;
25
26namespace Botan::TPM2 {
27
28struct CryptoCallbackState;
29
30class PrivateKey;
31class SessionBundle;
32
33/**
34 * Central class for interacting with a TPM2. Additional to managing the
35 * connection to the TPM, this provides authoritative information about the TPM's
36 * capabilities. Also, it allows to persist and evict keys generated by the TPM.
37 */
38class BOTAN_PUBLIC_API(3, 6) Context final : public std::enable_shared_from_this<Context> {
39 public:
40 /**
41 * @param tcti_nameconf this is passed to Tss2_TctiLdr_Initialize verbatim
42 */
43 static std::shared_ptr<Context> create(const std::string& tcti_nameconf);
44
45 /**
46 * @param tcti if set this is passed to Tss2_TctiLdr_Initialize_Ex verbatim
47 * otherwise a nullptr is passed.
48 * @param conf if set this is passed to Tss2_TctiLdr_Initialize_Ex verbatim
49 * otherwise a nullptr is passed.
50 */
51 static std::shared_ptr<Context> create(std::optional<std::string> tcti = {},
52 std::optional<std::string> conf = {});
53
54 /**
55 * Create a TPM2::Context from an externally sourced TPM2-TSS ESYS
56 * Context. Note that the input contexts need to remain alive for the
57 * lifetime of the entire TPM2::Context! This allows to use Botan's TPM2
58 * functionality within an existing ESAPI application.
59 *
60 * Note that Botan won't finalize an externally provided ESYS context,
61 * this responsibility remains with the caller in this case.
62 *
63 * @param ctx the already set up ESYS_CONTEXT*
64 */
65 static std::shared_ptr<Context> create(ESYS_CONTEXT* ctx);
66
67 Context(const Context&) = delete;
68 Context(Context&&) noexcept;
69 ~Context();
70
71 Context& operator=(const Context&) = delete;
72 Context& operator=(Context&&) noexcept;
73
74 /**
75 * Overrides the TSS2's crypto callbacks with Botan's functionality.
76 *
77 * This replaces all cryptographic functionality required for the
78 * communication with the TPM by botan's implementations. The TSS2
79 * would otherwise use OpenSSL or mbedTLS.
80 *
81 * Note that the provided @p rng should not be dependent on the TPM.
82 *
83 * @param rng the RNG to use for the crypto operations
84 * @throws Not_Implemented if the TPM2-TSS does not support crypto callbacks
85 * @sa supports_botan_crypto_backend()
86 */
87 void use_botan_crypto_backend(const std::shared_ptr<Botan::RandomNumberGenerator>& rng);
88
89 /**
90 * Checks if the TSS2 supports registering Botan's crypto backend at runtime.
91 * Older versions of the TSS2 do not support this feature ( 4.0.0), also
92 * Botan may be compiled without support for TSS' crypto backend.
93 * @return true if the TSS2 supports Botan's crypto backend
94 */
95 static bool supports_botan_crypto_backend() noexcept;
96
97 /// @returns true if botan is used for the TSS' crypto functions
98 bool uses_botan_crypto_backend() const noexcept;
99
100 /// @return an ESYS_CONTEXT* for use in other TPM2 functions.
101 ESYS_CONTEXT* esys_context() noexcept;
102
103 // NOLINTNEXTLINE(*-explicit-conversions,*-explicit-constructor) Intentional: enables transparent ESYS_CONTEXT* wrapper usage
104 operator ESYS_CONTEXT*() noexcept { return esys_context(); }
105
106 /// @return the Vendor of the TPM2
107 std::string vendor() const;
108
109 /// @returns the Manufacturer of the TPM2
110 std::string manufacturer() const;
111
112 /**
113 * The @p algo_name can be any of the string algorithm specifiers used
114 * elsewhere. For example, "RSA", "AES-128", "SHA-1", "CTR(3DES)", etc.
115 *
116 * @returns true if the specified algorithm is supported by the TPM
117 */
118 bool supports_algorithm(std::string_view algo_name) const;
119
120 /// @returns the maximum number of random bytes to be requested at once
121 size_t max_random_bytes_per_request() const;
122
123 std::vector<ESYS_TR> transient_handles() const;
124
125 /// @returns a persistent handle that is currently not in use
126 /// or std::nullopt if no such handle is available
127 std::optional<TPM2_HANDLE> find_free_persistent_handle() const;
128
129 std::vector<TPM2_HANDLE> persistent_handles() const;
130
131 /// Makes @p key persistent at location @p persistent_handle or any free
132 TPM2_HANDLE persist(TPM2::PrivateKey& key,
133 const SessionBundle& sessions,
134 std::span<const uint8_t> auth_value = {},
135 std::optional<TPM2_HANDLE> persistent_handle = std::nullopt);
136
137 /// Evicts a persistent @p key from the TPM. The key cannot be used after.
138 void evict(std::unique_ptr<TPM2::PrivateKey> key, const SessionBundle& sessions);
139
140 // TODO: Currently this assumes that the SRK is a persistent object,
141 // this assumption may not hold forever.
142 std::unique_ptr<TPM2::PrivateKey> storage_root_key(std::span<const uint8_t> auth_value,
143 const SessionBundle& sessions);
144
145 private:
146 Context(ESYS_CONTEXT* ctx, bool external);
147
148#if defined(BOTAN_HAS_TPM2_CRYPTO_BACKEND)
149 friend void enable_crypto_callbacks(const std::shared_ptr<Context>&);
150 CryptoCallbackState& crypto_callback_state();
151#endif
152
153 private:
154 struct Impl; // PImpl to avoid TPM2-TSS includes in this header
155 std::unique_ptr<Impl> m_impl;
156};
157
158} // namespace Botan::TPM2
159
160#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:21
void use_botan_crypto_backend(const std::shared_ptr< Botan::RandomNumberGenerator > &rng)
static bool supports_botan_crypto_backend() noexcept
Context(const Context &)=delete
static std::shared_ptr< Context > create(const std::string &tcti_nameconf)
Context(Context &&) noexcept
ESYS_CONTEXT * esys_context() noexcept
bool uses_botan_crypto_backend() const noexcept
uint32_t ESYS_TR
Forward declaration of TSS2 type for convenience.
uint32_t TPM2_HANDLE
Forward declaration of TSS2 type for convenience.