Botan 3.7.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/exceptn.h>
13#include <botan/rng.h>
14
15#include <memory>
16#include <optional>
17#include <vector>
18
19/// Forward declaration of TSS2 type for convenience
20using TPM2_HANDLE = uint32_t;
21
22/// Forward declaration of TSS2 type for convenience
23using ESYS_TR = uint32_t;
24
25struct ESYS_CONTEXT;
26
27namespace Botan::TPM2 {
28
29struct CryptoCallbackState;
30
31class PrivateKey;
32class SessionBundle;
33
34/**
35 * Central class for interacting with a TPM2. Additional to managing the
36 * connection to the TPM, this provides authorative information about the TPM's
37 * capabilities. Also, it allows to persist and evict keys generated by the TPM.
38 */
39class BOTAN_PUBLIC_API(3, 6) Context final : public std::enable_shared_from_this<Context> {
40 public:
41 /**
42 * @param tcti_nameconf this is passed to Tss2_TctiLdr_Initialize verbatim
43 */
44 static std::shared_ptr<Context> create(const std::string& tcti_nameconf);
45
46 /**
47 * @param tcti if set this is passed to Tss2_TctiLdr_Initialize_Ex verbatim
48 * otherwise a nullptr is passed.
49 * @param conf if set this is passed to Tss2_TctiLdr_Initialize_Ex verbatim
50 * otherwise a nullptr is passed.
51 */
52 static std::shared_ptr<Context> create(std::optional<std::string> tcti = {},
53 std::optional<std::string> conf = {});
54
55 /**
56 * Create a TPM2::Context from an externally sourced TPM2-TSS ESYS
57 * Context. Note that the input contexts need to remain alive for the
58 * lifetime of the entire TPM2::Context! This allows to use Botan's TPM2
59 * functionality within an exising ESAPI application.
60 *
61 * Note that Botan won't finalize an externally provided ESYS context,
62 * this responsibility remains with the caller in this case.
63 *
64 * @param ctx the already set up ESYS_CONTEXT*
65 */
66 static std::shared_ptr<Context> create(ESYS_CONTEXT* ctx);
67
68 Context(const Context&) = delete;
69 Context(Context&&) noexcept;
70 ~Context();
71
72 Context& operator=(const Context&) = delete;
73 Context& operator=(Context&&) noexcept;
74
75 /**
76 * Overrides the TSS2's crypto callbacks with Botan's functionality.
77 *
78 * This replaces all cryptographic functionality required for the
79 * communication with the TPM by botan's implementations. The TSS2
80 * would otherwise use OpenSSL or mbedTLS.
81 *
82 * Note that the provided @p rng should not be dependent on the TPM.
83 *
84 * @param rng the RNG to use for the crypto operations
85 * @throws Not_Implemented if the TPM2-TSS does not support crypto callbacks
86 * @sa supports_botan_crypto_backend()
87 */
88 void use_botan_crypto_backend(const std::shared_ptr<Botan::RandomNumberGenerator>& rng);
89
90 /**
91 * Checks if the TSS2 supports registering Botan's crypto backend at runtime.
92 * Older versions of the TSS2 do not support this feature ( 4.0.0), also
93 * Botan may be compiled without support for TSS' crypto backend.
94 * @return true if the TSS2 supports Botan's crypto backend
95 */
96 static bool supports_botan_crypto_backend() noexcept;
97
98 /// @returns true if botan is used for the TSS' crypto functions
99 bool uses_botan_crypto_backend() const noexcept;
100
101 /// @return an ESYS_CONTEXT* for use in other TPM2 functions.
102 ESYS_CONTEXT* esys_context() noexcept;
103
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:19
Context(const Context &)=delete
Context(Context &&) noexcept
int(* final)(unsigned char *, CTX *)
uint32_t ESYS_TR
Forward declaration of TSS2 type for convenience.
uint32_t TPM2_HANDLE
Forward declaration of TSS2 type for convenience.