How Can PHP Create Trusted SSL Certificates for Development on a Local Network - PHP Web Push Notifications Server package blog

By Stefan Kientzler

<email contact>

In this article you can read about the following:

1. Why Can It Be Necessary to Use Locally-Trusted Certificates
   
   
2. Configure your local Web Server for HTTPS Access
   
   
   • Create and Install the Kocal CA on the System
     
     
   • Generate the Locally Trusted Certificate(s) for the Local Web Site(s)
     
     
   • Configuring the Web Server (Apache) to Use the Certificates
     
     
3. Configure Clients in the Local Network to Access Server via HTTPS
   
   
4. Additional Instructions to Install in Firefox/Edge/Opera
   
   
5. Download and Install the PHP Web Push Notifications Server Package Using PHP Composer

Why Can It Be Necessary to Use Locally-Trusted Certificates

Since many browsers nowadays require a secure context to use some APIs (such as the Web push API, which is used by the PNServer packet), it is also necessary in the development environment that a secure connection via HTTPS is available.

But, normally, the Web server cannot be reached from outside within a development environment (regardless of whether it is a single workstation or a local network).

Thus there is no possibility for 'real' certification authorities (CAs) to verify a internal test-domain (i.E. 'mysite.dev', '127.0.0.1', localhost, ...).

This is where the 'mkcert' tool comes in! It is a simple, zero-config tool that creates and installs a local CA in the system root store, and generates locally-trusted certificates.

In view of the numerous web server systems that are used in the development, the tool cannot take care about the task of configuring the server to use the certificates. This article explains the configuration steps for an Apache web server.

Configure Your Local WebServer for HTTPS Access

The configuration on the web server takes place in three steps:

1. Create and install the local CA on the system.
2. Generate the locally trusted certificate(s) for the local Web site(s)
3. Configure your Web server to use the certificate(s)

Create and Install the Local CA on the System

1. Download the latest pre-built binary according to your system.

2. Make the binary accessible from anywhere on your system:

   • On a Linux machine (suggested path for Ubuntu - other distributions need other install command and may differ in the path):
     Move the file to a system wide accessible directory (a directory contained in the system path - e.g. /usr/local/bin) and ensure it is executable:

     # first install certutil... 
     sudo apt install libnss3-tools
     # move binary and make executable
     sudo mv mkcer-v1.x.x-linux-amd64 /usr/local/bin/mkcert
     sudo chmod +x /usr/local/bin/mkcert

   • On a windows machine:
     
     
     • Move the mkcert-v1.x.x-windows-amd64.exe to any decided folder and rename it to mkcert.exe.
     • Add the folder to the system path.

3. Create and install a local CA in the system root store:

   mkcert -install

   On windows there might popup a system message that ask if you realy want to install a certificate authority, that needs to be confirmed.

   The command should return a message like:

   Created a new local CA
   The local CA is now installed in the system trust store!
   The local CA is now installed in the Firefox and/or Chrome/Chromium trust store.
   Note: Firefox support is not available on your platform. (windows)
   (requires browser restart)!

   Additional instructions to install in Firefox/Edge/Opera

The local CA is now installed on the system and the following two files have been generated:

• rootCA.pem
• rootCA-key.pem

These files are located in the directory ~/.local/share/mkcert on Linux systems orUser/<username>/AppData/local/mkcert on windows.

The rootCA.pem is required if any client should get HTTPS access to this server!

Warning:
The rootCA-key.pem file that mkcert automatically generates gives complete power to intercept secure requests from your machine. !!! Do not share it !!!.

Generate the Locally Trusted Certificate(s) for the Local Website(s)

Next step is to create the certificate your Web server. If we assume an example system whose name is mysite.dev, we can generate the trusted certification for it with the following command:

mkcert mysite.dev "*.mysite.dev" localhost 127.0.0.1

This creates the certificate for access via the server name mysite.dev, via localhost or the internal IP address:

Created a new certificate valid for the following names
 - "mysite.dev"
 - "*.mysite.dev"
 - "localhost"
 - "127.0.0.1"

The files mysite.dev+3.pem and mysite.dev+3-key.pem have been created in the current working directory.

If there are multiple virtual host configured on your server, just repeat the creation for each host:
E.g. mkcert virtualhost1 will create the files virtualhost1.pem and virtualhost1-key.pem.

Configuring the Web Server (Apache) to Use the Certificates

In view of the numerous web server systems that are used in the development, at this place i only describe the configuration for the (probably the most widespreaded) apache server.

