added documentation and mainnet warning for side-channel attacks (minerva)

Author: karask

README.rst

@@ -9,6 +9,14 @@ The API documentation can be build with Sphinx but is also available as a PDF fo
 
 Complementary to this library is a CC BY-SA 4.0 licensed `Bitcoin programming book <https://github.com/karask/bitcoin-textbook>`_.
 
+Security model
+--------------
+This library is intentionally pure Python and educational. Private-key operations, including ECDSA signing and Taproot/Schnorr signing, are not side-channel hardened and should not be used to protect real funds in timing-observable environments. 
+
+The ``python-ecdsa`` dependency has a known Minerva timing-attack advisory (CVE-2024-23342) with no patched pure-Python release. Keeping the library pure Python means this class of side-channel risk cannot be fully eliminated. Use the library for learning, tests, testnet, offline experiments, and transaction construction; use production wallets, hardware signers, or hardened native cryptographic libraries for real funds.
+
+Private-key warnings are enabled by default on mainnet and can be disabled with ``bitcoinutils.setup.set_security_warnings(False)``. Testnet, testnet4, signet and regtest do not emit the warning by default, so educational examples stay quiet.
+
 
 Notes
 -----

TODO

@@ -3,12 +3,6 @@ PRIORITY
 
 SHORT-TERM
 - create Address object that covers all addresses and can convert from one to another
-- python-ecdsa is vulnerable to minerva timing attacks
-  . https://github.com/karask/python-bitcoin-utils/security/dependabot/2
-  . investigate the consequences (how critical) this is for the library
-  . no pure python implementation can go around that
-  . investigate changing the code to use library pyca/cryptography or pycryptodome?
-  . there are a couple of places where we extend the library for bitcoin-specific calculations; also consider them
 - taproot's op_addchecksig simply added
   . other tapscript changes?
   . think: how to differentiate tapscript in code? (right now addchecksig can be used in any script)

bitcoinutils/keys.py

@@ -18,6 +18,7 @@
 import re
 import struct
 import hashlib
+import warnings
 from abc import ABC, abstractmethod
 from base64 import b64encode, b64decode
 from typing import Optional, List, Tuple, Union, cast
@@ -45,7 +46,7 @@
     NETWORK_SEGWIT_PREFIXES,
     TAPROOT_SIGHASH_ALL,
 )
-from bitcoinutils.setup import get_network
+from bitcoinutils.setup import get_network, should_warn_about_private_key_use
 from bitcoinutils.ripemd160 import ripemd160
 from bitcoinutils.schnorr import schnorr_sign
 from bitcoinutils.transactions import Transaction
@@ -67,6 +68,19 @@
 import bitcoinutils.bech32
 
 
+_PRIVATE_KEY_SECURITY_WARNING = (
+    "Pure-Python private-key operations in bitcoinutils are for education, "
+    "testing, and offline experimentation. They are not side-channel hardened "
+    "and should not be used to protect real funds in timing-observable "
+    "environments."
+)
+
+
+def _warn_about_private_key_use() -> None:
+    if should_warn_about_private_key_use():
+        warnings.warn(_PRIVATE_KEY_SECURITY_WARNING, RuntimeWarning, stacklevel=3)
+
+
 class PrivateKey:
     """Represents an ECDSA private key.
 
@@ -118,9 +132,15 @@ def __init__(
             used to create a specific key deterministically (default None)
         b : bytes, optional
             used to create a key from raw bytes
+
+        Notes
+        -----
+        Private-key operations are implemented in pure Python for educational
+        readability. They are not side-channel hardened.
         """
 
         if not secret_exponent and not wif and not b:
+            _warn_about_private_key_use()
             self.key = SigningKey.generate(curve=SECP256k1)
         else:
             if wif:
@@ -241,7 +261,12 @@ def sign_message(self, message: str, compressed: bool = True) -> Optional[str]:
         respectively)
 
         Returns a Bitcoin compact signature in Base64
