Setting up to use server side certificates for your NGINX server.

Details: Written by: Eric Naujock; Category: NGINX; Published: 08 July 2018; Hits: 6535

There are a number of articles out there that describe the process. But many seem to leave out small bits and pieces of the final solution. I am trying to cover all the bits and pieces I have learned as I have had to solve this problem for some of my own projects.

Select where you will be holding this CA folder. I am using one separate CA for each site hosted to prevent certificate cross-contamination. There were also issues in the past where NGINX did not like to play with non-root certificate authorities.

When you choose where you want to put your CA for the service you may want to choose a common location. Especially if you are going to run multiple sites on your server. Some common places to consider putting the files include your /etc/nginx folder or the /opt folder.

You will notice that I do not have my key files encrypted. This is because I plan to have scripts be able to generate and manage my user certificates. If you are backing up your keys or storing them outside of the CA make sure you encrypt your keys. By encrypting your keys you will have to store your password for the key somewhere close by to allow recovery for the OpenSSL commands to work with the keys. Ideally, you would now use AES256 for saving your keys. Always protect your key files, especially the root key since if you lose that key its game over and you will have to rebuild everything from scratch. If you are going to export your keys or allow your users to retrieve their keys you should password protect and encrypt your keys.

I am using one local CA for each site I plan to protect this way due to the challenges of getting a hierarchy of key chains to protect sites. If you use a common CA for multiple sites then one certificate could authenticate to more than one site. [Find the article that refers to this issue. ]

If you do choose to use one chain for a number of sites you will want to make sure the root and all intermediate certificates are included in the CA file sent to NGINX, you will also need to make sure that in the CRL file you include all the CRL files for each Root, intermediate, and final CA. If you fail to include those CRL.pem files in the one CRL.PEM file then you will find the CA authentication will fail.

It is possible to use one configuration file to hold the configurations for multiple CAs. You would just need to make sure you specify the CA section to use when working with the CA. For simplicity, I am using one openssl.cnf file for each CA.

Also, note that when backing up the CA. Make sure to backup the entire CA. You will need key all the files to get your CA backed up and running when restored to a new location.

This part is based on the following posting.

https://arcweb.co/securing-websites-nginx-and-client-side-certificate-authentication-linux/

Going with this article I had issues getting the CRL list to behave properly and NGINX would not allow my certs to work. If you do all these items manually you will wind up with an unworkable CRL file and NGINX will not allow you certs to work with the site.

Important: Many users start our thinking that the user certificate is in any way related to the SSL certificate used to secure the website. This is a false assumption. The user's certificate authority can be completely separate and distinct from the CA used to sign your website traffic.

All the OpenSSL paths are relative to the root of the CA folder.

Create your CA (Certificate authority)

Create your openssl.conf file with the following components.

[ ca ]
default_ca = CA_default                 # The name of the CA configuration to be used. 
                                        # can be anything that makes sense to you.
[ CA_default ]
dir = /etc/nginx/clientssl/devmorgue    # Directory where everything is kept
certs = $dir/certs/users                # Directory where the issued certs are kept
crl_dir = $dir/crl                      # Directory where the issued crl are kept
database = $dir/index.txt               # database index file.
#unique_subject = no                    # Set to 'no' to allow creation of
                                        # several certificates with same subject.
new_certs_dir = $dir/newcerts           # Default directory for new certs.

certificate = $dir/certs/ca.crt         # The CA certificate
serial = $dir/serial                    # The current serial number
crlnumber = $dir/crlnumber              # The current crl number
                                        # must be commented out to leave a V1 CRL
crl = $dir/private/crl.pem              # The current CRL
private_key = $dir/private/ca.key       # The private key
RANDFILE    = $dir/private/.rand        # private random number file

x509_extensions = usr_cert              # The extentions to add to the cert

name_opt = ca_default                   # Subject Name options
cert_opt = ca_default                   # Certificate field options

default_days    = 365                   # how long to certify for
default_crl_days= 30                    # how long before next CRL
default_md    = sha256                  # use public key default MD
preserve    = no                        # keep passed DN ordering

policy = policy_match

####################################################################
# For the CA policy
[ policy_match ]
countryName = match
stateOrProvinceName = match
organizationName = match
organizationalUnitName = optional
commonName = supplied
emailAddress = optional

# For the 'anything' policy
# At this point in time, you must list all acceptable 'object'
# types.
[ policy_anything ]
countryName = optional
stateOrProvinceName = optional
localityName = optional
organizationName = optional
organizationalUnitName = optional
commonName = supplied
emailAddress = optional

####################################################################
[ req ]
default_bits       = 4096
default_keyfile    = cakey.pem
distinguished_name = ca_distinguished_name
x509_extensions    = ca_extensions
string_mask        = utf8only

