Skip to content

Instantly share code, notes, and snippets.

@buraksahin59

buraksahin59/enable-ssl-on-localhost.md

Last active July 9, 2020 22:27
Show Gist options
  • Save buraksahin59/74df9eb2a8f2f62d8a525fee98962892 to your computer and use it in GitHub Desktop.
Save buraksahin59/74df9eb2a8f2f62d8a525fee98962892 to your computer and use it in GitHub Desktop.
Download ZIP
Localhost SSL Certificate on Mac OS Sierra, High Sierra and Catalina
Raw
enable-ssl-on-localhost.md 
Sources: 
- https://getgrav.org/blog/macos-catalina-apache-ssl
- https://gist.github.com/ethicka/27c36c975a5c2cbbd1874bc78bab61c4

STEP 1: Enable SSL Module

It is often important to be able to test your local site setup under SSL (e.g. https://yoursite.com). There are a few steps that are needed to accomplish this with your Homebrew-based Apache setup. The first step is to make some modifications to your httpd.conf:

$ code /usr/local/etc/httpd/httpd.conf

In this file you should uncomment both the socache_shmcb_module, ssl_module, and also the include for the httpd-ssl.conf by removing the leading # symbol on those lines:

LoadModule socache_shmcb_module lib/httpd/modules/mod_socache_shmcb.so
...
LoadModule ssl_module lib/httpd/modules/mod_ssl.so
...
Include /usr/local/etc/httpd/extra/httpd-ssl.conf

Next we need to change the default 8443 port to the more standard 443 and comment out some sample code. So we need to open the SSL config file:

$ code /usr/local/etc/httpd/extra/httpd-ssl.conf

find:

Listen 8443

replace it with:

Listen 443

then find:

<VirtualHost _default_:8443>

#   General setup for the virtual host
DocumentRoot "/usr/local/var/www"
ServerName www.example.com:8443

and replace the 8443 references with 443 and note the commenting:

<VirtualHost _default_:443>

#   General setup for the virtual host
#DocumentRoot "/usr/local/var/www"
#ServerName www.example.com:443

STEP 2: Generate Certificates

Create a directory as named ssl within /usr/local/etc/httpd/ using Terminal.app:

$ sudo mkdir /usr/local/etc/httpd/ssl

To pass process from here till Step 3, you can use my script by following link https://gist.github.com/buraksahin59/91a98a04f05fd09addbe924cc2cd3de1

Next, generate server keys:

$ sudo openssl genrsa -out /usr/local/etc/httpd/server.key 2048
$ sudo openssl genrsa -out /usr/local/etc/httpd/ssl/yoursite.key 2048
$ sudo openssl rsa -in /usr/local/etc/httpd/ssl/yoursite.key -out /usr/local/etc/httpd/ssl/yoursite.key.rsa

Create a configuration file using Terminal.app:

$ sudo touch /usr/local/etc/httpd/ssl/yoursite.conf

Edit the newly created configuration file and add the following:

[req]
default_bits = 1024
distinguished_name = req_distinguished_name
req_extensions = v3_req

[req_distinguished_name]

[v3_req]
basicConstraints = CA:FALSE
keyUsage = nonRepudiation, digitalSignature, keyEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = yoursite.local
DNS.2 = *.yoursite.local

Generate the required Certificate Requests using Terminal.app:

$ sudo openssl req -new -key /usr/local/etc/httpd/server.key -subj "/C=/ST=/L=/O=/CN=yoursite.local/emailAddress=/" -out /usr/local/etc/httpd/server.csr
$ sudo openssl req -new -key /usr/local/etc/httpd/ssl/yoursite.key.rsa -subj "/C=/ST=/L=/O=/CN=yoursite.local/" -out /usr/local/etc/httpd/ssl/yoursite.csr -config /usr/local/etc/httpd/ssl/yoursite.conf

My example for Certificate Requests as following:

$ sudo openssl req -new -key /usr/local/etc/httpd/server.key -subj "/C=TR/ST=Istanbul/L=Istanbul/O=Local Organization/CN=yoursite.local/[email protected]/" -out /usr/local/etc/httpd/server.csr
$ sudo openssl req -new -key /usr/local/etc/httpd/ssl/yoursite.key.rsa -subj "/C=TR/ST=Istanbul/L=Istanbul/O=Local Organization/CN=yoursite.local/" -out /usr/local/etc/httpd/ssl/yoursite.csr -config /usr/local/etc/httpd/ssl/yoursite.conf

Note: Complete the values C= ST= L= O= CN= to reflect your own organizational structure, where:

  • C= eq. Country: The two-letter ISO abbreviation for your country.
  • ST= eq. State or Province: The state or province where your organization is legally located.
  • L= eq. City or Locality: The city where your organization is legally located.
  • O= eq. Organization: he exact legal name of your organization.
  • CN= eq. Common Name: The fully qualified domain name for your web server

Use the Certificate Requests to sign the SSL Certificates using Terminal.app:

$ sudo openssl x509 -req -days 365 -in /usr/local/etc/httpd/server.csr -signkey /usr/local/etc/httpd/server.key -out /usr/local/etc/httpd/server.crt
$ sudo openssl x509 -req -extensions v3_req -days 365 -in /usr/local/etc/httpd/ssl/yoursite.csr -signkey /usr/local/etc/httpd/ssl/yoursite.key.rsa -out /usr/local/etc/httpd/ssl/yoursite.crt -extfile /usr/local/etc/httpd/ssl/yoursite.conf

Add the SSL Certificate to Keychain Access.

$ sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /usr/local/etc/httpd/ssl/yoursite.crt

Step 3: Apache Virtual Host Configuration

Edit the Virtual Hosts file /usr/local/etc/httpd/extra/httpd-vhosts.conf to add appropriate SSL based virtual hosts.

$ code /usr/local/etc/httpd/extra/httpd-vhosts.conf

Here you can create a VirtualHost entry for each virtual host that you wish to provide SSL support for.

#Virtual Host Entry for yoursite.local
<VirtualHost *:443>
    ServerName yoursite.local
    DocumentRoot "/Users/buraksahin/Sites/yoursite"
    ErrorLog "/private/var/log/apache2/yoursite-error_log"
    CustomLog "/private/var/log/apache2/yoursite-access_log" common

    SSLEngine on
    SSLCertificateFile "/usr/local/etc/httpd/ssl/yoursite.crt"
    SSLCertificateKeyFile "/usr/local/etc/httpd/ssl/yoursite.key"
</VirtualHost>

In this example we have created the VirtualHost for yoursite.local, but it could be any of your existing or even a new VirtualHost. The important parts are the the 443 port, along with SSLEngine on and the SSLCertificateFile and SSLCertificateKeyFile entries that point to the certificate we now need to generate.

Then all you need to do now is double check your Apache configuration syntax:

$ sudo apachectl configtest

If all goes well, restart Apache:

$ sudo apachectl -k restart

Open your browser and visit https://yoursite.local to verify your configuration.

Tip You can tail -f /usr/local/var/log/httpd/error_log, the Apache error log while you restart to see if you have any errors.

Errors and Solves

SSL Library Error

If you got error like given below;

AH00016: Configuration Failed
[Thu Jul 09 23:53:10.720117 2020] [ssl:emerg] [pid 66730] AH02572: Failed to configure at least one certificate and key for localhost:443
[Thu Jul 09 23:53:10.720428 2020] [ssl:emerg] [pid 66730] SSL Library Error: error:140A80B1:SSL routines:SSL_CTX_check_private_key:no certificate assigned
[Thu Jul 09 23:53:10.720438 2020] [ssl:emerg] [pid 66730] AH02312: Fatal error initialising mod_ssl, exiting.

You need to find files given below in /usr/local/etc/httpd/extra/httpd-ssl.conf

SSLCertificateFile "/usr/local/etc/httpd/server.crt"
SSLCertificateKeyFile "/usr/local/etc/httpd/server.key"

and replace with your server.crt and server.key file

SSLCertificateFile "/usr/local/etc/httpd/ssl/server.crt"
SSLCertificateKeyFile "/usr/local/etc/httpd/ssl/server.key"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment