Resolving SSL Certificate Issues with Git on Windows

Understanding SSL Certificates and Git on Windows

When working with Git repositories over HTTPS, you might encounter errors related to SSL (Secure Sockets Layer) certificates. These errors typically manifest as “unable to get local issuer certificate” messages and indicate that your Git installation cannot verify the authenticity of the server’s SSL certificate. This is a common issue, especially when dealing with self-signed certificates or internal Certificate Authorities (CAs). This tutorial explains the root causes of these errors and provides solutions for resolving them on Windows.

Why Does This Happen?

Git relies on a Certificate Authority (CA) bundle – a file containing a list of trusted root certificates. When connecting to a server over HTTPS, Git checks if the server’s certificate is signed by a CA listed in this bundle. If the CA isn’t found or the certificate chain is incomplete, Git flags the connection as insecure.

Several scenarios can lead to this issue:

• Self-Signed Certificates: These certificates are not issued by a trusted public CA. They’re often used in development or internal environments, but Git won’t automatically trust them.
• Internal Certificate Authorities: Organizations sometimes have their own internal CAs to issue certificates. These CAs are not included in the default Git CA bundle.
• Missing Intermediate Certificates: A certificate chain might consist of multiple certificates – the server certificate, an intermediate certificate, and a root certificate. If any of these certificates are missing, verification will fail.
• Incorrect Backend: Git for Windows historically defaulted to a crypto backend that didn’t integrate well with the Windows certificate store.

Solutions

Here are several approaches to resolve SSL certificate issues with Git on Windows, ordered from the most recommended to less desirable (due to security implications).

1. Using the Windows SChannel Backend (Recommended)

Git for Windows version 2.14 and later allows you to configure it to use the Windows SChannel crypto backend. This backend leverages the Windows certificate store, automatically trusting certificates that are installed and considered valid by the operating system.

To enable SChannel:

git config --global http.sslbackend schannel

This is the simplest and most secure solution if you’ve already installed the necessary certificates in the Windows certificate store. After running this command, try cloning or pulling from the repository again.

2. Updating the Git CA Bundle with Your Certificate

If using SChannel doesn’t solve the problem, or you’re using an older version of Git for Windows, you can manually update the Git CA bundle with your self-signed or internal CA certificate.

• Obtain the Certificate: Export the certificate from your browser (usually by navigating to the certificate details and selecting "Export"). Ensure it’s in PEM format (a text-based format with a specific header/footer).
• Locate the CA Bundle: The CA bundle is typically located at Git\bin\curl-ca-bundle.crt within your Git installation directory.
• Append the Certificate: Open curl-ca-bundle.crt in a text editor and append the contents of your certificate file to the end. Important: Do not overwrite the existing contents. Be careful with line endings; ensure the file uses Unix-style line endings (LF) rather than Windows-style (CRLF).
• Test: Try cloning or pulling from the repository again.

3. Specifying the CA Bundle (Alternative)

If you don’t want to modify the default curl-ca-bundle.crt file, you can specify a custom CA bundle using the http.sslCAinfo configuration option:

git config --global http.sslCAinfo /path/to/your/custom/ca-bundle.crt

Replace /path/to/your/custom/ca-bundle.crt with the actual path to your custom bundle file.

4. Disabling SSL Verification (Not Recommended)

As a last resort, you can disable SSL verification entirely. This is strongly discouraged because it makes your connection vulnerable to man-in-the-middle attacks. Use this only for temporary testing or in controlled environments where security is not a primary concern.

git config --global http.sslVerify false

Remember to re-enable SSL verification as soon as possible:

git config --global http.sslVerify true

Troubleshooting

• Line Endings: Ensure your CA bundle file uses Unix-style line endings (LF). Windows-style line endings (CRLF) can cause issues.
• Certificate Format: The certificate must be in PEM format.
• Certificate Chain: If the certificate requires an intermediate certificate, include it in the bundle before the server certificate. The order matters.
• Permissions: Ensure Git has read access to the CA bundle file.
• Restart Git: Sometimes, changes to the configuration or CA bundle require restarting Git or your terminal session to take effect.

By following these steps, you should be able to resolve SSL certificate issues and successfully interact with HTTPS Git repositories on Windows. Prioritize security by using the recommended solutions and avoiding disabling SSL verification unless absolutely necessary.