To configure Apache to use these certificates, edit the default ssl configuration file (Linux: /etc/apache2/sites-available/default-ssl.conf; Windows: <apache-path>\conf\extra\httpd-ssl.conf) and change the SSL certificate and key file to point to the generated cert and key file. Following settings must be done:

SSLEngine  on
SSLCertificateFile      <path-to-your-certificate>/mysite.dev+3.pem
SSLCertificateKeyFile   <path-to-your-certificate>/mysite.dev+3-key.pem

Linux

Enable the SSL module, enable the SSL site and restart the apache server:

sudo a2enmod ssl
sudo a2ensite default-ssl.conf
sudo systemctl restart apache2

For further virtual hosts, copy the associated conf file(s) (e.g. sudo cp virtualhost1.conf virtualhost1-ssl.conf) and add the three lines from above with the corresponding certificate files. In addition, the port must be changed from :80 to :443:

<VirtualHost *:443>

Enable each site and restart the apache server.

Windows

Close the apache server, enable the required modules, include the SSL conf site and restart the apache server:

Edit the <apache-path>\conf\httpd.conf and remove the comment-sign (#) at following lines (if they have not already been removed so far...):

LoadModule log_config_module modules/mod_log_config.so
LoadModule setenvif_module modules/mod_setenvif.so
LoadModule ssl_module modules/mod_ssl.so
LoadModule socache_shmcb_module modules/mod_socache_shmcb.so

Include conf/extra/httpd-ssl.conf

Restart the httpd.exe.

Corresponding conf files must then be created and included in the httpd.conf for further virtual hosts.

Configure Clients in the Local Network to Access the Server via HTTPS

If you are working in a local network and want to have HTTPS access to your development webserver, on each client the created CA from the server needs to be installed.

1. If not the same operating system is running on the client as on the server, the corresponding binary from the repository is required

2. Make the binary accessible from anywhere on your system.

3. Create any directory on the client to store the CA.

4. Copy the rootCA.pem file, that was created on your server to this directory.

   Note:
   do NOT copy the rootCA-key.pem to any of the clients nor to any external target!!

5. Set the environment variable CAROOT to this directory

   • on Linux:
     export CAROOT=<path-to-the-created-directory>
   • on windows:
     set CAROOT=<path-to-the-created-directory>

   and verify the setting with
   mkcert -CAROOT

6. Call the installer
   mkcert -install
   
   You should get a messager like following:
   

   The local CA is now installed in the system trust store!
   The local CA is now installed in the Firefox and/or Chrome/Chromium trust store (linux)
   Note: Firefox support is not available on your platform. (windows)
   

   Additional instructions to install in Firefox/Edge/Opera

Add the Certificate to Other Browsers

Install the Certificate in Firefox on Windows

The current version of mkcert doesn't support the automatic installation for firefox on windwos. But don't worry, you can do this manually:

1. Open the 'Preferences' in Firefox
   
   
2. Type 'certificates' ('Zertifikate') into the search box on the top
   
   
3. Click [View Certificates...], select the 'Authorities' ('Zertifizierungsstellen') Tab and click [Import...]
   
   
4. Select the rootCA.pem file that have been created by the mkcert installer or that you have copied to your computer.
   
   
5. Close the window and restart Firefox

Install the Certificate in Edge on Windows

1. Select 'Settings' from the 'Settings and more' menu.
   
   
2. Go to the 'Privacy and Services' ('Datenschutz, Suche und Dienste') page and click on 'Manage Certificates' ('Zertifikate verwalten') in the 'Security' section to open the Certificates window.
   
   
3. Navigate to the 'Trusted Root Certification Authorities' ('Vertrauenswürdige Stammzertifizierungsstellen') tab and click [Import...]
   
   
4. Select the rootCA.pem file that have been created by the mkcert installer or that you have copied to your computer.
   
   
5. On the next page select 'Automatically Select the certificate...' ('Zertifikatsspeicher automatisch auswählen')
   
   
6. If any further security warning dialog appears, click Yes
   
   
7. Finish and relaunch the Browser.

Install the Certificate in Opera

1. Type 'opera://settings/privacy' in the URL line
   
   
2. Open the 'Security' pane and click 'Manage certificates'
   
   
3. Navigate to the 'Trusted Root Certification Authorities' ('Vertrauenswürdige Stammzertifizierungsstellen') tab and click [Import...]
   
   
4. Select the rootCA.pem file that have been created by the mkcert installer or that you have copied to your computer.
   
   
5. On the next page select 'Automatically Select the certificate...' ('Zertifikatsspeicher automatisch auswählen')
   
   
6. If any further security warning dialog appears, click Yes
   
   
7. Finish and relaunch the Browser.