Make it explicit to generate the CA

Author: julien-duponchelle

docs/custom-ca.md

@@ -17,8 +17,6 @@ To intercept HTTPS traffic, you need to create your own CA certificate and confi
 to trust this CA. This allows the proxy to generate and sign certificates for the target domains on-the-fly,
 allowing it to decrypt and inspect the HTTPS traffic.
 
-By default the library create a temporary Root CA on the fly but if you want to trust the CA in your
-browser you will need the persist the CA.
 
 ## Using Custom CA Keys with TLSStore
 
@@ -44,8 +42,14 @@ To persist a CA to disk for reuse across multiple proxy runs:
 ```python
 from asyncio_https_proxy import TLSStore
 
-# Create a new TLS store (will generate a new CA)
-tls_store = TLSStore()
+# Create a new TLS store with explicit CA generation
+tls_store = TLSStore.generate_ca(
+    country="FR",
+    state="Ile-de-France",
+    locality="Paris",
+    organization="My Company",
+    common_name="My Company CA"
+)
 
 # Save the CA to disk for future use
 tls_store.save_ca_to_disk("ca_private_key.pem", "ca_certificate.pem")
@@ -63,8 +67,14 @@ if os.path.exists("ca_private_key.pem") and os.path.exists("ca_certificate.pem")
     tls_store = TLSStore.load_ca_from_disk("ca_private_key.pem", "ca_certificate.pem")
     print("Loaded existing CA from disk")
 else:
-    # Create new CA and save it to disk
-    tls_store = TLSStore()
+    # Create new CA with explicit parameters and save it to disk
+    tls_store = TLSStore.generate_ca(
+        country="FR",
+        state="Ile-de-France",
+        locality="Paris",
+        organization="My Company",
+        common_name="My Company CA"
+    )
     tls_store.save_ca_to_disk("ca_private_key.pem", "ca_certificate.pem")
     print("Created new CA and saved to disk")
 ```

docs/getting-started.md

@@ -110,8 +110,14 @@ async def main():
     print("\nThe proxy will intercept both HTTP and HTTPS traffic.")
     print("For HTTPS, it generates certificates on-the-fly using a built-in CA.")
 
-    # Initialize TLS store (creates CA certificate automatically)
-    tls_store = TLSStore()
+    # Initialize TLS store with explicit CA generation
+    tls_store = TLSStore.generate_ca(
+        country="FR",
+        state="Ile-de-France",
+        locality="Paris",
+        organization="Getting Started Proxy",
+        common_name="Getting Started Proxy CA"
+    )
     print(f"\nGenerated CA certificate. Clients may show security warnings.")
     print("Use --insecure with curl")
 

examples/custom_http_client.py

@@ -57,8 +57,14 @@ async def main():
     print(f"  curl --insecure --proxy http://{host}:{port} http://httpbin.org/get")
     print("\nPress Ctrl+C to stop the proxy")
 
