1 // Copyright (c) 2009-2010 Satoshi Nakamoto
2 // Copyright (c) 2009-present The Bitcoin Core developers
3 // Copyright (c) 2017 The Zcash developers
4 // Distributed under the MIT software license, see the accompanying
5 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
6 7 #ifndef BITCOIN_KEY_H
8 #define BITCOIN_KEY_H
9 10 #include <pubkey.h>
11 #include <serialize.h>
12 #include <support/allocators/secure.h>
13 #include <uint256.h>
14 15 #include <stdexcept>
16 #include <vector>
17 18 struct secp256k1_context_struct;
19 typedef struct secp256k1_context_struct secp256k1_context;
20 21 /**
22 * CPrivKey is a serialized private key, with all parameters included
23 * (SIZE bytes)
24 */
25 typedef std::vector<unsigned char, secure_allocator<unsigned char> > CPrivKey;
26 27 /** Size of ECDH shared secrets. */
28 constexpr static size_t ECDH_SECRET_SIZE = CSHA256::OUTPUT_SIZE;
29 30 // Used to represent ECDH shared secret (ECDH_SECRET_SIZE bytes)
31 using ECDHSecret = std::array<std::byte, ECDH_SECRET_SIZE>;
32 33 class KeyPair;
34 35 /** An encapsulated private key. */
36 class CKey
37 {
38 public:
39 /**
40 * secp256k1:
41 */
42 static const unsigned int SIZE = 279;
43 static const unsigned int COMPRESSED_SIZE = 214;
44 /**
45 * see www.keylength.com
46 * script supports up to 75 for single byte push
47 */
48 static_assert(
49 SIZE >= COMPRESSED_SIZE,
50 "COMPRESSED_SIZE is larger than SIZE");
51 52 private:
53 /** Internal data container for private key material. */
54 using KeyType = std::array<unsigned char, 32>;
55 56 //! Whether the public key corresponding to this private key is (to be) compressed.
57 bool fCompressed{false};
58 59 //! The actual byte data. nullptr for invalid keys.
60 secure_unique_ptr<KeyType> keydata;
61 62 //! Check whether the 32-byte array pointed to by vch is valid keydata.
63 bool static Check(const unsigned char* vch);
64 65 void MakeKeyData()
66 {
67 if (!keydata) keydata = make_secure_unique<KeyType>();
68 }
69 70 void ClearKeyData()
71 {
72 keydata.reset();
73 }
74 75 public:
76 CKey() noexcept = default;
77 CKey(CKey&&) noexcept = default;
78 CKey& operator=(CKey&&) noexcept = default;
79 80 CKey& operator=(const CKey& other)
81 {
82 if (this != &other) {
83 if (other.keydata) {
84 MakeKeyData();
85 *keydata = *other.keydata;
86 } else {
87 ClearKeyData();
88 }
89 fCompressed = other.fCompressed;
90 }
91 return *this;
92 }
93 94 CKey(const CKey& other) { *this = other; }
95 96 friend bool operator==(const CKey& a, const CKey& b)
97 {
98 return a.fCompressed == b.fCompressed &&
99 a.size() == b.size() &&
100 memcmp(a.data(), b.data(), a.size()) == 0;
101 }
102 103 //! Initialize using begin and end iterators to byte data.
104 template <typename T>
105 void Set(const T pbegin, const T pend, bool fCompressedIn)
106 {
107 if (size_t(pend - pbegin) != std::tuple_size_v<KeyType>) {
108 ClearKeyData();
109 } else if (Check(UCharCast(&pbegin[0]))) {
110 MakeKeyData();
111 memcpy(keydata->data(), (unsigned char*)&pbegin[0], keydata->size());
112 fCompressed = fCompressedIn;
113 } else {
114 ClearKeyData();
115 }
116 }
117 118 //! Simple read-only vector-like interface.
119 unsigned int size() const { return keydata ? keydata->size() : 0; }
120 const std::byte* data() const { return keydata ? reinterpret_cast<const std::byte*>(keydata->data()) : nullptr; }
121 const std::byte* begin() const { return data(); }
122 const std::byte* end() const { return data() + size(); }
123 124 //! Check whether this private key is valid.
125 bool IsValid() const { return !!keydata; }
126 127 //! Check whether the public key corresponding to this private key is (to be) compressed.
128 bool IsCompressed() const { return fCompressed; }
129 130 //! Generate a new private key using a cryptographic PRNG.
131 void MakeNewKey(bool fCompressed);
132 133 /**
134 * Convert the private key to a CPrivKey (serialized OpenSSL private key data).
135 * This is expensive.
136 */
137 CPrivKey GetPrivKey() const;
138 139 /**
140 * Compute the public key from a private key.
141 * This is expensive.
142 */
143 CPubKey GetPubKey() const;
144 145 /**
146 * Create a DER-serialized signature.
147 * The test_case parameter tweaks the deterministic nonce.
148 */
149 bool Sign(const uint256& hash, std::vector<unsigned char>& vchSig, bool grind = true, uint32_t test_case = 0) const;
150 151 /**
152 * Create a compact signature (65 bytes), which allows reconstructing the used public key.
153 * The format is one header byte, followed by two times 32 bytes for the serialized r and s values.
154 * The header byte: 0x1B = first key with even y, 0x1C = first key with odd y,
155 * 0x1D = second key with even y, 0x1E = second key with odd y,
156 * add 0x04 for compressed keys.
157 */
158 bool SignCompact(const uint256& hash, std::vector<unsigned char>& vchSig) const;
159 160 /**
161 * Create a BIP-340 Schnorr signature, for the xonly-pubkey corresponding to *this,
162 * optionally tweaked by *merkle_root. Additional nonce entropy is provided through
163 * aux.
164 *
165 * merkle_root is used to optionally perform tweaking of the private key, as specified
166 * in BIP341:
167 * - If merkle_root == nullptr: no tweaking is done, sign with key directly (this is
168 * used for signatures in BIP342 script).
169 * - If merkle_root->IsNull(): sign with key + H_TapTweak(pubkey) (this is used for
170 * key path spending when no scripts are present).
171 * - Otherwise: sign with key + H_TapTweak(pubkey || *merkle_root)
172 * (this is used for key path spending, with specific
173 * Merkle root of the script tree).
174 */
175 bool SignSchnorr(const uint256& hash, std::span<unsigned char> sig, const uint256* merkle_root, const uint256& aux) const;
176 177 //! Derive BIP32 child key.
178 [[nodiscard]] bool Derive(CKey& keyChild, ChainCode &ccChild, unsigned int nChild, const ChainCode& cc) const;
179 180 /**
181 * Verify thoroughly whether a private key and a public key match.
182 * This is done using a different mechanism than just regenerating it.
183 */
184 bool VerifyPubKey(const CPubKey& vchPubKey) const;
185 186 //! Load private key and check that public key matches.
187 bool Load(const CPrivKey& privkey, const CPubKey& vchPubKey, bool fSkipCheck);
188 189 /** Create an ellswift-encoded public key for this key, with specified entropy.
190 *
191 * entropy must be a 32-byte span with additional entropy to use in the encoding. Every
192 * public key has ~2^256 different encodings, and this function will deterministically pick
193 * one of them, based on entropy. Note that even without truly random entropy, the
194 * resulting encoding will be indistinguishable from uniform to any adversary who does not
195 * know the private key (because the private key itself is always used as entropy as well).
196 */
197 EllSwiftPubKey EllSwiftCreate(std::span<const std::byte> entropy) const;
198 199 /** Compute a BIP324-style ECDH shared secret.
200 *
201 * - their_ellswift: EllSwiftPubKey that was received from the other side.
202 * - our_ellswift: EllSwiftPubKey that was sent to the other side (must have been generated
203 * from *this using EllSwiftCreate()).
204 * - initiating: whether we are the initiating party (true) or responding party (false).
205 */
206 ECDHSecret ComputeBIP324ECDHSecret(const EllSwiftPubKey& their_ellswift,
207 const EllSwiftPubKey& our_ellswift,
208 bool initiating) const;
209 /** Compute a KeyPair
210 *
211 * Wraps a `secp256k1_keypair` type.
212 *
213 * `merkle_root` is used to optionally perform tweaking of
214 * the internal key, as specified in BIP341:
215 *
216 * - If merkle_root == nullptr: no tweaking is done, use the internal key directly (this is
217 * used for signatures in BIP342 script).
218 * - If merkle_root->IsNull(): tweak the internal key with H_TapTweak(pubkey) (this is used for
219 * key path spending when no scripts are present).
220 * - Otherwise: tweak the internal key with H_TapTweak(pubkey || *merkle_root)
221 * (this is used for key path spending with the
222 * Merkle root of the script tree).
223 */
224 KeyPair ComputeKeyPair(const uint256* merkle_root) const;
225 };
226 227 CKey GenerateRandomKey(bool compressed = true) noexcept;
228 229 struct CExtKey {
230 unsigned char nDepth;
231 unsigned char vchFingerprint[4];
232 unsigned int nChild;
233 ChainCode chaincode;
234 CKey key;
235 236 friend bool operator==(const CExtKey& a, const CExtKey& b)
237 {
238 return a.nDepth == b.nDepth &&
239 memcmp(a.vchFingerprint, b.vchFingerprint, sizeof(vchFingerprint)) == 0 &&
240 a.nChild == b.nChild &&
241 a.chaincode == b.chaincode &&
242 a.key == b.key;
243 }
244 245 CExtKey() = default;
246 CExtKey(const CExtPubKey& xpub, const CKey& key_in) : nDepth(xpub.nDepth), nChild(xpub.nChild), chaincode(xpub.chaincode), key(key_in)
247 {
248 std::copy(xpub.vchFingerprint, xpub.vchFingerprint + sizeof(xpub.vchFingerprint), vchFingerprint);
249 }
250 251 void Encode(unsigned char code[BIP32_EXTKEY_SIZE]) const;
252 void Decode(const unsigned char code[BIP32_EXTKEY_SIZE]);
253 [[nodiscard]] bool Derive(CExtKey& out, unsigned int nChild) const;
254 CExtPubKey Neuter() const;
255 void SetSeed(std::span<const std::byte> seed);
256 };
257 258 /** KeyPair
259 *
260 * Wraps a `secp256k1_keypair` type, an opaque data structure for holding a secret and public key.
261 * This is intended for BIP340 keys and allows us to easily determine if the secret key needs to
262 * be negated by checking the parity of the public key. This class primarily intended for passing
263 * secret keys to libsecp256k1 functions expecting a `secp256k1_keypair`. For all other cases,
264 * CKey should be preferred.
265 *
266 * A KeyPair can be created from a CKey with an optional merkle_root tweak (per BIP342). See
267 * CKey::ComputeKeyPair for more details.
268 */
269 class KeyPair
270 {
271 public:
272 KeyPair() noexcept = default;
273 KeyPair(KeyPair&&) noexcept = default;
274 KeyPair& operator=(KeyPair&&) noexcept = default;
275 KeyPair& operator=(const KeyPair& other)
276 {
277 if (this != &other) {
278 if (other.m_keypair) {
279 MakeKeyPairData();
280 *m_keypair = *other.m_keypair;
281 } else {
282 ClearKeyPairData();
283 }
284 }
285 return *this;
286 }
287 288 KeyPair(const KeyPair& other) { *this = other; }
289 290 friend KeyPair CKey::ComputeKeyPair(const uint256* merkle_root) const;
291 [[nodiscard]] bool SignSchnorr(const uint256& hash, std::span<unsigned char> sig, const uint256& aux) const;
292 293 //! Check whether this keypair is valid.
294 bool IsValid() const { return !!m_keypair; }
295 296 private:
297 KeyPair(const CKey& key, const uint256* merkle_root);
298 299 using KeyType = std::array<unsigned char, 96>;
300 secure_unique_ptr<KeyType> m_keypair;
301 302 void MakeKeyPairData()
303 {
304 if (!m_keypair) m_keypair = make_secure_unique<KeyType>();
305 }
306 307 void ClearKeyPairData()
308 {
309 m_keypair.reset();
310 }
311 };
312 313 /** Check that required EC support is available at runtime. */
314 bool ECC_InitSanityCheck();
315 316 /** Access the secp256k1 context used for signing and MuSig2 nonce generation. */
317 secp256k1_context* GetSecp256k1SignContext();
318 319 /**
320 * RAII class initializing and deinitializing global state for elliptic curve support.
321 * Only one instance may be initialized at a time.
322 *
323 * In the future global ECC state could be removed, and this class could contain
324 * state and be passed as an argument to ECC key functions.
325 */
326 class ECC_Context
327 {
328 public:
329 ECC_Context();
330 ~ECC_Context();
331 };
332 333 #endif // BITCOIN_KEY_H
334