How to renew the isenseproject.org SSL certificate

iSENSE Security Documentation

How to renew the isenseproject.org SSL certificate

iSENSE is no longer hosted on AWS, it is now hosted on a UMass Lowell server. We have already validated our ownership of the domain for IT. We shouldn't have to generate a new CSR, and also do not need to generate a new private key. Steps 10-13, and 15-17 apply to installing a renewed certificate (make sure to submit a ticket with IT to ask for a renewed certificate). For further reading, click here.

Prerequisites:

• The ability to login to the iSENSE AWS console and ssh into the iSENSE ec2-instance

• Basic competence with the linux command line interface

• A general idea of how public key encryption works

Note: Anything enclosed in is used as a placeholder to represent an identifier that is described inside the brackets, and not as a literal string to be entered.

The following directives describe the protocol used to renew the isenseproject.org SSL certificate in August 2018. Assuming that the rSENSE application and its supporting technologies have not been modified since, the following directives will still accomplish the goal specified in the title.

1. Login to the AWS console using credentials provided by ECG

2. Go to s3

3. Enter the bucket named rsense-ssl

4. Download the file named cs.uml.edu.key

   • This is the isenseproject.org certificate’s private key

5. Open your prefered terminal emulator and cd to the directory that contains your newly downloaded private key file

6. Run the following command using the private key filename as a parameter:

   • openssl req -out <output_filename> -key <private-key_filename> -new

   • I recommend something like this: openssl req -out cs.uml.edu.csr -key cs.uml.edu.key -new

   • This will produce a file known as a certificate signing request with the name specified by the <output_filename> parameter

7. Delete your local copy of the private key

   • This step will not affect your ability to obtain a new certificate, but it is generally a good idea to remove extra copies of security keys from your hard drive after they are no longer needed

rm cs.uml.edu.key

8. Send the newly generated certificate signing request to the party that requests it

   • In 2018, this communication was done over an email thread between Dr. Martin, IT staff, and the lab member responsible for the certificate update.

9. If IT requires ECG to validate our ownership of the domain, do the following:

   • Download the validation file sent by IT. If you do not have access to this file, ask Dr. Martin.

   • It should look something like <long-hexadecimal-string>.txt

   • The hexadecimal string that proceeds the .txt extension will hereafter be referred to by the identifier <long-hexadecimal-string>, however it is possible that you may have a different filename

   • Upload the file to the iSENSE instance so that it is accessible at:

   • https://isenseproject.org/.well-known/pki-validation/<long-hexadecimal-string>.txt

   • In 2018, the following method was used method was used:

   • The program (and protocol) known as scp ("Secure Copy Protocol") allows a user to easily copy files between hosts regardless of whether they are local or remote. It is based on ssh (“Secure shell”) protocol and usage of the program follows a similar syntax

   • The syntax is as follows:

   scp -i <path/to/aws/ssh/private.key> <path/to/file/for/upload> ec2-user@<Public DNS (IPv4)>:/path/to/destination/directory/<target_dir>/

   • TIP: When using scp, you must be sure that user ec2-user has write permissions for the destination directory, hereafter referred to as <target_dir>. If you do not know how to do this, use the following protocol:

     1. To to this, first record the original owner of the directory using this command while ssh’d into </path/to/destination/directory/<target_dir>> on the ec2 instance:

     ls -l ..

     2. The third column of the row that ends with <target_dir> is the original owner, hereafter referred to as <target_dir_original_owner>

     3. In the target directory, run the following commands to change the owner of the directory to ec2-user

     cd ..

     sudo chown ec2-user <target_dir>

     5. Now, scp your file(s) into <target_dir>

     6. Once you are done, restore ownership of <target_dir> to <target_dir_original_owner> using the following commands (assuming you begin in directory <target_dir>:

   cd ..

   sudo chown <target_dir_original_owner> <target_dir>

    7. Follow the protocol described above whenever you use scp to copy from a local host to a remote host
   

   • The <Public DNS (IPv4)> can be found in the AWS console:

     8. Login and go to ec2

     9. Select the " running instances option" (where is the number of instances ECG is running on AWS)

     10. Click on the square next to rsense-beanstalk-env

     11. A panel should appear below with several tabs. The description tab should be first and selected. The first entry in the right column will be labeled "Public DNS (IPv4)" and the corresponding value will be the hostname to substitute for <Public DNS (IPv4)> in the above scp syntax

   • At this point, you should know how to use scp and understand the associated permissions issues enough to be able to follow the remaining instructions in Directive 9. If you believe that you do not understand these concepts well enough, please practice them before continuing, as you will be editing the filesystem of the live isenseproject.org server in real time, and your changes will be reflected on the website instantly.

   • WARNING: From this point onward, be extremely careful with your actions. If you unsure about what to do, or are confused about the process, work alongside someone else or ask a knowledgeable person about what you are trying to do before executing a command. Any "rm"s will PERMANENTLY DELETE files on the LIVE SERVER

   • Comfortable? Good, let’s proceed

   • Upload the <long-hexadecimal-string>.txt file to /var/app/current/public

   • Open the file /var/app/current/config/routes.rb for editing

   • Under the line Rsense::Application.routes.draw do, add this route directive (indented by two spaces):

   get '/.well-known/pki-validation/<long-hexadecimal-string>.txt', :to => redirect('<long-hexadecimal-string>.txt')

   • The author of this guide recommends adding a comment above this line that explains the purpose of the directive (A ‘#’ followed by a text string until a line break), but it is not necessary for the validation to work.

   • Restart puma (our ruby application server) using the following command while ssh’d into the ec2 instance:

   sudo bash ~/restart_puma.sh

   • Attempt to access the new resource at https://isenseproject.org/.well-known/pki-validation/<long-hexadecimal-string>.txt

   • If the above instructions do not work, please reread them or ask a senior ECG member about your error

10. Wait for IT to send you the certificate

11. Download the files that are sent by IT

    • In 2018, IT sent two files:

      1. A file containing the isenseproject.org certificate itself, hereafter referred to as <cert-isense>

      2. A file containing the certificate signing chain that validates <cert-isense>, hereafter referred to as <cert-intermediate>

    • The filenames were as follows:

      1. <cert-isense> was called isenseproject_org_cert-file

      2. <cert-chain> was called isenseproject_org_intermediate-file

12. Concatenate the two files

    • Cert file above intermediate file

    • Take care that the line breaks are correct

    • In 2018, cat <cert-isense> <cert-intermediate> > <output-filename> produced an invalid file: There was a line break missing between end of the first certificate (from <cert-isense>) and the beginning of the certificate chain

    • It looked like this:

      -----END CERTIFICATE----------BEGIN CERTIFICATE-----

    • Instead of the this:

      -----END CERTIFICATE-----

      -----BEGIN CERTIFICATE-----

    • The above is the correct format

    • This error can easily be fixed manually using your text editor of choice

13. Redirect the output to a file named cert_and_chain.pem (substitute that name for <output-filename>) and replace the old one in the directory specified in /etc/nginx/nginx.conf, (ex./home/isense/ssl/) on the isense server

14. Replace the old cert_and_chain.pem on s3 in the isense-ssl bucket so it is placed into the correct location on deploy (see deploy.rb located at isenseDev/rSENSE:/.ebextensions in the repository)

15. Restart nginx (A buffer server between user requests and puma)

    sudo service nginx restart

    • If there are errors, this command will produce output letting you know

16. Visit https://isenseproject.org and check the certificate validity status in the top left of the browser, on the far left of the URL bar

17. Feel good about a job well done :)