Page Comparison

- [Introduction](#introduction)
  - [Some Background](#some-background)
- [Converting a .pfx Certificate File to a .crt & .key File Pair](#converting-a-pfx-certificate-file-to-a-crt--key-file-pair)
- [Obtaining an SSL Certificate from the Windows Certificate Store](#obtaining-an-ssl-certificate-from-the-windows-certificate-store)
- [Renewing the Certificate](#renewing-the-certificate)
- [Troubleshooting](#troubleshooting)

## Introduction
The [Ayfie Locator Installation Guide](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2400714758/Ayfie+Locator+Installation+Guide) lists the following requirements for an SSL certificate that is not from Let's Encrypt:
> - two PEM formatted files, \<name\>.crt and \<name\>.key.
> - the \<name\>.crt has Gateway Hostname set in the Subject Alternative Name attribute. This applies even if there technically are no alternative names.
> - the \<name\>.key has an unencrypted private key.

The command `openssl x509 -text -noout -in <name>.crt` can be run to inspect the certificate file and determine if the Gateway Hostname has been added or not to the Subject Alternative Name atribute.

This documentation describes how to produce the two files if the certificate has already been stored in the Windows Certificate Store, or if the certificate is available in another format then what the Saga platform requires.

### Some Background
SSL certificates formats are defined by the X.509 standard. They come in two main formats, binary and ASCII, which then again have sub formats as shown below.
* X.509 Certificate Formats
  * ASCII (base64 encoded)
    * PEM
      * *.pem* - the server certificate, the intermediate certificate and the private key in a single file.
      * .cre, .crt, .key - the server certificate, the intermediate certificate and the private key, each in separate files.
      * .crt, .key - the server certificate and any intermediate certificate in one file and the private key in another. **This is the option that Ayfie uses.**
    * PKCS#7
      * *.p7b* or *.p7c* - contains only the certificate, not the private key.
  * Binary
    * DER
      * *.der* or *.cer* - formats used by Java-based web servers.
    * PKCS#12
      * *.pfx* - extension used by Windows for binary format that stores the server certificate, the intermediate certificate and the private key in a single file.
      * *.p12* - extension used by Netscape for the very same format as .pfx.

## Converting a .pfx Certificate File to a .crt & .key File Pair
One way to convert from .pfx file format to the .crt/.key file pair format used by Locator, is to use the *openssl* tool. The tool can be downloaded independently, but is also comes as part of other software packages such as *Cywin* and *Git Bash*. The instructions below are based on using the *openssl* tool that comes with Git Bash.

Open up a *Git Bash* terminal and issue the commands below. Make sure to replace `<CERTIFICATE.PFX>` with the actual name of your .pfx file in the first and in the last line.

```
> winpty openssl pkcs12 -in <CERTIFICATE.PFX> -nocerts -out certificate-encrypted.key
> winpty openssl rsa -in certificate-encrypted.key -out certificate.key
> winpty openssl pkcs12 -in <CERTIFICATE.PFX> -clcerts -nokeys -out certificate.crt
```
Comments to the lines above:

* **Line 1** - One will be prompted for the .pfx file password. If one obtained the .pfx file using the instructions given in the next section, then the requested password is the one that was created in step 8. One will also be asked to provide a new password for the PEM passphrase that will be used on the next line (and then never again). The output of this first line is the file *certificate-encrypted.key* that is the input value of the second line.

* **Line 2** - One will be prompted for the password that one created in the first line.

The file output of line 2 (certificate.key) and line 3 (certificate.crt) are the two SSL certificate files required by Locator. The HTTPS section of the [Ayfie Locator Installation Guide](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2400714758/Ayfie+Locator+Installation+Guide) explains where these files are to be copied.

## Obtaining an SSL Certificate from the Windows Certificate Store
The following procedure describes how one can extract an SSL certificate in the form of a .pfx file from a Windows Certificate Store.

1. On the Start menu click **Run** and then type **mmc**.
2. Click **File > Add/Remove Snap-in**.
3. Click **Certificates > Add**.
4. Select **Computer Account** and then click **Next**. Select **Local Computer** and then click **Finish**. Then click **OK** to close the popup window.
5. Click the **+** (can be a > as well) to expand the certificates (local computer) console tree and look for the personal directory/folder. Expand the certificates folder.
6. Right-click on the certificate you want to backup and select **ALL TASKS > Export**.
7. Choose **Yes, export the private key** and **include all certificates in certificate path if possible**.
Warning: Do not select the delete private key option.
8. Leave the default settings and then enter any password of your choice to be used with the file (in this context, the password will only be needed one time later if/when converting the file to a .crt/.key file pair as described in the section above).
9. Specify the path of the file to which the certificate is to be saved and then click **Next** and then **Finish**. You should receive an "export successful" message. The .pfx file is now saved to the location you selected.

The **Yes, export the private** key option may be grayed out if the System and Administrator accounts do not have sufficient permissions or the Administrators group does not have ownership of the *%SystemDrive%\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys* folder.

## Renewing the Certificate

CA issued SSL certificates have a maximum validity of 13 months. When (or preferably before) the certificate expires, it needs to be replaced. That is done by overwriting the old .crt and .key files with the new ones and then restarting Saga. The location of the files is given in the *HTTPS* section of the [Installation Guide](https://ayfie-dev.atlassian.net/wiki/spaces/SAGA/pages/2400714758/Ayfie+Locator+Installation+Guide). Once the files have been replaced, restart Saga.

## Troubleshooting

- If the browser displays the error `NET::ERR_CERT_COMMON_NAME_INVALID` when accessing Saga, then the most likely cause is that the Gateway Hostname has not been set in the Subject Alternative Name attribute. Use the command `openssl x509 -text -noout -in <name>.crt` to inspect the certificate.