-    # Initialize the TLS store with a self-signed CA certificate
-    tls_store = TLSStore()
+    # Initialize the TLS store with a generated CA certificate
+    tls_store = TLSStore.generate_ca(
+        country="FR",
+        state="Ile-de-France",
+        locality="Paris",
+        organization="Example Proxy",
+        common_name="Example Proxy CA"
+    )
 
     server = await start_proxy_server(
         handler_builder=lambda: BasicProxyHandler(),

examples/forward_proxy_usage.py

@@ -71,7 +71,13 @@ async def main():
     print("\nPress Ctrl+C to stop the proxy")
 
     # Initialize the TLS store for HTTPS interception
-    tls_store = TLSStore()
+    tls_store = TLSStore.generate_ca(
+        country="FR",
+        state="Ile-de-France",
+        locality="Paris",
+        organization="Forward Proxy Example",
+        common_name="Forward Proxy CA"
+    )
 
     server = await start_proxy_server(
         handler_builder=lambda: LoggingForwardProxyHandler(),

examples/persistent_ca_usage.py

@@ -28,9 +28,15 @@ def get_or_create_ca():
     else:
         print("No existing CA files found.")
 
-    # Create new TLSStore with default CA generation
+    # Create new TLSStore with explicit CA generation
     print("Creating new TLS store...")
-    tls_store = TLSStore()
+    tls_store = TLSStore.generate_ca(
+        country="FR",
+        state="Ile-de-France",
+        locality="Paris",
+        organization="Persistent Proxy Example",
+        common_name="Persistent Proxy CA"
+    )
 
     # Save the generated CA to disk for future use
     print("Saving CA to disk for future reuse...")

src/asyncio_https_proxy/tls_store.py

@@ -14,37 +14,60 @@
 
 class TLSStore:
     """
-    A simple in-memory TLS store that generates a CA and signs certificates for domains on the fly.
+    A simple in-memory TLS store that signs certificates for domains on the fly using a provided CA.
+    
+    Use TLSStore.generate_ca() to create a new CA, or TLSStore.load_ca_from_disk() to load an existing one.
     
     Args:
-        ca_key: Optional CA private key. If provided, ca_cert must also be provided.
-        ca_cert: Optional CA certificate. If provided, ca_key must also be provided.        
+        ca_key: The CA private key (must be EllipticCurve)
+        ca_cert: The CA certificate        
     """
 
     def __init__(
         self,
-        ca_key: Optional[ec.EllipticCurvePrivateKey] = None,
-        ca_cert: Optional[x509.Certificate] = None,
+        ca_key: ec.EllipticCurvePrivateKey,
+        ca_cert: x509.Certificate,
     ):
-        if (ca_key is None) != (ca_cert is None):
-            raise ValueError("Both ca_key and ca_cert must be provided together, or neither")
-        
-        if ca_key is not None and ca_cert is not None:
-            self._ca = (ca_key, ca_cert)
-        else:
-            self._ca = self._generate_ca()
+        """
+        Initialize TLSStore with an existing CA key and certificate.
         
+        Args:
+            ca_key: The CA private key (must be EllipticCurve)
+            ca_cert: The CA certificate
+        """
+        self._ca = (ca_key, ca_cert)
         self._store = {}
 
-    def _generate_ca(self):
+    @classmethod
+    def generate_ca(
+        cls,
+        country: str,
+        state: str,
+        locality: str,
+        organization: str,
+        common_name: str,
+    ) -> "TLSStore":
+        """
+        Generate a new CA and create a TLSStore instance with it.
+        
+        Args:
+            country: Two-letter country code (e.g., "FR", "US")
+            state: State or province name (e.g., "Ile-de-France", "California")
+            locality: City or locality name (e.g., "Paris", "San Francisco")
+            organization: Organization name (e.g., "My Company")
+            common_name: Common name for the CA (e.g., "My Company CA")
+            
+        Returns:
+            TLSStore instance with the generated CA
+        """
         root_key = ec.generate_private_key(ec.SECP256R1())
         subject = issuer = x509.Name(
             [
-                x509.NameAttribute(NameOID.COUNTRY_NAME, "FR"),
-                x509.NameAttribute(NameOID.STATE_OR_PROVINCE_NAME, "Ile-de-France"),
-                x509.NameAttribute(NameOID.LOCALITY_NAME, "Paris"),
-                x509.NameAttribute(NameOID.ORGANIZATION_NAME, "Asyncio HTTPS Proxy"),
-                x509.NameAttribute(NameOID.COMMON_NAME, "Asyncio HTTPS Proxy CA"),
+                x509.NameAttribute(NameOID.COUNTRY_NAME, country),
+                x509.NameAttribute(NameOID.STATE_OR_PROVINCE_NAME, state),
+                x509.NameAttribute(NameOID.LOCALITY_NAME, locality),
+                x509.NameAttribute(NameOID.ORGANIZATION_NAME, organization),
+                x509.NameAttribute(NameOID.COMMON_NAME, common_name),
             ]
         )
         root_cert = (
@@ -83,7 +106,8 @@ def _generate_ca(self):
             )
             .sign(root_key, hashes.SHA256())
         )
-        return (root_key, root_cert)
+        return cls(ca_key=root_key, ca_cert=root_cert)
+
 
     def _generate_cert(
         self, domain

tests/test_server.py

@@ -23,7 +23,13 @@ async def on_client_connected(self):
 def tls_store():
     from asyncio_https_proxy.tls_store import TLSStore
 
-    return TLSStore()
+    return TLSStore.generate_ca(
+        country="FR",
+        state="Ile-de-France", 
+        locality="Paris",
+        organization="Test Org",
+        common_name="Test CA"
+    )
 
 
 @pytest.fixture

tests/test_tls_store.py

@@ -12,7 +12,13 @@
 @pytest.fixture
 def tls_store():
     """Create a fresh TLSStore instance for testing"""
-    return TLSStore()
+    return TLSStore.generate_ca(
+        country="FR",
+        state="Ile-de-France", 
+        locality="Paris",
+        organization="Asyncio HTTPS Proxy",
+        common_name="Asyncio HTTPS Proxy CA"
+    )
 
 
 def test_tls_store_initialization(tls_store):