OpenSSL BIO_do_handshake返回-1无栈错误，如何排查TLS握手问题？

关于BIO_do_handshake的错误栈问题 #

在OpenSSL 1.0.2中，BIO_do_handshake并非所有错误都会写入全局错误栈。尤其是当握手失败源于客户端Client Hello与服务器配置不兼容（比如不支持的协议版本、加密套件、扩展字段）时，往往不会生成对应的ERR错误码，导致ERR_get_error()返回0。这类场景下，错误信息需要从SSL对象本身而非全局错误栈获取。

获取握手问题详细信息的方法 #

1. 关联BIO与SSL对象并获取SSL层错误
   首先从BIO中取出对应的SSL指针：

   SSL *ssl = NULL;
   BIO_get_ssl(bio, &ssl);
   

   然后用SSL_get_error()解析BIO_do_handshake的返回值（-1），这是定位问题的核心：

   int ret = BIO_do_handshake(bio);
   if (ret <= 0) {
       int ssl_err = SSL_get_error(ssl, ret);
       // 根据ssl_err的值判断错误类型
   }
   

   常见的ssl_err取值及含义：

   • SSL_ERROR_WANT_READ/SSL_ERROR_WANT_WRITE：并非真正错误，需要继续调用BIO_do_handshake完成IO操作
   • SSL_ERROR_SSL：SSL层逻辑错误（大概率是Client Hello不兼容）
   • SSL_ERROR_SYSCALL：系统调用层面的错误（比如连接中断）

2. 开启OpenSSL调试日志追踪握手细节
   针对SSL_ERROR_SSL但错误栈为空的情况，直接开启握手消息调试：

   • 在代码中添加调试选项：

     SSL_CTX_set_options(ctx, SSL_OP_DEBUG);
     

     运行程序时会在标准错误输出打印握手阶段的所有消息，包括Client Hello的协议版本、加密套件列表、扩展字段等细节。
   • 或者自定义消息回调函数，精准捕获Client Hello内容：

     void ssl_msg_callback(int write_p, int version, int content_type, const void *buf, size_t len, SSL *ssl, void *arg) {
         if (!write_p && content_type == SSL3_RT_HANDSHAKE) {
             const unsigned char *handshake_buf = (const unsigned char *)buf;
             if (handshake_buf[0] == SSL3_MT_CLIENT_HELLO) {
                 // 解析并打印Client Hello的具体字段
                 printf("Received Client Hello, length: %zu\n", len);
                 // 此处可进一步解析版本、加密套件、扩展等
             }
         }
     }
     // 注册回调
     SSL_CTX_set_msg_callback(ctx, ssl_msg_callback);
     

3. 抓包对比客户端请求与服务器配置
   用tcpdump或Wireshark抓取握手数据包，直接分析Client Hello的以下关键字段：

   • 协议版本（比如TLS 1.0/1.2/1.3）
   • 加密套件列表
   • 扩展字段（如SNI、ALPN、EC曲线、Session Ticket等）
     然后对比服务器端的配置：
   • SSL_CTX_set_cipher_list设置的加密套件是否包含客户端请求的任意一项
   • 通过SSL_OP_NO_TLSv1等选项禁用的协议版本是否与客户端请求冲突
   • 是否开启了客户端请求的扩展支持（比如是否配置了SNI、是否支持对应的EC曲线）

4. 排查IO重试场景
   如果SSL_get_error()返回SSL_ERROR_WANT_READ或SSL_ERROR_WANT_WRITE，不要直接判定为失败，需要在IO就绪后再次调用BIO_do_handshake，直到返回1（握手成功）或其他错误码。

额外提示 #

OpenSSL 1.0.2已于2019年终止维护，存在安全风险，建议尽快升级至受支持的版本（如1.1.1或3.x），新版本的错误处理机制更完善，调试信息也更丰富。

内容的提问来源于stack exchange，提问作者SteveT