####################################################################
[ ca_distinguished_name ]
countryName         = Country Name (2 letter code)
countryName_default = US

stateOrProvinceName         = State or Province Name (full name)
stateOrProvinceName_default = Ohio

localityName                = Locality Name (eg, city)
localityName_default        = Toledo

organizationName            = Organization Name (eg, company)
organizationName_default    = example.com

organizationalUnitName         = Organizational Unit (eg, division)
organizationalUnitName_default = Server Research Department

commonName        = Common Name (e.g. server FQDN or YOUR name)
commonName_default = Test CA

emailAddress         = Email Address
emailAddress_default = This email address is being protected from spambots. You need JavaScript enabled to view it.

[ usr_cert ]

# These extensions are added when 'ca' signs a request.

# This goes against PKIX guidelines but some CAs do it and some software
# requires this to avoid interpreting an end user certificate as a CA.

basicConstraints=CA:FALSE

# Here are some examples of the usage of nsCertType. If it is omitted
# the certificate can be used for anything *except* object signing.

# This is OK for an SSL server.
# nsCertType                    = server

# For an object signing certificate this would be used.
# nsCertType = objsign

# For normal client use this is typical
# nsCertType = client, email

# and for everything including object signing:
# nsCertType = client, email, objsign

# This is typical in keyUsage for a client certificate.
# keyUsage = nonRepudiation, digitalSignature, keyEncipherment

# This will be displayed in Netscape's comment listbox.
nsComment                       = "OpenSSL Generated Certificate

# PKIX recommendations harmless if included in all certificates.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer

# This stuff is for subjectAltName and issuerAltname.
# Import the email address.
# subjectAltName=email:copy
# An alternative to produce certificates that aren't
# deprecated according to PKIX.
# subjectAltName=email:move

# Copy subject details
# issuerAltName=issuer:copy

#nsCaRevocationUrl              = http://www.domain.dom/ca-crl.pem
#nsBaseUrl
#nsRevocationUrl
#nsRenewalUrl
#nsCaPolicyUrl
#nsSslServerName

# This is required for TSA certificates.
# extendedKeyUsage = critical,timeStamping

In the new CA create a series of folders.

Create the folders required for the CA. The “-p” flag in the mkdir tells the utility to create the full hierarchy specfified. This is for the certs/users folder.

mkdir -p certs/users newcerts private

This should have a folder set like so

Certs
    Users
Newcerts
Private

Create the index.txt file

touch index.txt

Create a serial number file. This contains a single number with the serial number for the next certificate. Many articles will tell you to just but 01 into here.

echo 1001 > serial

Create the CRL number file. This will be used when revoking certificates. But does need to exist.

echo 01 > crlnumber

Create the index.txt.attr file for the index.txt file.

touch index.txt.attr

Make sure all the files and folders are read and writable by the user accounts that will manage them. Whatever user will be running or executing the OpenSSL command should own the folder and its contents. Keep in mind you do what to protect this folder from accounts that should not be messing with it. Do not put it in any path that a web server would have access to. There will be files in this hierarchy that MUST be kept private.

Create your CA Private Key. ( This must be kept safe but will also need to be readable for the purposes of generating certificates.) I am using 4096 bits.

openssl genrsa -out private/ca.key 4096

This is what an unencrypted 4096 bit should look like. If you omit the length you may get a file much smaller. This example file was generated and discarded so do not expect to see this particular key ever again.

When you generate your private key you may get a warning about unable to write to random file. “ unable to write 'random state'

e is 65537 (0x010001) “ If you are doing this on Linux or a system with a random number generator this is fine. Openssl will try to fetch a random number from the build in random generator. See https://www.openssl.org/docs/faq.html#USER1 for more information about this.

My code does not include a passphrase. It is strongly considered to be good practice to encrypt the key with a passphrase.

The command to do this is a minor change but every time you wish to access your key you will be required to supply this passphrase. I have in my example AES256 as it is one of the strongest hashing methods. When you encrypt the key you will have to present the password each time unless you add the “ -passout pass:<mypassword>” to the line, or “-passout

file:{Some filename}” for open ssl to read the password.

openssl genrsa -aes256 -out private/ca.key 4096

This is what an encrypted 4096-bit private key would look like. This particular key was generated for example but has been deleted shortly afterward.

Create your new root cert

We will not create our root certificate for the service. This is the certificate we will use when we sign client certificates. The length of time is set to far in the future assuming to prevent from having to renew the root CA certificate anytime soon.

openssl req -new -x509  -days 10958 -key private/ca.key -out certs/ca.crt

You will have to answer the certificate creation questions. This will generate your root certificate.

Verify your certificate.

openssl x509 -noout -text -in certs/ca.crt

