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

{cloud_sql_python_connector-1.23.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.23.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
@@ -16,6 +16,7 @@ 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.11
 Description-Content-Type: text/markdown
@@ -789,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.23.0 → cloud_sql_python_connector-1.24.0}/README.md

@@ -749,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.23.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.23.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
@@ -16,6 +16,7 @@ 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.11
 Description-Content-Type: text/markdown
@@ -789,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.23.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

{cloud_sql_python_connector-1.23.0 → cloud_sql_python_connector-1.24.0}/google/cloud/sql/connector/connection_info.py

@@ -46,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

{cloud_sql_python_connector-1.23.0 → cloud_sql_python_connector-1.24.0}/google/cloud/sql/connector/connector.py

@@ -23,6 +23,7 @@ import logging
 import os
 import random
 import socket
+import ssl
 from threading import Thread
 import time
 from types import TracebackType
@@ -38,6 +39,7 @@ from google.cloud.sql.connector import psycopg
 from google.cloud.sql.connector import pymysql
 from google.cloud.sql.connector import pytds
 from google.cloud.sql.connector.client import CloudSQLClient
+from google.cloud.sql.connector.connection_info import ConnectionInfo
 from google.cloud.sql.connector.connection_name import ConnectionName
 from google.cloud.sql.connector.enums import DriverMapping
 from google.cloud.sql.connector.enums import IPTypes
@@ -49,6 +51,7 @@ from google.cloud.sql.connector.exceptions import ResourceExhaustedError
 from google.cloud.sql.connector.instance import RefreshAheadCache
 from google.cloud.sql.connector.lazy import LazyRefreshCache
 from google.cloud.sql.connector.monitored_cache import MonitoredCache
+from google.cloud.sql.connector.postgres_connection import PostgresConnection
 from google.cloud.sql.connector.resolver import DefaultResolver
 from google.cloud.sql.connector.resolver import DnsResolver
 from google.cloud.sql.connector.sqldata_client import SqlDataClient
@@ -346,6 +349,7 @@ class Connector:
         self,
         conn_name: ConnectionName,
         enable_iam_auth: bool,
+        ip_type: IPTypes | None = None,
     ) -> MonitoredCache:
         assert self._client is not None, "client must be initialized before creating cache"
         assert self._keys is not None, "keys must be initialized before creating cache"
@@ -355,6 +359,13 @@ class Connector:
         ].closed:
             return self._cache[(str(conn_name), enable_iam_auth)]
 
