SSL 证书检测 API

POST /api/v2/tls/check，请求头需带 Content-Type: application/json

与目标完成一次真实的 TLS 握手，返回证书与连接详情。只做握手，不发送 HTTP 请求，也不下载页面内容。接口地址、响应格式与限流为各接口通用，见 API 文档。

参数	说明
host	域名或 IP 字面量（IPv4，或带不带方括号的 IPv6），必填。传主机名而不是 URL：请先去掉协议、路径与查询。Unicode 域名会转换为 punycode。
port	TCP 端口，1–65535，默认 443。

域名会通过 A 与 AAAA 查询解析（IPv4 优先）。最多尝试两个可连接地址，共享 8 秒总预算；单次握手超时 5 秒，DNS 解析超时 3 秒。内网、环回、链路本地与保留地址一律不探测。IP 目标直接连接。

即使证书无效也会完成握手，因此请求成功只代表 TLS 已建立；证书结论看 validation。

示例：

curl -X POST "https://tcp.lc/api/v2/tls/check" \
  -H "Content-Type: application/json" \
  -d '{"host":"example.com","port":443}'

响应 data 字段：

字段	说明
host	归一化后的检测目标：域名（IDN 为 punycode）或 IP 字面量。
targetType	domain 或 ip。
port	实际检测的端口。
ip	实际完成握手的地址。
addresses	解析出的可连接地址，IPv4 在前；已过滤内网与保留地址。IP 目标时为该 IP 本身。
elapsed	服务端完成整次检测的耗时（毫秒）。
connection	协商出的 TLS 连接信息，见下表。
certificate	证书详情，见下表。
validation	证书校验结论，见下表。

connection 字段：

字段	说明
version	协商出的 TLS 版本，如 TLSv1.3、TLSv1.2。
cipher	协商出的加密套件，如 TLS_AES_128_GCM_SHA256。
forwardSecrecy	是否具备前向保密（TLS 1.3 全部套件，或更低版本使用 ECDHE/DHE）。
alpn	ALPN 协商结果（h2 或 http/1.1）；服务器未响应 ALPN 时为 null。
http2	ALPN 协商为 h2 时为 true。

certificate 字段：

字段	说明
subject	证书主体，单行 RDN 串，通常以 CN= 开头。
issuer	签发机构，同样是 RDN 串。
validFrom	生效时间，ISO 8601。
validTo	到期时间，ISO 8601。
daysRemaining	距到期的剩余天数（向下取整）；已过期时为负值。
san	主题备用名称中的 DNS 名，保留通配符原样。
publicKeyAlgorithm	RSA、RSA-PSS、ECDSA、Ed25519、Ed448 或 DSA。
publicKeyBits	密钥位数，如 2048、256；未知时为 null。
publicKeyCurve	EC 证书的曲线名，如 prime256v1；其它类型为 null。

validation 字段：

字段	说明
valid	签发链受信任、证书在有效期内且与主机名匹配时为 true。
issues	校验问题类别；valid 为 true 时为空。
errorCode	原始 OpenSSL/Node 错误码，如 CERT_HAS_EXPIRED，便于排查；有效时为 null。

issues 取值：

值	含义
expired	证书已过期。
notYetValid	证书尚未生效。
hostname	证书与请求的主机名不匹配。
selfSigned	证书为自签名。
untrusted	证书链不受信任，例如缺少中间证书或签发机构未知。
unknown	其它校验失败原因。

示例：

{
  "code": 200,
  "msg": "ok",
  "data": {
    "host": "example.com",
    "targetType": "domain",
    "port": 443,
    "ip": "93.184.215.14",
    "addresses": ["93.184.215.14", "2606:2800:21f:cb07:6820:80da:af6b:8b2c"],
    "elapsed": 182,
    "connection": {
      "version": "TLSv1.3",
      "cipher": "TLS_AES_128_GCM_SHA256",
      "forwardSecrecy": true,
      "alpn": "http/1.1",
      "http2": false
    },
    "certificate": {
      "subject": "CN=example.com",
      "issuer": "C=US, O=DigiCert Inc, CN=DigiCert TLS RSA SHA256 2020 CA1",
      "validFrom": "2026-01-01T00:00:00.000Z",
      "validTo": "2027-01-01T23:59:59.000Z",
      "daysRemaining": 74,
      "san": ["example.com", "www.example.com"],
      "publicKeyAlgorithm": "RSA",
      "publicKeyBits": 2048,
      "publicKeyCurve": null
    },
    "validation": {
      "valid": true,
      "issues": [],
      "errorCode": null
    }
  }
}

证书无效不算接口错误：仍返回 code: 200，结论在 validation 中。这里只展示该对象：

{
  "code": 200,
  "msg": "ok",
  "data": {
    "validation": {
      "valid": false,
      "issues": ["expired"],
      "errorCode": "CERT_HAS_EXPIRED"
    }
  }
}

错误

失败时 code 为 -1000，msg 为稳定标识，data.args 可能携带细节。

msg	含义
api.param.host.invalid	缺少 host，或无法解析为域名/IP 字面量；data.args.host 为原始输入。
api.param.port.invalid	端口不是 1-65535 的整数；data.args.port 为原始输入。
api.param.host.private	解析出的地址全部为内网或保留地址，无法探测。
api.notfound.domain	域名不存在（NXDOMAIN）；data.args.name 为域名。
api.notfound.address	域名没有 A 或 AAAA 记录；data.args.name 为域名。
api.upstream.timeout	DNS 解析超时。
api.upstream.error	DNS 解析因其它原因失败。
api.upstream.tls.timeout	TLS 握手超时。
api.upstream.tls.refused	连接被拒绝——端口没有服务监听，或未启用 TLS。
api.upstream.tls.handshake	TLS 握手失败；站点可能不支持 HTTPS，或其 TLS 配置与检测端不兼容。
api.upstream.tls.error	握手因其它网络原因失败。
api.rate.limitedDaily	今日配额已用完，响应带 Retry-After 头。
api.server.internal	服务端或配置异常。

示例：

{
  "code": -1000,
  "msg": "api.param.host.private",
  "data": null
}

说明

• IP 目标会跳过主机名匹配，因为证书 SAN 中可能不包含 IP；有效期与证书链信任仍会校验。
• 在 CDN 或拥有多个地址的域名后面，不同边缘节点可能返回不同证书；ip 为实际连接的地址。
• validation 覆盖证书链信任、有效期与主机名匹配，不检查吊销状态（CRL/OCSP）。
• 只进行 TLS 握手，服务端不会发送 HTTP 请求。

限流与缓存

按客户端 IP 限流：每分钟 10 次、每天 100 次；所有请求（包括失败的请求）均计入。每日额度按 UTC+8 零点重置。分钟额度用完时返回 api.rate.limited，每日额度用完时返回 api.rate.limitedDaily，均带 Retry-After 响应头（秒）。

成功响应带 Cache-Control: public, max-age=300, s-maxage=600；错误响应带 Cache-Control: no-store。