How to root local SSL certificates on Linux and macOS

Why your browser complains about local HTTPS sites

When developing web applications, it is very common to access addresses like localhost or fake domains created just for testing. In practice, this means your computer is trying to open a secure site without a legitimate guarantee seal. On the real internet, this seal is provided by companies called Certificate Authorities, which verify whether the site owner is truly who they claim to be. On your computer, since the site was created by yourself, the browser looks at that connection and triggers a loud alarm stating the connection is not secure.

This warning exists to protect ordinary users against internet scams, but in everyday programming, it gets in the way. Testing modern security features, such as cookies that only work with encryption or geolocation APIs, requires the development environment to be identical to production. The solution to silence this warning is not to disable browser security, but rather to create your own certificate authority and teach your operating system to trust it. This approach ensures tests occur in a scenario faithful to the real world.

To understand how this works behind the scenes, it is worth remembering how how to inspect HTTPS traffic in Wireshark using session keys helps decode encrypted packets for debugging purposes. Similarly, when we create a local certificate, we are forcing the machine to recognize a private key and a root certificate that digitally sign our test domains, such as 'app.test' or 'api.local'.

Creating your own certificate authority with OpenSSL

The first practical step to solve this problem is to generate a custom root certificate using OpenSSL, which is a standard tool for handling cryptography on Unix-based systems. In practice, this tool works like a digital stamp factory. The root certificate you will create will be the main seal, and any other certificate generated from it will be accepted by your computer as if it came from a major security company.

To generate the root authority, run the command below in your Linux or macOS terminal. This command creates a private key with strong encryption and a certificate that will last for several years. Remember to replace the identification data according to your personal preference:

openssl req -x509 -nodes -new -sha256 -days 1024 -newkey rsa:2048 -keyout rootCA.key -out rootCA.pem -subj '/C=US/ST=California/L=San Francisco/O=DevLocal/CN=DevLocal Root CA'

After running this command, you will have two main files in your current folder: 'rootCA.key', which must be kept in absolute secrecy since it is the key that signs certificates, and 'rootCA.pem', which is the public certificate your operating system will need to know and embrace as trusted.

Installing the root certificate on Linux systems

Now that you have the root certificate ready, the Linux system needs to be instructed to trust it. Since there are several different Linux distributions, the location where these certificates are stored can change slightly. However, in Debian and Ubuntu-based distributions, the process is quite straightforward and involves copying the file to the system certificate folder and updating the trust list.

To perform this task securely and without errors, follow the sequence of commands below in your terminal:

1. Copy the generated certificate to the system trusted authorities directory.
   

   sudo cp rootCA.pem /usr/local/share/ca-certificates/dev-root-ca.crt

2. Update the operating system's internal certificate database.
   

   sudo update-ca-certificates

If the success message appears in the terminal, it means Linux now trusts any certificate signed by your 'rootCA.pem'. If you use infrastructure tools or complex local servers — such as those we usually manage when we how to configure Cron scheduler on Linux without errors for automated tasks —, this systemic trust prevents integration scripts from failing due to missing valid certificates.

Registering the certificate authority on macOS

On macOS, certificate management is centralized in a graphical application called Keychain Access, although we can also do this quickly via the command line. The goal here is the same as Linux: insert the 'rootCA.pem' file into the system keychain repository and change the trust policy so macOS accepts the certificate without restrictions.

To add the root certificate on macOS using the terminal, run the command below:

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain rootCA.pem

After running this command, the system will prompt for your administrator password. Once the authority is integrated, open Safari or Google Chrome and you will notice that annoying invalid certificate warnings will immediately disappear from your local development domains.

Generating specific certificates for your projects

With the root authority installed and trusted, the next step is to create individual certificates for each project you are developing. If you are building an application on a domain like 'myproject.test', you will need a configuration file that defines subject alternative names, allowing the browser to recognize the certificate for that specific address.

Create a configuration file named 'server.ext' with the following content to define domain rules:

authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = myproject.test
DNS.2 = localhost

Next, generate the server private key and signing request, and finalize by signing the certificate with your newly created root authority using OpenSSL commands.

Validating configuration and troubleshooting common issues

After going through all configuration steps, it is essential to validate whether your local web server is actually serving the correct certificate. Typos in the configuration file or incorrect folder permissions can cause the browser to keep displaying alerts, requiring a detailed investigation of network behavior.

If connection failures or unexpected behavior persist on secure routes, network diagnostic tools help understand where the packet is failing, just as we do when we how to inspect network packets with tcpdump on Linux to trace dropped connections. Also check if your operating system's 'hosts' file correctly points the local domain to the '127.0.0.1' IP address.

Final Considerations

Configuring local SSL certificates in Linux and macOS development environments is a time investment that brings immediate returns in productivity and testing fidelity. By creating a custom certificate authority and registering it correctly in the operating system, you eliminate browser security false positives and can test advanced features in a fully isolated and secure manner.

Mastering this process avoids routine frustrations and ensures your code transitions seamlessly between your development machine and cloud production servers, maintaining end-to-end integrity and encryption at all stages of the software development lifecycle.