grpc tls_error ai_generated true

UNAVAILABLE: SSL target name override mismatch: expected 'service.example.com' but got 'backend.internal'

ID: grpc/ssl-target-name-override-mismatch

Also available as: JSON · Markdown · 中文
87%Fix Rate
86%Confidence
1Evidence
2024-05-08First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
gRPC v1.61.0 active — — —
gRPC-Go v1.63.0 active — — —
OpenSSL 1.1.1w active — — —

Root Cause

gRPC client SSL/TLS target name override (via 'grpc.ssl_target_name_override') doesn't match the server's TLS certificate Common Name (CN) or Subject Alternative Name (SAN), causing handshake failure.

generic

中文

gRPC客户端SSL/TLS目标名称覆盖（通过'grpc.ssl_target_name_override'）与服务器TLS证书的通用名称（CN）或主题备用名称（SAN）不匹配，导致握手失败。

Official Documentation

https://grpc.io/docs/guides/auth/#ssl-tls

Workarounds

  1. 95% success Update the client's SSL target name override: set 'grpc.ssl_target_name_override' to the exact CN/SAN in the server certificate (e.g., 'backend.internal'); in Python: 'grpc.secure_channel(target, credentials, options=[("grpc.ssl_target_name_override", "backend.internal")])'. 
    Update the client's SSL target name override: set 'grpc.ssl_target_name_override' to the exact CN/SAN in the server certificate (e.g., 'backend.internal'); in Python: 'grpc.secure_channel(target, credentials, options=[("grpc.ssl_target_name_override", "backend.internal")])'.
  2. 85% success Regenerate the server TLS certificate with the correct SAN: include both 'service.example.com' and 'backend.internal' in the Subject Alternative Names to match the client override; restart the server to load the new certificate. 
    Regenerate the server TLS certificate with the correct SAN: include both 'service.example.com' and 'backend.internal' in the Subject Alternative Names to match the client override; restart the server to load the new certificate.
  3. 90% success Remove the override entirely: if the client target URL matches the certificate's CN/SAN, omit 'grpc.ssl_target_name_override' to use automatic hostname verification; ensure DNS resolves correctly. 
    Remove the override entirely: if the client target URL matches the certificate's CN/SAN, omit 'grpc.ssl_target_name_override' to use automatic hostname verification; ensure DNS resolves correctly.

中文步骤

  1. 更新客户端的SSL目标名称覆盖：将'grpc.ssl_target_name_override'设置为服务器证书中的确切CN/SAN（如'backend.internal'）；在Python中：'grpc.secure_channel(target, credentials, options=[("grpc.ssl_target_name_override", "backend.internal")])'。
  2. 使用正确的SAN重新生成服务器TLS证书：在主题备用名称中包含'service.example.com'和'backend.internal'以匹配客户端覆盖；重启服务器以加载新证书。
  3. 完全移除覆盖：如果客户端目标URL与证书的CN/SAN匹配，省略'grpc.ssl_target_name_override'以使用自动主机名验证；确保DNS正确解析。

Dead Ends

Common approaches that don't work:

  1. 80% fail

    Disabling SSL verification entirely ('grpc.ssl_target_name_override='') exposes the connection to man-in-the-middle attacks and may not resolve if the server enforces TLS.

  2. 85% fail

    Changing the server's hostname in the client target URL without updating the override value causes a different mismatch; the error persists if the override still points to the old name.

  3. 90% fail

    Regenerating the server certificate with the same mismatched name doesn't fix the client-side override; the client must be updated to match the new certificate name.