Understanding and Resolving SSL Certificate Errors in PHP

When making HTTPS requests in PHP using functions like curl or libraries like Guzzle, you might encounter SSL certificate errors. These errors, often manifesting as “cURL error 60: SSL certificate problem: unable to get local issuer certificate,” indicate that your PHP environment can’t verify the authenticity of the server’s SSL certificate. This tutorial explains the root cause of these errors and provides a comprehensive guide to resolving them.

What Causes SSL Certificate Errors?

SSL/TLS certificates are crucial for securing communication over the internet. Your PHP environment needs to trust the Certificate Authority (CA) that issued the server’s certificate. This trust is established through a list of trusted root certificates stored on your system. When PHP can’t find a valid certificate to verify the server’s certificate chain, it throws an error.

Common causes include:

Missing Root Certificates: The list of trusted root certificates on your system might be outdated or incomplete.
Incorrect Configuration: PHP might not be configured to look in the correct location for these certificates.
Firewall/Proxy Issues: Although less common, network configurations can sometimes interfere with certificate validation.

Resolving SSL Certificate Errors

Here’s a step-by-step guide to resolving these errors. We’ll cover the most common solutions, starting with the simplest.

1. Update Your Certificate Bundle

The first step is to ensure you have a current "certificate bundle." This bundle is a file containing a collection of trusted root certificates. A widely used bundle is available from Mozilla/curl:

https://curl.haxx.se/docs/caextract.html

Download the cacert.pem file from this link.

2. Configure PHP to Locate the Certificate Bundle

PHP needs to know where to find this cacert.pem file. There are two primary ways to configure this:

Using php.ini: This is the most common and recommended approach. Open your php.ini file (location varies depending on your operating system and PHP installation). Look for the [curl] and/or [openssl] sections. If they don’t exist, you can add them. Add or modify the following lines, replacing /path/to/your/cacert.pem with the actual path to the downloaded cacert.pem file:

[curl]
curl.cainfo = "/path/to/your/cacert.pem"

[openssl]
openssl.cafile = "/path/to/your/cacert.pem"

Using Environment Variables: You can also set the PHP_CAINFO environment variable. This method is less common but can be useful in certain deployment scenarios.

3. Restart Your Web Server

After modifying php.ini, you must restart your web server (e.g., Apache, Nginx) and potentially your PHP FastCGI Process Manager (PHP-FPM) if you are using one. This ensures that the new configuration is loaded.

4. Verify the Configuration

You can verify that PHP is correctly reading the certificate bundle by using the following PHP code snippet:

<?php
echo "openssl.cafile: ", ini_get('openssl.cafile'), "\n";
echo "curl.cainfo: ", ini_get('curl.cainfo'), "\n";
?>

This code will print the paths that PHP is using for certificate verification. Make sure they point to your cacert.pem file.

5. Addressing Specific Library Configurations (Guzzle)

If you’re using a specific PHP library like Guzzle, you might need to configure it explicitly. Guzzle, for example, will follow these steps to locate a certificate archive:

Check if openssl.cafile is set in your php.ini.
Check if curl.cainfo is set in your php.ini.
Check for specific files in common locations (e.g., /etc/pki/tls/certs/ca-bundle.crt, /etc/ssl/certs/ca-certificates.crt).

If you are still experiencing issues with Guzzle, you can point it directly to the certificate bundle from within your code:

use GuzzleHttp\Client;

$client = new Client([
    'verify' => '/path/to/your/cacert.pem',
]);

6. Operating System Specific Considerations

Windows: Ensure you use forward slashes (/) in the paths within php.ini, even though Windows typically uses backslashes.
Linux/macOS: Ensure the user running the web server has read permissions on the cacert.pem file.

By following these steps, you should be able to resolve most SSL certificate errors encountered in your PHP applications. Remember to update your certificate bundle periodically to ensure you have the latest root certificates.