iTranslated by AI
How to Fix GitHub SSL Errors Securely Without Disabling http.sslVerify
Introduction
Depending on the security software installed on your work PC, the SSL inspection feature may cause the following error when executing commands such as git fetch.
$ git fetch
fatal unable to access "URL": SSL peer certificate or SSH remote key was not OK
On the internet, the following workaround is often introduced:
# Disable server certificate verification for HTTPS communication
git config --global http.sslVerify false
However, this method increases the risk of man-in-the-middle attacks. There is no need to intentionally create a vulnerability. Additionally, it may violate your company's security policy.
In the case of errors caused by the SSL inspection feature, it is possible to establish a connection while keeping server certificate verification enabled.
In this article, I will introduce a workaround using a work PC (Windows 11) with the security software Zscaler installed as an example.
About SSL Inspection Functionality
# Normal
PC → GitHub Server
# With SSL inspection
PC → Zscaler → GitHub Server
The official explanation from Zscaler is easy to understand, so I will quote it here:
SSL inspection is the process of intercepting and inspecting SSL-encrypted internet communication between a client and a server. While the majority of internet traffic is SSL-encrypted, it can also contain malicious content, making SSL traffic inspection extremely important.
In some applications like git, when Zscaler intercepts the communication, certificate verification fails, resulting in an error.
(Supplement) Regarding Other Security Software
There are other security software programs besides Zscaler that have SSL inspection features.
Since I do not have a verification environment at hand, I will omit them in this article, but the workaround for Zscaler might be applicable.
Investigating the Cause of the SSL Error
You can check the communication status when connecting to GitHub with the following command.
$ openssl s_client -crlf -connect www.github.com:443
CONNECTED(00000003)
depth=2 C = US, ST = New Jersey, L = Jersey City, O = The USERTRUST Network, CN = USERTrust ECC Certification Authority
verify return:1
depth=1 C = GB, ST = Greater Manchester, L = Salford, O = Sectigo Limited, CN = Sectigo ECC Domain Validation Secure Server CA
verify return:1
depth=0 CN = github.com
verify return:1
---
# Omitted
The above shows the results without SSL inspection.
The parts labeled depth=2, depth=1, and depth=0 indicate the hierarchical structure of the SSL server certificate.
The reliability (lack of tampering) of the GitHub.com server certificate is verified through the following flow:
GitHub.com server certificate (depth=0)
↑ Issued/Signed
Intermediate certificate (Sectigo ECC Domain Validation Secure Server CA) (depth=1)
↑ Issued/Signed
Root certificate (USERTrust ECC Certification Authority) (depth=2)
When Zscaler SSL inspection is enabled, an error occurs because the system cannot properly retrieve the Zscaler root certificate (depth=2) during GitHub server certificate verification.
depth=2 <omitted> CN = Zscaler Intermediate Root CA
verify error:num=20:unable to get local issuer certificate
verify return:1
Zscaler's official documentation states that this issue occurs with certain applications like git.
Some applications maintain custom trust stores instead of using the default system trust store. As a result, the application cannot verify the Zscaler-generated server certificate, and the TLS connection fails. In such cases, the user must manually add the custom root certificate authority (CA) to the custom trust store or disable server certificate verification.
The following resources were helpful regarding how server certificates work.
Solution
Workflow
- Export the Zscaler root certificate registered on the PC
- Register the certificate path in git config
- Done!
The steps are based on the following:
Exporting the Root Certificate
Run certmgr.
start certmgr.msc
Open Trusted Root Certification Authorities > Certificates.
Find a certificate whose issuer includes the name "Zscaler", right-click > All Tasks > Export.
Pressing Next will bring you to the screen for selecting the file format to export.
Select Base 64 encoded X.509 (.CER).
Specify any folder as the save destination.
The filename seems flexible. I named it ZscalerRootCA.cer.
Registering the certificate path in git config
Move the exported certificate to any directory.
Following Zscaler's official explanation, I will save it to C:\Users\<username>\AppData\Roaming this time.
Use the following command to allow git to reference the prepared certificate:
git config --global http.sslcainfo C:\Users\<username>\AppData\Roaming\ZscalerRootCA.cer
The setup is now complete.
Conclusion
Do not simply set git config --global http.sslVerify false.
By examining the cause of the error and configuring appropriate settings, you can resolve the issue while maintaining security.
Do not simply set git config --global http.sslVerify false.
Discussion