Information related to the creation of CRL (Certificate Revocation Lists) was found at https://jamielinux.com/docs/openssl-certificate-authority/certificate-revocation-lists.html

Create your CRL (Certificate Revocation List)

openssl ca -config openssl.cnf -gencrl -out private/crl.pem

Check your CRL file

openssl crl -inform PEM -text -noout -in private/crl.pem

This post was helpful in checking this out.

https://langui.sh/2010/01/10/parsing-a-crl-with-openssl/

Add configuration of the user CA to NGINX

Configure NGINX to use the new CA for user authentication. Add these three lines to your NGINX configuration.

ssl_client_certificate /etc/nginx/clientssl/{websitename}/certs/ca.crt;
ssl_crl /etc/nginx/clientssl/{websitename}/private/crl.pem;
ssl_verify_client on;

You could use “ ssl_verify_client optional;” if you want the site to check the passed cert.

After making these changes make sure you check your configuration Then restart NGINX.

Note ssl_verify has an option of either On or Optional. If you choose Optional the traffic will still go through even without a certificate and it will be up to your application to check for the certificate. If you want to use the SSL certificate as an enhanced security option the Optional may be worthwhile. But if you want absolute security then On is your option.

At this point, you should not be able to get to your website and you should be getting a 400 Bad Request. With the message “No required SSL certificate was sent”.

A recent discovery about different browsers when testing this.Wakanda Backend access with Safari not working when using certificate based authentication. based authentication from javascript when the backend port is different than the frontend port.

Creating the user's certificate

Now we will create our first user certificate and test that the website will play nicely.

I will create a combination of the users key and CSR in one line. This could also be done in two lines.

openssl req -out certs/users/{username}.csr -new -newkey rsa:4096 -nodes -keyout certs/users/{username}.key

Take a look at the key and make sure it’s the right length.

cat certs/users/{username}.key

Then take a look at the CSR. Make sure the CSR is correct before signing it.

openssl req -text -noout -verify -in certs/users/{username}.csr

Now we will sign the certificate.

openssl ca -config openssl.cnf -cert certs/ca.crt -keyfile private/ca.key -in certs/users/{username}.csr

At this point in time, you will have to sign the certificate.

The new certificate will be placed in newcerts with the serial number.pem as the name of the file. This will match the serial.old.

Move the newly created certificate to your certs/users folder.

mv newcerts/1001.pem certs/users/{username}.crt

Serial will update to a new number to be used for the next certificate.

Copy the newly minted certificate to your certificates/users folder and rename to match the key.

Now check the certificate.

openssl x509 -noout -text -in certs/users/{username}.crt

Now we will export the certificate and user key into a p12 file.

openssl pkcs12 -export -clcerts -in certs/users/{username}.crt -inkey certs/users/{username}.key -out certs/users/{username}.p12

Note that while you can leave the password empty by just hitting the return key some athe apple keychain importer will not accept a p12 file with no password.

Check that the p12 file is working.

openssl pkcs12 -in certs/users/{username}.p12 -info

Deliver the certificate to the user.

Copy the root certificate and p12 file together and take to client computer.

Install the CA certificate into your system and trust the certificate. Depending on the operating system you may need to install this in the root certificates of your operating system. On Mac OS computers you can use the .mobileconfig file to install your root certificates and in doing so it will automatically install and trust the root certificates provided in the .mobileconfig file.

Once the certificate and CA is installed you should be able to refresh the page and have your certificate work in your local browser.

Remember after installing your new certificate you may need restart your browser to make sure the page loads and looks for the proper certificate to send. This is required for safari.

Firefox uses its own certificate system and will need to be manually installed for the user. It will not trust the certificate stores built into any running operating system.

Special extra techniques to install certificates in Firefox and Google Chrome.

If the certificate is working properly then you should be able to load your web page.

Note : Client side certificates work well in all modern browsers, but Safari has an issue where it will not check the Client SSL certificate for AJAX requests sent to a server after the main page is loaded. This may case issues with system like Wakanda who use a different port to handle data requests that the main server port.

Revoking a certificate.

Sometimes we will need to revoke a certificate that has gone rogue or for a user of office that is no longer allowed to access services.

First we will revoke the certificate for the user. This will kill their access to the service.

openssl ca -config openssl.cnf -revoke certs/users/{username}2.crt -keyfile private/ca.key -cert certs/ca.crt

Now at this point the certificate is revoked but we will also need to update the certificate revocation list so that NGINX of other parties checking the CRL (Certificate Revocation lIst) will know about the revocation.

You may want to run this function for each CA as a cron script either daily, or hourly depending on the security requirements of your organization. Running this in a cron function makes sure that the certificate is permanently revoked even if the CRL generation step was missed.

openssl ca -config openssl.cnf -keyfile private/ca.key -cert certs/ca.crt -out private/ca.crl -crldays 1095