+
+        Notes
+        -----
+        This pure-Python signing path is not side-channel hardened.
         """
+        _warn_about_private_key_use()
 
         # All bitcoin signatures include the magic prefix. It is just a string
         # added to the message to distinguish Bitcoin-specific messages.
@@ -278,6 +303,7 @@ def sign_message(self, message: str, compressed: bool = True) -> Optional[str]:
     def sign_input(
         self, tx: Transaction, txin_index: int, script: Script, sighash: int = SIGHASH_ALL
     ) -> str:
+        _warn_about_private_key_use()
         # get the digest from the transaction object and sign
         tx_digest = tx.get_transaction_digest(txin_index, script, sighash)
         return self._sign_input(tx_digest, sighash)
@@ -290,6 +316,7 @@ def sign_segwit_input(
         amount: int,
         sighash: int = SIGHASH_ALL,
     ) -> str:
+        _warn_about_private_key_use()
         # get the digest from the transaction object and sign
         tx_digest = tx.get_transaction_segwit_digest(
             txin_index, script, amount, sighash
@@ -308,6 +335,7 @@ def sign_taproot_input(
         sighash: int = TAPROOT_SIGHASH_ALL,
         tweak: bool = True,
     ) -> str:
+        _warn_about_private_key_use()
         # get the digest from the transaction object and sign
         # note that when signing a tapleaf we typically won't use tweaked
         # keys - so tweak should be set to False
@@ -336,7 +364,12 @@ def _sign_input(self, tx_digest: bytes, sighash: int = SIGHASH_ALL) -> str:
         is what is actually signed!)
 
         Returns a signature for that input
+
+        Notes
+        -----
+        This pure-Python signing path is not side-channel hardened.
         """
+        _warn_about_private_key_use()
 
         # Both R ans S cannot start with 0x00 (be signed as negative) unless
         # they are higher than 2^128 or start with 0x80.
