libcurl CURLOPT_TLSAUTH_PASSWORD 详解：TLS-SRP 认证密码选项、参数语义与 8.22.0 弃用现状
【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl
导读
CURLOPT_TLSAUTH_PASSWORD是 libcurl 中用于设置 TLS 认证密码（TLS-SRP 共享密钥）的易用接口选项，与CURLOPT_TLSAUTH_TYPE、CURLOPT_TLSAUTH_USERNAME三者配合构成完整的 TLS-SRP 认证配置。本文以 libcurl 官方选项文档（docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md）为骨架，结合当前仓库的头文件声明、setopt 实现与命令行等价参数，完整讲解该选项的用法、参数语义，并说明其在 8.22.0 版本被正式弃用的原因与现状。读完本文，你将能准确判断旧代码中该选项的实际行为，并为遗留项目制定正确的替换方案。
选项总览：签名与基本信息
CURLOPT_TLSAUTH_PASSWORD用于为 TLS 认证方法提供密码字符串。其原型与官方文档一致：
#include <curl/curl.h> CURLcode curl_easy_setopt(CURL *handle, CURLOPT_TLSAUTH_PASSWORD, char *pwd);- 引入版本：7.21.4
- 适用协议：TLS（即所有基于 TLS 的安全协议）
- TLS 后端：OpenSSL、GnuTLS
- 默认值：NULL（未设置任何密码）
- 参数类型：
CURLOPTTYPE_STRINGPOINT（字符串指针），在 include/curl/curl.h 中以CURLOPTDEPRECATED(CURLOPT_TLSAUTH_PASSWORD, CURLOPTTYPE_STRINGPOINT, 205, 8.22.0, "Support was removed")形式声明。
该选项需要与CURLOPT_TLSAUTH_TYPE（认证方法）和CURLOPT_TLSAUTH_USERNAME（用户名）组合使用，单独设置密码不会产生任何认证效果。
功能说明：它到底做什么
按官方文档 docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md 的说明：
- 传入一个指向以
\0结尾的密码字符串的char *指针，该密码将用于CURLOPT_TLSAUTH_TYPE指定的 TLS 认证方法； - 前置条件：必须同时设置
CURLOPT_TLSAUTH_USERNAME； - 字符串生命周期：libcurl 会复制该字符串，应用程序在设置此选项后无需保留原字符串；
- 重复设置语义：多次调用时，最后一次设置的字符串覆盖之前的值；
- 重置方式：传入
NULL可再次禁用该选项。
从本质上讲，这一组选项对应的是TLS-SRP（Secure Remote Password）认证——一种基于共享密钥的双向（mutual）认证机制，定义于 RFC 5054。其设计意图是：在客户端与服务端共享同一个"用户名 + 密码"秘密的前提下，即使不依赖传统 CA 证书链，也能完成双方身份的相互验证。相关配套选项说明见 CURLOPT_TLSAUTH_TYPE 与 CURLOPT_TLSAUTH_USERNAME。
一个必须注意的限制：TLS 1.3 不兼容
官方文档明确强调：TLS-SRP 无法在 TLS 1.3 下工作。由于现代服务端普遍启用 TLS 1.3，这成为该认证方式难以落地的主要障碍，也是其最终走向废弃的重要原因之一。如果你的服务端强制使用 TLS 1.3，那么即便设置了这一组选项，TLS-SRP 握手也无法完成。
参数语义详解：生命周期、覆盖与重置
CURLOPT_TLSAUTH_PASSWORD虽是简单字符串选项，但其参数语义有几点值得在实际编码中注意：
| 语义维度 | 行为 | 依据 |
|---|---|---|
| 字符串所有权 | libcurl 内部复制，应用可立即释放或复用缓冲区 | 官方 DESCRIPTION |
| 多次设置 | 后设置的值覆盖先前的值 | 官方 DESCRIPTION |
| 重置 | 传入NULL恢复默认（未设置）状态 | 官方 DESCRIPTION |
| 默认值 | NULL | 官方 DEFAULT 章节 |
| 前置依赖 | 需同时设置CURLOPT_TLSAUTH_USERNAME | 官方 DESCRIPTION |
由于该选项在当前的 libcurl 实现中已不再被真正处理（见下文"源码现状"），这些语义目前更多是历史行为的记录；但在使用 8.22.0 之前的 libcurl 版本维护遗留代码时，上述语义依然适用。
完整代码示例：SRP 认证的标准用法
官方示例展示了这三个选项的典型组合用法。下面在原文基础上补充了错误处理与注释，使其更贴近生产代码：
#include <curl/curl.h> int main(void) { CURL *curl = curl_easy_init(); if(curl) { CURLcode result; /* 目标资源 */ curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); /* 指定 TLS 认证方法为 SRP */ curl_easy_setopt(curl, CURLOPT_TLSAUTH_TYPE, "SRP"); /* TLS-SRP 用户名（与服务端共享的标识） */ curl_easy_setopt(curl, CURLOPT_TLSAUTH_USERNAME, "user"); /* TLS-SRP 密码（与服务端共享的秘密） */ curl_easy_setopt(curl, CURLOPT_TLSAUTH_PASSWORD, "secret"); result = curl_easy_perform(curl); /* 检查执行结果：CURLE_OK 表示成功，非零为错误码 */ if(result != CURLE_OK) fprintf(stderr, "curl_easy_perform() failed: %s\n", curl_easy_strerror(result)); curl_easy_cleanup(curl); } return 0; }要点说明：
- 三选项缺一不可：
TLSAUTH_TYPE决定认证方法（当前仅支持"SRP"），TLSAUTH_USERNAME与TLSAUTH_PASSWORD提供共享凭证； CURLOPT_TLSAUTH_TYPE的默认值为空字符串（blank），未显式设置时认证不会生效；- 返回值：
curl_easy_setopt(3)返回CURLcode，CURLE_OK (0)表示设置成功，非零表示发生错误，具体错误码含义参见 libcurl-errors(3)。
源码现状：选项在 8.22.0 后已"名存实亡"
从当前仓库源码可以确认，这一组 TLS-SRP 选项虽然仍保留在 API 中（以保证二进制兼容与编译通过），但其实际处理逻辑已被移除。
setopt 实现：直接返回"未内置"
在 lib/setopt.c 中，六个相关选项被统一归入一个分支：
case CURLOPT_TLSAUTH_USERNAME: case CURLOPT_TLSAUTH_PASSWORD: case CURLOPT_TLSAUTH_TYPE: case CURLOPT_PROXY_TLSAUTH_USERNAME: case CURLOPT_PROXY_TLSAUTH_PASSWORD: case CURLOPT_PROXY_TLSAUTH_TYPE: return CURLE_NOT_BUILT_IN;也就是说，调用curl_easy_setopt(handle, CURLOPT_TLSAUTH_PASSWORD, ...)会立即返回CURLE_NOT_BUILT_IN（功能未构建/已被移除），而非像过去那样把密码保存进 easy handle。这与官方文档开篇那句 "Deprecated option. It serves no purpose anymore."（已废弃，不再有任何用途）完全吻合。
头文件声明：显式标记 deprecated
在 include/curl/curl.h 中，三个选项通过CURLOPTDEPRECATED宏声明，宏定义于 include/curl/curl.h，其效果是为该枚举值附加CURL_DEPRECATED(8.22.0, "Support was removed")属性：
/* Set a username for authenticated TLS */ CURLOPTDEPRECATED(CURLOPT_TLSAUTH_USERNAME, CURLOPTTYPE_STRINGPOINT, 204, 8.22.0, "Support was removed"), /* Set a password for authenticated TLS */ CURLOPTDEPRECATED(CURLOPT_TLSAUTH_PASSWORD, CURLOPTTYPE_STRINGPOINT, 205, 8.22.0, "Support was removed"), /* Set authentication type for authenticated TLS */ CURLOPTDEPRECATED(CURLOPT_TLSAUTH_TYPE, CURLOPTTYPE_STRINGPOINT, 206, 8.22.0, "Support was removed"),这带来两个直接影响：
- 编译期告警：使用支持 GCC/Clang 属性（
__attribute__((deprecated))）的编译器时，引用CURLOPT_TLSAUTH_PASSWORD会触发 deprecation 警告，提醒开发者及时迁移； - 枚举号保留：选项编号 204/205/206 仍被占用，避免历史二进制程序中的数值语义漂移。
选项注册表：仍以字符串类型登记
在 lib/easyoptions.c 中，选项仍登记为字符串类型：
{ "TLSAUTH_PASSWORD", CURLOPT_TLSAUTH_PASSWORD, CURLOT_STRING, 0 }, { "TLSAUTH_TYPE", CURLOPT_TLSAUTH_TYPE, CURLOT_STRING, 0 }, { "TLSAUTH_USERNAME", CURLOPT_TLSAUTH_USERNAME, CURLOT_STRING, 0 },这条注册表用于curl_easy_option_by_name()等选项自省 API。开发者仍能通过名称查询到这些选项及其参数类型，但它们已无法产生实际认证效果。
关于代理侧变体
除直接面向连接的 TLS 认证外，libcurl 还曾提供对应的代理侧选项CURLOPT_PROXY_TLSAUTH_PASSWORD、CURLOPT_PROXY_TLSAUTH_TYPE、CURLOPT_PROXY_TLSAUTH_USERNAME，用于在 HTTPS 代理（CONNECT 隧道）场景下对代理进行 TLS-SRP 认证。在 lib/setopt.c 中它们与直连版本一同返回CURLE_NOT_BUILT_IN，同样已被移除。
命令行对应参数：--tlspassword 一族
命令行工具 curl 曾提供与之对应的三个参数，相关文档见：
- docs/cmdline-opts/tlspassword.md：
--tlspassword <password>，TLS 认证密码，要求同时设置--tlsuser； - docs/cmdline-opts/tlsuser.md：
--tlsuser <user>，TLS 认证用户名，要求同时设置--tlspassword； - docs/cmdline-opts/tlsauthtype.md：
--tlsauthtype <type>，TLS 认证方法；文档说明当该参数未显式给出而--tlsuser已被设置时，默认取值为SRP； - 代理侧对应：
--proxy-tlspassword、--proxy-tlsuser、--proxy-tlsauthtype（见 docs/cmdline-opts/proxy-tlsauthtype.md，等效于--tlsauthtype但用于 HTTPS 代理上下文）。
历史用法示例（与 libcurl 选项一一对应）：
curl --tlspassword secret --tlsuser user --tlsauthtype SRP https://example.com/需要说明的是，随着 libcurl 移除该功能，命令行侧的这些参数在当前仓库版本中同样不再具备实际认证作用，遗留脚本依赖它们时需评估替代认证方案。
弃用时间线与迁移建议
- 7.21.4：该选项随 TLS-SRP 支持一同引入；
- 8.22.0：官方正式弃用，
CURLOPTDEPRECATED声明注明 "Support was removed"，curl_easy_setopt对相关选项返回CURLE_NOT_BUILT_IN； - 弃用原因：TLS-SRP 与 TLS 1.3 不兼容，在现代 TLS 生态中无法继续发挥作用，故移除实际实现。
迁移建议：
- 若你的服务端仅依赖 TLS-SRP 做双向认证，需改用 TLS 1.3 兼容的认证机制，例如基于证书的 mTLS（配合
CURLOPT_SSLKEY/CURLOPT_SSLCERT等选项）、客户端证书认证，或应用层的认证协议（如 HTTP 层的 Digest/Bearer 等）； - 升级 libcurl 到 8.22.0 及以上后，代码中残留的
CURLOPT_TLSAUTH_*调用应删除或改为条件编译（#if LIBCURL_VERSION_NUM < 0x081600），以消除编译期 deprecated 告警； - 涉及
CURLE_NOT_BUILT_IN返回码时，参考 libcurl-errors(3) 中该错误码的说明，将其视为"功能不可用"而非请求失败。
返回值说明
curl_easy_setopt()返回CURLcode：
CURLE_OK (0)：设置成功（在 8.22.0 之前的版本中表示字符串已合法接收并保存）；- 非零：发生错误。在当前版本中，
CURLOPT_TLSAUTH_PASSWORD等选项固定返回CURLE_NOT_BUILT_IN，详见 libcurl-errors(3)。
相关选项速查
| 选项 | 作用 | 仓库文档 |
|---|---|---|
CURLOPT_TLSAUTH_TYPE | TLS 认证方法（当前仅 "SRP"） | docs/libcurl/opts/CURLOPT_TLSAUTH_TYPE.md |
CURLOPT_TLSAUTH_USERNAME | TLS 认证用户名 | docs/libcurl/opts/CURLOPT_TLSAUTH_USERNAME.md |
CURLOPT_TLSAUTH_PASSWORD | TLS 认证密码（本文主题） | docs/libcurl/opts/CURLOPT_TLSAUTH_PASSWORD.md |
CURLOPT_PROXY_TLSAUTH_* | HTTPS 代理侧的同一组认证参数 | 源码实现见 lib/setopt.c |
总结
CURLOPT_TLSAUTH_PASSWORD是 libcurl 历史上用于 TLS-SRP 共享密钥认证的密码选项，自 7.21.4 引入，需要与CURLOPT_TLSAUTH_TYPE、CURLOPT_TLSAUTH_USERNAME配套使用，且与 TLS 1.3 不兼容。从 8.22.0 起该功能已被正式移除：头文件以CURLOPTDEPRECATED标记弃用，lib/setopt.c 中对相关选项直接返回CURLE_NOT_BUILT_IN。理解这一演进脉络，有助于遗留代码的平滑迁移，并避免在新项目中误用这套已失效的认证接口。
【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
