cloud-sql-python-connector 1.22.0__tar.gz → 1.24.0__tar.gz

{cloud_sql_python_connector-1.22.0 → cloud_sql_python_connector-1.24.0}/PKG-INFO

@@ -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.22.0 → cloud_sql_python_connector-1.24.0}/README.md

@@ -201,7 +201,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
@@ -279,7 +279,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:
 
@@ -745,6 +749,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.22.0 → cloud_sql_python_connector-1.24.0}/cloud_sql_python_connector.egg-info/PKG-INFO

@@ -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.22.0 → cloud_sql_python_connector-1.24.0}/cloud_sql_python_connector.egg-info/SOURCES.txt

@@ -18,6 +18,7 @@ google/cloud/sql/connector/instance.py
 google/cloud/sql/connector/lazy.py
 google/cloud/sql/connector/monitored_cache.py
 google/cloud/sql/connector/pg8000.py
+google/cloud/sql/connector/postgres_connection.py
 google/cloud/sql/connector/psycopg.py
 google/cloud/sql/connector/py.typed
 google/cloud/sql/connector/pymysql.py
@@ -25,5 +26,6 @@ google/cloud/sql/connector/pytds.py
 google/cloud/sql/connector/rate_limiter.py
 google/cloud/sql/connector/refresh_utils.py
 google/cloud/sql/connector/resolver.py
+google/cloud/sql/connector/sqldata_client.py
 google/cloud/sql/connector/utils.py
 google/cloud/sql/connector/version.py

{cloud_sql_python_connector-1.22.0 → cloud_sql_python_connector-1.24.0}/cloud_sql_python_connector.egg-info/requires.txt

@@ -3,9 +3,7 @@ cryptography>=42.0.0
 dnspython>=2.0.0
 Requests
 google-auth>=2.28.0
-grpcio
-protobuf
-googleapis-common-protos
+google-cloud-sql>=0.1.1
 
 [asyncpg]
 asyncpg>=0.30.0

{cloud_sql_python_connector-1.22.0 → cloud_sql_python_connector-1.24.0}/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

{cloud_sql_python_connector-1.22.0 → cloud_sql_python_connector-1.24.0}/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