+        effective_ip_type = ip_type if ip_type is not None else self._ip_type
+        dial_func = partial(
+            self._dial_probe_connection,
+            enable_iam_auth=enable_iam_auth,
+            ip_type=effective_ip_type,
+        )
+
         if self._refresh_strategy == RefreshStrategy.LAZY:
             logger.debug(
                 f"['{conn_name}']: Refresh strategy is set to lazy refresh"
@@ -364,6 +375,9 @@ class Connector:
                 self._client,
                 self._keys,
                 enable_iam_auth,
+                ip_type=effective_ip_type,
+                timeout=self._timeout,
+                dial_func=dial_func,
             )
         else:
             logger.debug(
@@ -374,6 +388,9 @@ class Connector:
                 self._client,
                 self._keys,
                 enable_iam_auth,
+                ip_type=effective_ip_type,
+                timeout=self._timeout,
+                dial_func=dial_func,
             )
         # wrap cache as a MonitoredCache
         monitored_cache = MonitoredCache(
@@ -452,7 +469,9 @@ class Connector:
 
         conn_name = await self._resolver.resolve(instance_connection_string)
         if ip_type != IPTypes.SQL_DATA:
-            monitored_cache = self._get_or_create_cache(conn_name, enable_iam_auth)
+            monitored_cache = self._get_or_create_cache(
+                conn_name, enable_iam_auth, ip_type
+            )
 
         connect_func = {
             "pymysql": pymysql.connect,
@@ -587,33 +606,7 @@ class Connector:
                     await self._remove_cached(str(conn_name), enable_iam_auth)
                     raise
 
-                targets = []
-                if conn_info.conn_name.domain_name and isinstance(self._resolver, DnsResolver):
-                    try:
-                        ips = await self._resolver.resolve_a_record(conn_info.conn_name.domain_name)
-                        if ips:
-                            targets.extend(ips)
-                            logger.debug(
-                                f"['{instance_connection_string}']: Custom DNS name "
-                                f"'{conn_info.conn_name.domain_name}' resolved to '{ips}', "
-                                "using it to connect"
-                            )
-                        else:
-                            logger.debug(
-                                f"['{instance_connection_string}']: Custom DNS name "
-                                f"'{conn_info.conn_name.domain_name}' resolved but returned no "
-                                f"entries, using '{preferred_ips}' from instance metadata"
-                            )
-                            targets.extend(preferred_ips)
-                    except Exception as e:  # noqa: BLE001
-                        logger.debug(
-                            f"['{instance_connection_string}']: Custom DNS name "
-                            f"'{conn_info.conn_name.domain_name}' did not resolve to an IP "
-                            f"address: {e}, using '{preferred_ips}' from instance metadata"
-                        )
-                        targets.extend(preferred_ips)
-                else:
-                    targets.extend(preferred_ips)
+                targets = await self._resolve_targets(conn_info, preferred_ips)
                 # format `user` param for automatic IAM database authn
                 if enable_iam_auth:
                     formatted_user = format_database_user(
@@ -636,14 +629,28 @@ class Connector:
                                 await conn_info.create_ssl_context(enable_iam_auth),
                                 **kwargs,
                             )
+                            if (
+                                enable_iam_auth
+                                and conn_info.database_version.startswith("POSTGRES")
+                            ):
+                                db_name = kwargs.get("database")
+                                if db_name is None:
+                                    db_name = kwargs.get("db")
+                                user = kwargs.get("user")
+                                if user:
+                                    monitored_cache.record_principal(
+                                        str(user),
+                                        str(db_name) if db_name else str(user),
+                                    )
                             last_ex = None
                             return conn
 
                         # Create socket with SSLContext for sync drivers
                         ctx = await conn_info.create_ssl_context(enable_iam_auth)
                         raw_sock = socket.create_connection((target_ip, SERVER_PROXY_PORT))
+                        sync_sock: socket.socket | ssl.SSLSocket | PostgresConnection
                         try:
-                            sock = ctx.wrap_socket(
+                            sync_sock = ctx.wrap_socket(
                                 raw_sock,
                                 server_hostname=target_ip,
                             )
@@ -651,15 +658,24 @@ class Connector:
                             raw_sock.close()
                             raise
 
+                        if (
+                            enable_iam_auth
+                            and conn_info.database_version.startswith("POSTGRES")
+                        ):
+                            sync_sock = PostgresConnection(
+                                sync_sock,
+                                on_startup=monitored_cache.record_principal,
+                            )
+
                         # If this connection was opened using a domain name, then store it
                         # for later in case we need to forcibly close it on failover.
                         if conn_info.conn_name.domain_name:
-                            monitored_cache.sockets.append(sock)
+                            monitored_cache.sockets.append(sync_sock)
                         # Synchronous drivers are blocking and run using executor
                         connect_partial = partial(
                             connector,
                             target_ip,
-                            sock,
+                            sync_sock,
                             **kwargs,
                         )
                         conn = await self._loop.run_in_executor(None, connect_partial)
@@ -670,7 +686,6 @@ class Connector:
                             f"['{conn_info.conn_name}']: Connection to {target_ip} failed: {e}"
                         )
                         last_ex = e
-
                 if last_ex:
                     raise last_ex
 
@@ -694,6 +709,87 @@ class Connector:
         cache = self._cache.pop((instance_connection_string, enable_iam_auth))
         await cache.close()
 
+    async def _resolve_targets(
+        self,
+        conn_info: ConnectionInfo,
+        preferred_ips: list[str],
+    ) -> list[str]:
+        """Resolves target IP addresses for a Cloud SQL instance, with DNS fallback."""
+        targets: list[str] = []
+        if conn_info.conn_name.domain_name and isinstance(self._resolver, DnsResolver):
+            try:
+                ips = await self._resolver.resolve_a_record(
+                    conn_info.conn_name.domain_name
+                )
+                if ips:
+                    targets.extend(ips)
+                    logger.debug(
+                        f"['{conn_info.conn_name}']: Custom DNS name "
+                        f"'{conn_info.conn_name.domain_name}' resolved to '{ips}', "
+                        "using it to connect"
+                    )
+                else:
+                    logger.debug(
+                        f"['{conn_info.conn_name}']: Custom DNS name "
+                        f"'{conn_info.conn_name.domain_name}' resolved but returned no "
+                        f"entries, using '{preferred_ips}' from instance metadata"
+                    )
+                    targets.extend(preferred_ips)
+            except Exception as e:  # noqa: BLE001
+                logger.debug(
+                    f"['{conn_info.conn_name}']: Custom DNS name "
+                    f"'{conn_info.conn_name.domain_name}' did not resolve to an IP "
+                    f"address: {e}, using '{preferred_ips}' from instance metadata"
+                )
+                targets.extend(preferred_ips)
+        else:
+            targets.extend(preferred_ips)
+        return targets
+
+    async def _dial_probe_connection(
+        self,
+        conn_info: ConnectionInfo,
+        enable_iam_auth: bool,
+        ip_type: IPTypes | None = None,
+    ) -> tuple[asyncio.StreamReader, asyncio.StreamWriter]:
+        """Dials a TLS probe connection using the connector's IP resolution and SSLContext."""
+        effective_ip_type = ip_type if ip_type is not None else self._ip_type
+        preferred_ips = conn_info.get_preferred_ips(effective_ip_type)
+        targets = await self._resolve_targets(conn_info, preferred_ips)
+
+        if not targets:
+            raise ConnectionError(
+                f"No target IP addresses found for {conn_info.conn_name}"
+            )
+
+        ssl_context = await conn_info.create_ssl_context(enable_iam_auth)
+        server_hostname = (
+            conn_info.conn_name.domain_name
+            if conn_info.conn_name.domain_name
+            else None
+        )
+
+        last_err: Exception | None = None
+        for target in targets:
+            try:
+                reader, writer = await asyncio.wait_for(
+                    asyncio.open_connection(
+                        host=target,
+                        port=SERVER_PROXY_PORT,
+                        ssl=ssl_context,
+                        server_hostname=server_hostname,
+                    ),
+                    timeout=float(max(1, self._timeout)),
+                )
+                return reader, writer
+            except Exception as e:  # noqa: BLE001
+                last_err = e
+        if last_err:
+            raise last_err
+        raise ConnectionError(
+            f"Failed to connect to any target for {conn_info.conn_name}"
+        )
+
     def __enter__(self) -> Any:
         """Enter context manager by returning Connector object"""
         return self