@@ -452,7 +485,12 @@ def _sign_taproot_input(
         use tweaking so tweak should be set to False
 
         Returns a signature for that input
+
+        Notes
+        -----
+        This pure-Python Schnorr signing path is not side-channel hardened.
         """
+        _warn_about_private_key_use()
 
         byte_key = b""
 

bitcoinutils/setup.py

@@ -10,6 +10,8 @@
 # LICENSE file.
 
 NETWORK = "testnet"
+SECURITY_WARNINGS = True
+_SECURITY_WARNING_EMITTED = False
 
 networks = {"mainnet", "testnet", "testnet4", "signet", "regtest"}
 
@@ -30,6 +32,32 @@ def get_network() -> str:
     return NETWORK
 
 
+def set_security_warnings(enabled: bool) -> None:
+    """Enable or disable warnings for pure-Python private-key operations."""
+
+    global SECURITY_WARNINGS
+    global _SECURITY_WARNING_EMITTED
+    SECURITY_WARNINGS = enabled
+    if enabled:
+        _SECURITY_WARNING_EMITTED = False
+
+
+def get_security_warnings() -> bool:
+    """Return whether pure-Python private-key operation warnings are enabled."""
+
+    return SECURITY_WARNINGS
+
+
+def should_warn_about_private_key_use() -> bool:
+    """Return True the first time a private-key operation should warn."""
+
+    global _SECURITY_WARNING_EMITTED
+    if NETWORK != "mainnet" or not SECURITY_WARNINGS or _SECURITY_WARNING_EMITTED:
+        return False
+    _SECURITY_WARNING_EMITTED = True
+    return True
+
+
 def is_mainnet() -> bool:
     return NETWORK == "mainnet"
 

docs/usage/keys.rst

@@ -1,5 +1,22 @@
 Keys and Addresses module
 -------------------------
 
+Security note
+~~~~~~~~~~~~~
+
+The key APIs are pure Python and intended for education, tests, testnet, and
+offline experimentation. Private-key operations, including ECDSA signing and
+Taproot/Schnorr signing, are not side-channel hardened. They should not be used
+to protect real funds in timing-observable environments.
+
+This mirrors Bitcoin Core's Python test framework: readable Python secp256k1
+code is useful for tests and teaching, while production Bitcoin software uses
+hardened native implementations or external signers for real keys.
+
+Warnings for private-key operations are enabled by default on mainnet. They can
+be disabled with ``bitcoinutils.setup.set_security_warnings(False)``. Testnet,
+testnet4, signet and regtest do not emit the warning by default, so educational
+examples stay quiet.
+
 .. automodule:: keys
    :members:

tests/test_keys.py

@@ -11,8 +11,9 @@
 
 
 import unittest
+import warnings
 
-from bitcoinutils.setup import setup
+from bitcoinutils.setup import setup, set_security_warnings
 from bitcoinutils.keys import (
     PrivateKey,
     PublicKey,
@@ -27,6 +28,10 @@
 
 
 class TestPrivateKeys(unittest.TestCase):
+    def tearDown(self):
+        set_security_warnings(True)
+        setup("testnet")
+
     def setUp(self):
         setup("mainnet")
         self.key_wifc = "KwDiBf89QgGbjEhKnhXJuH7LrciVrZi3qYjgd9M7rFU73sVHnoWn"
@@ -56,6 +61,27 @@ def test_public_key(self):
         p = PrivateKey(secret_exponent=1)
         self.assertEqual(p.get_public_key().to_bytes(), self.public_key_bytes)
 
+    def test_private_key_generation_warns_by_default(self):
+        set_security_warnings(True)
+        with self.assertWarnsRegex(RuntimeWarning, "not side-channel hardened"):
+            PrivateKey()
+
+    def test_private_key_warning_can_be_disabled(self):
+        set_security_warnings(False)
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            PrivateKey()
+        self.assertEqual(caught, [])
+
+    def test_private_key_generation_does_not_warn_on_test_networks(self):
+        for network in ["testnet", "testnet4", "signet", "regtest"]:
+            setup(network)
+            set_security_warnings(True)
+            with warnings.catch_warnings(record=True) as caught:
+                warnings.simplefilter("always")
+                PrivateKey()
+            self.assertEqual(caught, [])
+
 
 class TestPublicKeys(unittest.TestCase):
     def setUp(self):
@@ -176,6 +202,10 @@ def test_creation_address(self):
 
 
 class TestSignAndVerify(unittest.TestCase):
+    def tearDown(self):
+        set_security_warnings(True)
+        setup("testnet")
+
     def setUp(self):
         setup("mainnet")
         self.message = "The test!"
@@ -199,6 +229,39 @@ def test_sign_and_verify(self):
         self.assertEqual(signature, self.deterministic_signature)
         self.assertTrue(PublicKey.verify_message(self.address, signature, self.message))
 
+    def test_sign_message_warns_by_default(self):
+        set_security_warnings(True)
+        with self.assertWarnsRegex(RuntimeWarning, "not side-channel hardened"):
+            self.priv.sign_message(self.message)
+
+    def test_sign_message_warning_can_be_disabled(self):
+        set_security_warnings(False)
+        with warnings.catch_warnings(record=True) as caught:
+            warnings.simplefilter("always")
+            self.priv.sign_message(self.message)
+        self.assertEqual(caught, [])
+
+    def test_sign_message_does_not_warn_on_test_networks(self):
+        for network in ["testnet", "testnet4", "signet", "regtest"]:
+            setup(network)
+            set_security_warnings(True)
+            with warnings.catch_warnings(record=True) as caught:
+                warnings.simplefilter("always")
+                self.priv.sign_message(self.message)
+            self.assertEqual(caught, [])
+
+    def test_transaction_signing_helper_warns_by_default(self):
+        set_security_warnings(True)
+        digest = bytes.fromhex("00" * 32)
+        with self.assertWarnsRegex(RuntimeWarning, "not side-channel hardened"):
+            self.priv._sign_input(digest)
+
+    def test_taproot_signing_helper_warns_by_default(self):
+        set_security_warnings(True)
+        digest = bytes.fromhex("00" * 32)
+        with self.assertWarnsRegex(RuntimeWarning, "not side-channel hardened"):
+            self.priv._sign_taproot_input(digest)
+
     def test_verify_external(self):
         self.assertTrue(
             PublicKey.verify_message(

tests/test_setup.py

@@ -7,6 +7,8 @@
     is_testnet4,
     is_signet,
     is_regtest,
+    set_security_warnings,
+    get_security_warnings,
 )
 
 
@@ -34,6 +36,15 @@ def test_invalid_network(self):
 
         setup("testnet")
 
+    def test_security_warning_setting(self):
+        set_security_warnings(False)
+        self.assertFalse(get_security_warnings())
+
+        set_security_warnings(True)
+        self.assertTrue(get_security_warnings())
+
+        setup("testnet")
+
 
 if __name__ == "__main__":
     unittest.main()