csr

A Certificate Signing Request (CSR) contains both administrative and technical information about a certificate request. A CSR is often required when purchasing a certificate from a provider or when generating one yourself.

Prerequisites

The openssl library is required to generate the private key and CSR. Run the following command in your local environment to see if you already have openssl installed installed.

:::term
$ which openssl
/usr/bin/openssl

If the which command does not return a path then you will need to install openssl yourself:

If you have...	Install with...
Mac OS X	Homebrew: brew install openssl
Windows	Windows complete package .exe installer
Ubuntu Linux	apt-get install openssl

Create a Private Key

Keep the private key file in a safe place as it will be required again when configuring SSL for your application.

A private key is required to generate the CSR. You will be asked to enter a passphrase for your private key during this process. Enter any value as we will strip it out in the next step.

:::term
$ openssl genrsa -des3 -out site.key 2048
...
Enter pass phrase for site.key:
Verifying - Enter pass phrase for site.key:

You will now have a site.keyprivate key file in your current working directory.

For the certificate to be automatically loaded into a web server the site.key private key file will need to have its password stripped.

Making a copy of the unstripped file, `site.orig.key`, ensures we can easily rollback should we encounter errors.

:::term
$ mv site.key site.orig.key
$ openssl rsa -in site.orig.key -out site.key

Generate a Certificate Signing Request

Generation of a CSR requires the private key along with administrative information about you or your organization (i.e. the certificate requester). There are a few essential fields to the CSR:

• Country Name: This is the two letter code, in ISO 3166-1 format, of the country your organization is based in.
• State or Province Name: Spell out the full name of your organization's region (state, province etc..). No abbreviations.
• Locality Name: Spell out the city your organization is based in.
• Organization Name: The full legal name of your organization.
• Organizational Unit Name: The department or division of your organization requesting the certificate. This is optional and can be left blank.
• Common Name: This is the fully qualified domain name that you wish to secure traffic to. This is not your personal name.
  • To secure traffic to a single subdomain you would enter something like "secure.mydomain.com".
  • To secure all subdomains you will need to specify the wildcard URL pattern: "*.mydomain.com".
  • To secure the root domain (mydomain.com) specify "mydomain.com".
• The rest of the fields are optional and can be left empty.

Execute the CSR generation in your terminal with the information outlined above:

The pass phrase requested is the same one you used when creating your private key.

If you mess up just use the Ctrl^C key sequence to quite the CSR generation process. You can also delete the existing site.csr file and start over.

:::term
$ openssl req -new -key site.key -out site.csr
...
Country Name (2 letter code) [AU]:US
State or Province Name (full name) [Some-State]:California
Locality Name (eg, city) []:San Francisco
Organization Name (eg, company) [Internet Widgits Pty Ltd]:Your Company, Inc.
Organizational Unit Name (eg, section) []:
Common Name (eg, YOUR name) []:secure.yourdomain.com
Email Address []:
...

The result of this operation will be a site.csr file in your local directory. This is your certificate signing request and is necessary when purchasing a certificate from a certificate provider or generating one yourself.

When submitting the CSR to your certificate authority you may be asked what web server to create the certificate for. If so, select Apache 2.x as the web server for use on Heroku.