Python ssl.SSLContext 怎样限制允许的 TLS 版本

如果 Python 客户端必须只使用 TLS 1.2 和 TLS 1.3，不要把协议版本写成某个已经过时的固定协议常量。更稳妥的做法是先创建 ssl.SSLContext，再设置 minimum_version 与 maximum_version，让上下文负责协商范围。

官方文档：https://docs.python.org/3/library/ssl.html

推荐的基本写法是：使用 ssl.create_default_context() 保留客户端证书校验和主机名校验，再把最低版本设为 TLSVersion.TLSv1_2。如果业务确实要把最高版本也锁定为 TLS 1.3，再设置 maximum_version。上下限只是允许范围，最终能否握手还取决于本机 OpenSSL、对端能力和证书验证条件。

SSLContext 解决的是哪一层问题

SSLContext 是 TLS 连接的配置容器，负责保存协议版本、证书验证、主机名检查以及其他连接策略。它不是一次连接本身；客户端套接字通过 context.wrap_socket() 使用这些设置。

因此，版本限制应该放在创建连接之前完成，并且尽量复用已经配置好的上下文。文章只讨论协议版本范围，不展开证书签发、密码套件设计或服务端证书部署。

从职责上看，可以把它拆成三块：

• 创建方式：PROTOCOL_TLS_CLIENT 或 create_default_context()。
• 版本范围：minimum_version 决定下限，maximum_version 决定上限。
• 安全校验：客户端上下文还要负责证书链和主机名检查。

用 minimum_version 和 maximum_version 限制协议范围

下面的配置允许 TLS 1.2 和 TLS 1.3。代码没有关闭证书验证，也没有把连接降级到旧版协议：

import ssl


def build_tls_context() -> ssl.SSLContext:
    # 默认客户端上下文会启用证书校验和主机名校验。
    context = ssl.create_default_context()

    # 最低版本限制为 TLS 1.2，排除更旧的协议版本。
    context.minimum_version = ssl.TLSVersion.TLSv1_2

    # 最高版本限制为 TLS 1.3；本机不支持时，握手不会凭空获得该能力。
    context.maximum_version = ssl.TLSVersion.TLSv1_3
    return context


tls_context = build_tls_context()
print(tls_context.minimum_version, tls_context.maximum_version)

这里的两个属性表达的是“允许集合”的边界，而不是强制每次连接都使用最高版本。对端只支持 TLS 1.2 时，范围内仍然可以协商到 TLS 1.2；如果对端只支持 TLS 1.1，则双方没有交集，连接会失败。

默认客户端上下文为什么值得保留

直接写 SSLContext(PROTOCOL_TLS_CLIENT) 也可以创建客户端上下文，但使用 create_default_context() 更适合作为常规客户端的起点。它会加载系统默认信任配置，并启用客户端需要的证书验证和主机名检查。

如果必须从协议常量开始创建，也要明确保留校验职责：

import ssl


def build_explicit_client_context() -> ssl.SSLContext:
    # 显式指定客户端协议，避免使用已弃用的版本专用常量。
    context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)

    # 客户端模式默认要求证书和主机名校验；不要为了兼容随意关闭它们。
    context.verify_mode = ssl.CERT_REQUIRED
    context.check_hostname = True
    context.load_default_certs()

    # 只收窄协议范围，其他安全策略继续交给上下文管理。
    context.minimum_version = ssl.TLSVersion.TLSv1_2
    context.maximum_version = ssl.TLSVersion.TLSv1_3
    return context

除非有明确的信任库来源，否则不要把 check_hostname 改成 False，也不要把 verify_mode 改成 CERT_NONE 来掩盖握手失败。协议版本协商成功，不等于对端身份已经通过验证。

三类失败现象不要混在一起

配置完成后，排查握手失败时先按责任边界分类，而不是一看到 SSLError 就关闭验证。

代码层面可以先保留异常原文，区分协议协商和认证阶段的线索：

import ssl


def connect_with_context(context: ssl.SSLContext, sock, host: str):
    try:
        # server_hostname 让客户端上下文能够执行主机名校验。
        tls_sock = context.wrap_socket(sock, server_hostname=host)
        # 连接动作仍由调用方负责；这里返回已经套上 TLS 策略的套接字。
        return tls_sock
    except ssl.SSLError as exc:
        # 保留 library、reason 和文字信息，便于区分协议与证书问题。
        details = {"library": exc.library, "reason": exc.reason, "message": str(exc)}
        raise RuntimeError(f"TLS 握手失败：{details}") from exc

这个示例不伪造运行输出。实际错误名称会受到 Python、OpenSSL、操作系统和对端实现影响，排查时应以异常对象提供的字段和日志为准。

上下限应该怎样选

如果目标是现代客户端，常见的保守选择是最低 TLS 1.2、最高版本保持为 MAXIMUM_SUPPORTED，这样可以获得新版本能力，同时不把未来新增版本提前写死。只有在协议合规、对端联调或回归测试要求固定版本时，才把最高版本也设置为 TLS 1.2 或 TLS 1.3。

注意，设置了版本范围后，还要检查范围是否有效：最低版本不能高于最高版本，且不能与 SSLContext.options 中排除的版本互相矛盾。Python 文档已经建议使用上下限属性替代旧的 OP_NO_TLS* 方式。

几个容易踩到的配置坑

• 把 TLS 版本专用协议常量当成首选方案：现代代码应使用通用 TLS 客户端或服务端上下文，再配置版本边界。
• 只设置最高版本：如果没有明确的最低版本要求，优先使用安全默认值；如果要建立合规基线，应显式设置最低版本。
• 上下文投入使用后继续改配置：SSLContext 适合在连接前配置完成，连接已经建立后不要在多个线程中随意重配。
• 把证书错误误判为协议错误：先查看异常原因和连接目标，协议版本放行并不会解决不可信证书。

结论

限制 Python 允许的 TLS 版本，核心就是给 SSLContext.minimum_version 和 maximum_version 设定边界。常规客户端可以从 create_default_context() 开始，把最低版本提高到 TLS 1.2，同时保留默认的证书与主机名校验；只有在明确的兼容或合规要求下，才固定最高版本。

当握手失败时，先区分协议范围没有交集、本机 OpenSSL 能力不足和证书校验失败三种责任边界。这样既能收敛兼容性问题，也不会把安全配置当成排障开关。

常见问题

只设置 minimum_version 可以吗？

可以。只设置最低版本时，最高版本通常保持为上下文允许的最大支持版本，适合希望接受新版本协议的现代客户端。

把 maximum_version 设置成 TLS 1.3 就一定使用 TLS 1.3 吗？

不一定。它只是允许范围的上限；如果对端只支持 TLS 1.2，仍可能协商到 TLS 1.2。如果想只允许 TLS 1.3，需要同时把最低版本也设为 TLS 1.3。

为什么不继续使用 OP_NO_TLSv1_2？

版本排除选项表达能力较分散，并且相关 OP_NO_SSL* 与 OP_NO_TLS* 选项已被文档标记为弃用方向。新代码使用上下限属性更直观。

协议版本没问题但仍然握手失败怎么办？

保留 SSLError 的 library、reason 和错误文本，继续检查证书链、主机名、信任库和对端配置。不要直接关闭 CERT_REQUIRED 或 check_hostname。