dotnet network_error ai_generated true

Grpc.Core.RpcException: Status(StatusCode="Unavailable", Detail="failed to connect to all addresses; last error: UNKNOWN: Failed SSL handshake")

ID: dotnet/grpc-ssl-handshake-failed

Also available as: JSON · Markdown · 中文
82%Fix Rate
87%Confidence
1Evidence
2023-02-15First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
.NET 6.0 active — — —
.NET 7.0 active — — —
.NET 8.0 active — — —
Grpc.Net.Client 2.49 active — — —
Grpc.Net.Client 2.52 active — — —

Root Cause

gRPC client fails SSL/TLS handshake with server due to mismatched protocols, missing or invalid certificates, or server not supporting HTTP/2 over TLS.

generic

中文

gRPC 客户端因协议不匹配、证书缺失或无效、或服务器不支持基于 TLS 的 HTTP/2 而导致 SSL/TLS 握手失败。

Official Documentation

https://learn.microsoft.com/en-us/aspnet/core/grpc/troubleshoot

Workarounds

  1. 85% success Ensure server certificate is trusted by client machine. Install the server's CA certificate using certmgr.msc or update Linux CA store. 
    Ensure server certificate is trusted by client machine. Install the server's CA certificate using certmgr.msc or update Linux CA store.
  2. 80% success Configure gRPC client to use specific TLS version: AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", false); and set HttpClientHandler.SslProtocols = SslProtocols.Tls12; 
    Configure gRPC client to use specific TLS version: AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", false); and set HttpClientHandler.SslProtocols = SslProtocols.Tls12;
  3. 95% success If using .NET Core 3.1+ and server uses self-signed cert, add client code: var handler = new HttpClientHandler(); handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator; (not for production). 
    If using .NET Core 3.1+ and server uses self-signed cert, add client code: var handler = new HttpClientHandler(); handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator; (not for production).

中文步骤

  1. 确保服务器证书被客户端信任。使用 certmgr.msc 或更新 Linux CA 存储安装服务器的 CA 证书。
  2. 配置 gRPC 客户端使用特定 TLS 版本：AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", false); 并设置 HttpClientHandler.SslProtocols = SslProtocols.Tls12;
  3. 如果使用 .NET Core 3.1+ 且服务器使用自签名证书，添加客户端代码：var handler = new HttpClientHandler(); handler.ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator;（不适用于生产环境）。

Dead Ends

Common approaches that don't work:

  1. Disable SSL validation entirely by setting ServicePointManager.ServerCertificateValidationCallback = delegate { return true; } 90% fail

    Disabling SSL validation creates a severe security vulnerability and may not fix protocol-level mismatches like TLS version or cipher suite.

  2. Use HTTP/1.1 instead of HTTP/2 95% fail

    gRPC requires HTTP/2; switching to HTTP/1.1 will cause protocol errors and the gRPC call will fail with a different error.

  3. Set AppContext switch to ignore certificate revocation 85% fail

    Ignoring revocation does not address root cause of handshake failure (e.g., mismatched cipher suites or expired certificate).