/etc/ssl/certs, macOS uses the Keychain Access application with distinct Trust settings for each certificate. This article explains why your local development CA might work in browsers or tools on Linux but fail on macOS, and provides the exact steps to fix it by manually adjusting trust policies.
Understanding the Root Cause
The primary reason for this discrepancy lies in the architecture of certificate validation. On most Linux distributions, adding a certificate to the system trust store is a matter of copying the file to a specific directory and running an update command. The system then trusts that certificate globally for all applications. macOS, however, isolates certificates within the user’s Keychain. Even if you import a certificate into the "System" or "Login" keychain, it does not automatically inherit full trust privileges. By default, newly imported certificates in macOS are set to "System Default." This setting often results in untrusted errors when used for self-signed domains or internal Certificate Authorities. You must explicitly change the trust level to "Always Trust" for the certificate to be recognized by Safari, Chrome, and other macOS-native applications. Without this manual override, the OS treats the certificate as unverified, blocking secure connections even if the underlying cryptographic signature is valid.Importing the Certificate Correctly
To resolve the issue, you first need to ensure the certificate is properly placed in the correct keychain. Open the Keychain Access application, which can be found via Spotlight search. Drag your.crt or .pem file into the window. It is crucial to drop the file into the System keychain rather than the Login keychain if you want the trust setting to apply to all users on the machine. If you are working on a personal machine, the Login keychain is acceptable, but you must ensure you are editing the right entry.
Once the certificate appears in the list, double-click it to open its properties. You will see several sections, including Basic Constraints, Key Usage, and Trust. Expand the Trust section. Here, you will find options for how the certificate should be handled during SSL connections. By default, this may be set to "Use System Defaults," which causes the failure you are experiencing. Change the option for Secure Sockets Layer (SSL) to Always Trust. You may also need to adjust the HTTPS and HTTP settings depending on your application requirements, though SSL usually covers HTTPS traffic.
After making these changes, close the window. macOS will prompt you to authenticate using your password or Touch ID to confirm the change. Once authenticated, the certificate is now trusted for secure connections. You may need to restart your browser or clear its DNS cache for the changes to take effect immediately.
Verifying Trust Settings
It is important to verify that the trust policy was applied correctly. Return to the certificate details in Keychain Access and look at the Trust section again. Ensure that the dropdowns for SSL, HTTPS, and HTTP all reflect your new selection. If they still show "Use System Defaults," the change did not save, and you should repeat the process. Additionally, check the icon next to the certificate in the main list. A trusted certificate usually displays a small lock icon or no warning symbol. An untrusted one might display a red cross or a question mark. If the certificate shows a warning despite being set to Always Trust, there may be a conflict with existing certificates. Check if you have multiple entries for the same Common Name (CN). Duplicate certificates can cause confusion in the validation chain. Remove any duplicate entries, keeping only the one with the correct trust settings. Clearing the browser cache is also recommended, as browsers often cache certificate revocation lists and trust states locally.Troubleshooting Persistent Errors
If you have adjusted the trust settings and the error persists, consider checking the certificate chain. A root certificate alone is often insufficient; intermediate certificates may be required to establish a complete chain of trust. Ensure that all necessary intermediate CAs are also imported into the Keychain and set to Always Trust. You can view the chain by clicking on the certificate in Keychain Access and looking at the related certificates section. Another common issue arises from time synchronization. macOS relies heavily on accurate system time for certificate validation. If your system clock is significantly off, certificates may appear invalid because their validity period seems to be in the future or past. Check your date and time settings to ensure they are synchronized with internet time servers. Finally, some enterprise environments use Managed Trust Policies via Mobile Device Management (MDM) profiles. These profiles can override user-level trust settings. If you are on a managed device, contact your IT administrator to ensure the CA is approved at the system level.Frequently Asked Questions
Why does my browser still show a warning after changing trust settings?
Browsers like Chrome and Firefox maintain their own certificate stores separate from macOS Keychain Access. After updating the trust in Keychain, you must restart the browser completely. In some cases, you may need to go into the browser's security settings and remove the previous exception for the site before reloading.
Can I automate the trust setting process via command line?
Yes, you can use the security command-line tool to modify trust policies. For example, you can use security add-trusted-cert to add a certificate and then use security set-key-partition-list to adjust partition flags. However, manually using Keychain Access is generally safer and more transparent for individual developers.
What is the difference between System and Login keychains?
The Login keychain is tied to your specific user account and unlocks when you log in. The System keychain affects all users on the machine and requires administrative privileges to modify. For development environments shared across users, placing the CA in the System keychain ensures consistent behavior.
How do I remove a trusted certificate if I made a mistake?
Open Keychain Access, locate the certificate, and delete it by pressing the Delete key or selecting File > Delete. You will be prompted to enter your password to confirm the removal. After deletion, restart your browser to ensure the trust state is cleared.
Does this issue affect curl or wget commands?
Tools like curl and wget on macOS often rely on the system keychain for SSL verification. If you have added the CA to the System keychain and set it to Always Trust, these tools should recognize it. If they still fail, you may need to specify the certificate path explicitly using the --cacert flag.