Adding a Custom Certificate Authority to PHP for Persistent Trust
When your application needs to fetch remote resources signed by a private Certificate Authority (CA), you quickly hit a wall: PHP's default SSL verification only trusts the root CAs bundled in its configuration. If you attempt to use file('https://example.com/cert.pem') or similar functions without explicitly providing a custom stream context, the request will fail with a certificate verification error. The core issue isn't just that PHP doesn't know the CA; it's that the verification logic is tightly coupled to the specific transport layer used by the function.
You can solve this by injecting a custom stream_context every time you perform a file operation. However, this approach creates a maintenance bottleneck. If your application calls file() or fopen() from dozens of endpoints, you end up duplicating context creation logic across your codebase. You need a way to tell PHP to trust that specific CA globally, without wrapping every single call in a context factory.
The standard solution involves modifying the OpenSSL configuration files that PHP uses at runtime. Unlike some web server configurations where you drop a .crt file into /etc/ssl/certs/, PHP does not automatically scan that directory for custom CAs to add to its trust store. You must explicitly define where the CA bundle resides and instruct the OpenSSL library to load it.
Configuring the OpenSSL Environment
To make PHP permanently trust a private CA, you need to ensure the OpenSSL configuration file knows about the additional certificate bundle. This is typically done by editing the openssl.cnf file or creating a dedicated configuration snippet.
First, locate your system's OpenSSL configuration. On Linux distributions like Debian or Ubuntu, this is often found at /etc/ssl/openssl.cnf. You can check which configuration PHP is actually using by running:
php -i | grep openssl.cafile
If openssl.cafile is empty, PHP relies on the default bundle. To add your private CA's public key (or a bundle containing it), you need to update the ca_file directive within the configuration or point the system to a new file that includes both the default and custom CAs.
A robust approach is to create a combined certificate bundle. Concatenate the default CA bundle with your company's CA certificate into a single file, for example /etc/ssl/certs/ca-bundle.crt. Then, update the openssl.cnf file to point to this new location:
[ ca ]
default_ca = CA_default
CA_default {
ca_file = /etc/ssl/certs/ca-bundle.crt
verify_fail_if_no_cert = 1
}
After modifying the configuration, you must ensure PHP uses it. Sometimes php.ini has its own openssl.cafile setting that overrides the system config. You can define a default context in your php.ini file to handle this globally:
[stream]
default_socket_options = 64, 21
ssl.ciphers = TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-ECDSA:!EDH-RSA-ECDSA:!CAMELLIA128-SHA:!CAMELLIA256-SHA
ssl.verify_peer = 1
ssl.cafile = /etc/ssl/certs/ca-bundle.crt
By setting ssl.cafile in the [stream] section of php.ini, you instruct PHP to use this specific file for all SSL verification attempts, including the file() function. This eliminates the need to construct a stream context manually in your application code.
Important Considerations and Pitfalls
It is crucial to understand that simply dropping a .crt file into /etc/ssl/certs/ does not automatically register it with PHP. The OpenSSL library requires an explicit path in its configuration directives. If you update the system-wide openssl.cnf, ensure that your application has permission to read the new configuration file. Running PHP as a non-root user (like www-data) often fails if the config file permissions are too restrictive.
Additionally, be cautious about merging certificates. If you append your private CA certificate to the default bundle, ensure there are no duplicate entries or formatting issues that break the PEM structure. A malformed bundle can cause OpenSSL to reject valid certificates from other providers as well.
If you are using a framework like Laravel, remember that while the global php.ini settings apply to CLI and SAPI handlers, some environments (like certain PHP-FPM setups) might isolate configurations. In such cases, placing a custom openssl.cnf in your application root or modifying the FPM pool configuration (php-fpm.d) with the same ssl.cafile directive is often necessary.
For enterprise-grade applications where you need granular control over verification policies without touching global system files, creating a dedicated context via code remains the most secure option. However, for standard remote resource fetching where convenience and code cleanliness are priorities, configuring the global SSL CA file is the cleanest path forward. This method ensures that file() and other stream-based functions automatically trust your private CA without requiring repetitive context instantiation.