cloud-sql-python-connector 1.22.0__py3-none-any.whl → 1.24.0__py3-none-any.whl

{cloud_sql_python_connector-1.22.0.dist-info → cloud_sql_python_connector-1.24.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cloud-sql-python-connector
-Version: 1.22.0
+Version: 1.24.0
 Summary: Google Cloud SQL Python Connector library
 Author-email: Google LLC <googleapis-packages@google.com>
 License-Expression: Apache-2.0
@@ -12,13 +12,13 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.9
+Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp
@@ -26,9 +26,7 @@ Requires-Dist: cryptography>=42.0.0
 Requires-Dist: dnspython>=2.0.0
 Requires-Dist: Requests
 Requires-Dist: google-auth>=2.28.0
-Requires-Dist: grpcio
-Requires-Dist: protobuf
-Requires-Dist: googleapis-common-protos
+Requires-Dist: google-cloud-sql>=0.1.1
 Provides-Extra: pymysql
 Requires-Dist: PyMySQL>=1.1.0; extra == "pymysql"
 Provides-Extra: pg8000
@@ -244,7 +242,7 @@ from google.cloud.sql.connector import Connector
 
 # Note: all parameters below are optional
 connector = Connector(
-    ip_type="public",  # can also be "private" or "psc"
+    ip_type="public",  # can also be "private", "psc", or "sql_data"
     enable_iam_auth=False,
     timeout=30,
     credentials=custom_creds, # google.auth.credentials.Credentials
@@ -322,7 +320,11 @@ with, set the `ip_type` keyword argument when initializing a `Connector()` or wh
 calling `connector.connect()`.
 
 Possible values for `ip_type` are `"public"` (default value),
-`"private"`, and `"psc"`.
+`"private"`, `"psc"`, and `"sql_data"`.
+
+> [!NOTE]
+>
+> Usage of the `asyncpg` driver does not currently support `ip_type="sql_data"` (`IPTypes.SQL_DATA`).
 
 Example:
 
@@ -788,6 +790,84 @@ async def main():
         await pool.dispose()
 ```
 
+### Post-Quantum Cryptography (PQC)
+
+The Cloud SQL Python Connector establishes mTLS connections over TLS 1.3 using
+Python's standard `ssl` module without restricting key-exchange groups. When
+Python's `ssl` module is linked against **OpenSSL 3.5 or later**, TLS 1.3
+connections automatically offer and negotiate the hybrid post-quantum key
+exchange group **`X25519MLKEM768`** (ML-KEM-768 combined with X25519) whenever
+the Cloud SQL instance supports it. No code changes or connector configuration
+are required.
+
+#### Checking your OpenSSL version
+
+Post-quantum TLS key exchange depends on the OpenSSL library linked into your
+Python runtime's `ssl` module (not the Python language version or the
+`cryptography` package version alone). Run the following command to check which
+OpenSSL version your Python interpreter uses:
+
+```sh
+python3 -c "import ssl; print(ssl.OPENSSL_VERSION)"
+```
+
+- **OpenSSL 3.5.0 or higher** (for example, `python:3.13-trixie` / Debian 13
+  "Trixie" container images; check your runtime with the one-liner above):
+  `X25519MLKEM768` is enabled by default on TLS 1.3 connections.
+- **OpenSSL earlier than 3.5.0** (for example, Ubuntu 24.04 LTS, which ships
+  system OpenSSL 3.0.x): TLS 1.3 connections continue to use classical elliptic
+  curve Diffie-Hellman (such as `X25519` or `P-256`).
+
+> [!NOTE]
+>
+> Connections configured with `ip_type="sql_data"` (`IPTypes.SQL_DATA`) stream
+> over gRPC (`grpcio`), which uses its bundled BoringSSL (supporting
+> `X25519MLKEM768` independently of Python's `ssl` module and `OPENSSL_CONF`),
+> whereas its direct-TLS fallback path uses `create_ssl_context()` and Python's
+> linked OpenSSL library as described above.
+
+#### Backwards compatibility
+
+Hybrid post-quantum key exchange is backwards-compatible. On OpenSSL 3.5+,
+Python's `ssl` module advertises both hybrid (`X25519MLKEM768`) and classical
+(`X25519`, `secp256r1`, etc.) groups in the TLS 1.3 `ClientHello`. If either the
+client runtime (OpenSSL `< 3.5`) or the Cloud SQL instance only supports
+classical groups, the TLS 1.3 handshake automatically falls back to classical
+ECDHE without error.
+
+#### Opting out
+
+If you need to disable post-quantum key exchange on an OpenSSL 3.5+ client (for
+example, to troubleshoot a network middlebox sensitive to larger TLS
+`ClientHello` records), configure OpenSSL's `Groups` list via an OpenSSL
+configuration file (`OPENSSL_CONF`) to advertise only classical curves.
+
+> [!WARNING]
+>
+> Setting `OPENSSL_CONF` replaces the system default OpenSSL configuration for
+> the entire Python process. It affects **all** TLS connections made by the
+> process (not just Cloud SQL connections), and starting from a minimal file
+> omits distribution defaults (such as Debian's `MinProtocol` or
+> `CipherString`). Copy your system's `openssl.cnf` (check `openssl version -d`,
+> typically `/etc/ssl/openssl.cnf`) and add `Groups = X25519:P-256:P-384` under
+> its `[system_default_sect]` section rather than using a bare file from
+> scratch.
+
+For example, after copying `/etc/ssl/openssl.cnf`, ensure its
+`[system_default_sect]` (referenced via `ssl_conf` -> `system_default`) sets
+`Groups`:
+
+```ini
+[system_default_sect]
+Groups = X25519:P-256:P-384
+```
+
+Then point `OPENSSL_CONF` to your modified copy when starting your application:
+
+```sh
+OPENSSL_CONF=/path/to/openssl.cnf python3 app.py
+```
+
 ### Debug Logging
 
 The Cloud SQL Python Connector uses the standard [Python logging module][python-logging]

cloud_sql_python_connector-1.24.0.dist-info/RECORD

@@ -0,0 +1,28 @@
+cloud_sql_python_connector-1.24.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+google/cloud/sql/connector/__init__.py,sha256=pfa-FD-VRpYI49OUul9p6UFDp7G_yT2f6WS9rZMn8CM,1148
+google/cloud/sql/connector/asyncpg.py,sha256=MpZhwFke0WXvYD3OcEF1Ok0qHl-CU7ZIPy85PCog5QY,2002
+google/cloud/sql/connector/client.py,sha256=GfiZKDDBOxeA0yfqETQuaw3Nhg0BS71oQNZNxq3CooY,14991
+google/cloud/sql/connector/connection_info.py,sha256=NnHSHs1PZ_9WeFICkZ53gbA2hVvlWuzdBdhWizOI6hs,5770
+google/cloud/sql/connector/connection_name.py,sha256=SCCVeWb8YN0f9My09_l9FGTr6iRbi1b_52TJQaS6xzM,2574
+google/cloud/sql/connector/connector.py,sha256=8A4uxTIGJKxnRgG2TqBHQwi4dG5KPO_1vNAQkNrR5vs,41574
+google/cloud/sql/connector/enums.py,sha256=F_mUdwscpW2fAzw4XElSy4BWkWcGQAkBOAUG8bvd3vg,3118
+google/cloud/sql/connector/exceptions.py,sha256=-QgsUq4gZaMrl3MH5KnsfJybEegAKW84-sdRmPKT-Dg,3137
+google/cloud/sql/connector/instance.py,sha256=j3xj3ZuSpV7AcQz6_eYsS6F6bFPySKcGeFYfNOnIEKU,17269
+google/cloud/sql/connector/lazy.py,sha256=9OOSfr13aX1OSA77V72Utp8M8VUQlwLloogRlUm0GDE,6746
+google/cloud/sql/connector/monitored_cache.py,sha256=BarNBg-VsthW5bguGl3aq17IP4QaiF099W0AnrboujM,6919
+google/cloud/sql/connector/pg8000.py,sha256=tbqFSIoSguMX1hTZ4kWeBOKLhLHKX1Vq5SespfA0Y0w,1801
+google/cloud/sql/connector/postgres_connection.py,sha256=NCUCZ_X6svNoJaqSClYDyqXaIArZYPQrPZu7wC-LtjU,7509
+google/cloud/sql/connector/psycopg.py,sha256=UD7OFVJ7C_PPsiIWzpbi1k3YIkqC4rM1pQS08wPeSM0,10950
+google/cloud/sql/connector/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+google/cloud/sql/connector/pymysql.py,sha256=MOau37nTOTesUR5Hor7lLtEckvvGThzjECEWQYHcM8U,2166
+google/cloud/sql/connector/pytds.py,sha256=e-KBCqv0m3a7cRi9YmFHNuYqClhlJbf-KoF611w-1Ck,2304
+google/cloud/sql/connector/rate_limiter.py,sha256=60k-r9h-nUBqovVIHnIGbW0NMgUGD4exH_rZ02ukNa0,2924
+google/cloud/sql/connector/refresh_utils.py,sha256=Eghd-_uR5ndCGLsPgnyeUOoAvN7Tz4yzTlQFW4QWOjo,5228
+google/cloud/sql/connector/resolver.py,sha256=4U8G0Pxwmy64qoRmP5shLnmIykxcGcGCoFSH_7tr120,6353
+google/cloud/sql/connector/sqldata_client.py,sha256=vov9R3xI_0LBxByMUIBDBsXZOE64cnUADp25Tp4Kvo0,23892
+google/cloud/sql/connector/utils.py,sha256=bGsWj_SupSBmxcnsaMlmREP7hyLV7CcZ4g2_qHzHVoA,4119
+google/cloud/sql/connector/version.py,sha256=juuKD5HYyccQin3zqup25QoyaBFJQnEtQgG7cgdeFIg,598
+cloud_sql_python_connector-1.24.0.dist-info/METADATA,sha256=fLmn8G44gYU1v-gXeu3FvCGScL1xqipmX6lh3UfSB1w,35170
+cloud_sql_python_connector-1.24.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+cloud_sql_python_connector-1.24.0.dist-info/top_level.txt,sha256=_1QvSJIhFAGfxb79D6DhB7SUw2X6T4rwnz_LLrbcD3c,7
+cloud_sql_python_connector-1.24.0.dist-info/RECORD,,

{cloud_sql_python_connector-1.22.0.dist-info → cloud_sql_python_connector-1.24.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (84.0.0)
+Generator: setuptools (84.2.1)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

google/cloud/sql/connector/client.py

@@ -173,9 +173,13 @@ class CloudSQLClient:
             if psc_dns_names:
                 ip_addresses["PSC"] = psc_dns_names
 
+        server_ca_cert = None
+        if "serverCaCert" in ret_dict and "cert" in ret_dict["serverCaCert"]:
+            server_ca_cert = ret_dict["serverCaCert"]["cert"]
+
         return {
             "ip_addresses": ip_addresses,
-            "server_ca_cert": ret_dict["serverCaCert"]["cert"],
+            "server_ca_cert": server_ca_cert,
             "database_version": ret_dict["databaseVersion"],
         }
 
@@ -271,7 +275,15 @@ class CloudSQLClient:
         finally:
             resp.raise_for_status()
 
-        ephemeral_cert: str = ret_dict["ephemeralCert"]["cert"]
+        try:
+            ephemeral_cert: str = ret_dict["ephemeralCert"]["cert"]
+        except KeyError as e:
+            logger.error(
+                "KeyError in _get_ephemeral parsing generateEphemeralCert: %s. Response dict: %s",
+                e,
+                ret_dict,
+            )
+            raise
 
         # decode cert to read expiration
         x509 = load_pem_x509_certificate(
@@ -285,7 +297,7 @@ class CloudSQLClient:
             # google.auth library strips timezone info for backwards compatibality
             # reasons with Python 2. Add it back to allow timezone aware datetimes.
             # Ref: https://github.com/googleapis/google-auth-library-python/blob/49a5ff7411a2ae4d32a7d11700f9f961c55406a9/google/auth/_helpers.py#L93-L99
-            token_expiration = token_expiration.replace(tzinfo=datetime.timezone.utc)
+            token_expiration = token_expiration.replace(tzinfo=datetime.UTC)
 
             expiration = min(expiration, token_expiration)
         return ephemeral_cert, expiration

google/cloud/sql/connector/connection_info.py

@@ -21,6 +21,7 @@ import ssl
 from typing import Any, TYPE_CHECKING
 
 from google.cloud.sql.connector.connection_name import ConnectionName
+from google.cloud.sql.connector.exceptions import CloudSQLConnectionError
 from google.cloud.sql.connector.exceptions import CloudSQLIPTypeError
 from google.cloud.sql.connector.exceptions import TLSVersionError
 from google.cloud.sql.connector.utils import AsyncTemporaryDirectory
@@ -45,6 +46,10 @@ class ConnectionInfoCache(abc.ABC):
     async def force_refresh(self) -> None:
         pass
 
+    @abc.abstractmethod
+    def record_principal(self, user: str, database: str) -> None:
+        pass
+
     @abc.abstractmethod
     async def close(self) -> None:
         pass
@@ -62,7 +67,7 @@ class ConnectionInfo:
 
     conn_name: ConnectionName
     client_cert: str
-    server_ca_cert: str
+    server_ca_cert: str | None
     private_key: bytes
     ip_addrs: dict[str, Any]
     database_version: str
@@ -78,6 +83,12 @@ class ConnectionInfo:
         # if SSL context is cached, use it
         if self.context is not None:
             return self.context
+        
+        if self.server_ca_cert is None:
+            raise CloudSQLConnectionError(
+                "Cannot create SSL context: server CA certificate is missing."
+            )
+
         context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
 
         # update ssl.PROTOCOL_TLS_CLIENT default