Go back to the procedure overview

IV. Create a Subject Alternate Name extension file

When creating a Server Certificate for your groov EPIC processor, you’ll need your Certificate Authority (CA) key ([myCertificateAuthority]-CA.key), the Client Certificate (CC) file ([myClientCertificate]-CC.pem), a Certificate Signing Request (CSR) from the groov EPIC, and a Subject Alternate Name (SAN) extension file [myEPIC]-SAN.ext.

Unlike the Certificate Authority (CA) key and Client Certificate (CC) which you create only once, the Subject Alternate Name (SAN) extension file and the Certificate Signing Request (CSR) files must be created for each individual EPIC.

This is a crucial step since the extension file is required for many clients such as Google Chrome. Set the SAN to be the hostname or static IP of each groov EPIC processor.

Note that you will need to use a persistent hostname or static IP address for the Server Certificate to work long-term. You must use the hostname if your groov EPIC processor is configured for dynamic IP addressing, since the IP address could change at any time. If the hostname or static IP address does change, a new Server Certificate will need to be generated and uploaded to the EPIC.

You can create the SAN file using any standard text editor. It’s important that the file has the correct .ext file extension.

Use the following text as a template for your SAN file, replacing [myEPIC] on the last line at DNS = with your groov EPIC’s hostname or static IP.

[myEPIC]-SAN.ext:

authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names

[alt_names]
DNS = [myEPIC]


Note: Make sure you replace the square brackets for the DNS, for example a hostname of epic-01-02-03 would look like this:

. . .
[alt_names]
DNS = epic-01-02-03


Top

V. Update and download the Certificate Signing Request (CSR)

A Certificate Signing Request (CSR) is a file created an SSL server that serves as an application for a certificate that will be provided by some Certificate Authority. In this case the groov EPIC processor is applying for a Server Certificate from your personal Certificate Authority so that it can be trusted by any clients that have the associated Client Certificate. The Certificate Signing Request contains two important sets of data: the encrypted public key and information about the server such as the business name, and the server hostname.

  1. In groov Manage navigate to the Security menu and click Server SSL.
  2. Select Create Certificate in the Certificate Management section and fill in the details. The Server Name and Country Code fields are required; others are optional but recommended:

    • Server Name (required) - This is the Fully Qualified Domain Name (FQDN), hostname, or static IP address of your groov EPIC processor. In most cases, you’ll simply enter the hostname of your EPIC here. If you’re not using DHCP and DNS, you’ll need to enter your static IP address.

      This is especially important if you have recently changed the hostname or static IP address of your groov EPIC processor. This field must exactly match the hostname or static IP used to access your EPIC. In most cases, this will simply be what is set in the System > Network menu; either the hostname of the device (for example epic-01) or the static IP address (for example 192.168.0.1). As well as updating the hostname or static IP address, creating a new CSR gives you the opportunity to change the key encryption length and expiration. Also, while the only required fields are Server Name and Country Code (US for the United States, see wordlatlas.com for other country codes), you may want to associate your groov EPIC processor with your organization, department, city, state, and country.

    • Email - Optional field for administrator’s email address, or whoever should be contacted for support regarding any problems with this certificate.
    • Department - This is the equivalent of the “Organizational Unit” used in creating the Client Certificate. Enter your department name or leave the field blank.
    • Organization - This should be the name of your company or reflect where the groov EPIC is installed. For example, “Opto 22”.
    • City or Locality - This should be the full city where the groov EPIC is installed. For example, “Temecula”.
    • State - The State should be written out in full, not abbreviated (for example, use “Washington” rather than “WA”.
    • Country Code (required) - Enter US for the United States, see wordlatlas.com for other country codes. You must enter a value for this field.
    • Expiration - The number of days the certificate will be valid for. Recommend leaving at 397 days or less due to certificate validity constraints.
    • RSA Key Size - This is the length (in bits) of the key encryption. Leave this at the default 2048, which is the value currently recommended by the National Institute of Standards and Technology (NIST).

  3. Once the fields are complete, click Create in the top right.

  4. You will see a popup stating “Generating CSR”, and once complete, a message saying that you need to restart groov Manage for the change to take effect. Click reload.

  5. Click Download CSR to download the updated Certificate Signing Request file to a folder on your computer. The resulting file will be named csr.pem. Confirm the file was created and take a moment to rename it to help keep track of your individual EPIC CSRs. A good choice is [myEPIC]-CSR.pem just replace [myEPIC] with the uniquely identifying hostname, serial number, or static IP of the EPIC you downloaded it from. Once you’ve confirmed the file download and renamed it, move it to the folder where your Certificate Authority, Client Certificate, and extension file ([myEPIC]-SAN.ext from step IV) are all stored.

Top

VI. Create a Server Certificate for each individual groov EPIC processor

You will need four files before you can create the Server Certificate (SC) file:

  1. [myCertificateAuthority]-CA.key: the Certificate Authority (CA) secure .key file and its associated passphrase. This is created in step I and is reusable for as many groov EPIC processors (servers) as needed.
  2. [myClientCertificate]-CC.pem: the Client Certificate (CC) .pem file that is created in step II, installed in step III, and is used to securely connect to multiple EPICs whose Server Certificates (SC) were created with this same file. This file will also be installed on client trusted certificate stores (operating systems or browsers).
  3. [myEPIC]-SAN.ext: the extension file for EPIC being signed, to set the Subject Alternate Name (SAN) made for a specific device in step IV.
  4. [myEPIC]-CSR.pem: the Certificate Signing Request generated from groov Manage on the groov EPIC processor for its specific hostname or static IP in step V.

It is recommended to keep the -suffixes in your file names to help keep track of which file serves what purpose: -CA (Certificate Authority), -CC (Client Certificate), -SAN (Subject Alternate Name extension file), -CSR (Certificate Signing Request) and -SC (Server Certificate).

At the command line, type the following, replacing [myEPIC] with your EPIC hostname for the CSR, Server Certificate (SC), and SAN extension file, as well as replacing [myCertificateAuthority] with your Certificate Authority (CA), and [myClientCertificate] with the chosen name of your Client Certificate (CC):

openssl x509 -req -in [myEPIC]-CSR.pem -CA [myClientCertificate]-CC.pem -CAkey [myCertificateAuthority]-CA.key -CAcreateserial -out [myEPIC]-SC.crt -days 397 -sha256 -extfile [myEPIC]-SAN.ext

After you enter the passphrase associated with [myCertificateAuthority]-CA.key, this command will create your new Server Certificate named [myEPIC]-SC.crt.

This command will also generate a serialized file [myClientCertificate]-CC.srl that will update itself for each additional generated Server Certificate associated with the Certificate Authority key and Client Certificate you provide.

Proceed to step VII and upload the Server Certificate.

Top

VII. Upload the Server Certificate

Use groov Manage to upload the newly created Server Certificate [myEPIC]-SC.crt to the groov EPIC processor.

  • Note: It is extremely important that you upload the correct Server Certificate (SC) to the groov EPIC processor it was created for.
    1. Open groov Manage
    2. Navigate to the Security menu and select Server SSL.
    3. Download the Private Key file key.pem from the groov EPIC processor by clicking Download Private Key
  • Note: You may want to rename this Private Key file to [myEPIC]-PK.crt to stay consistent with your file naming. It’s also helpful when uploading Server Certificates to multiple EPICs.
    1. Click on Upload Certificate
    2. Click on Public Certificate. (groov Manage uses the term “Public Certificate” for Server Certificates.)
    3. Choose your Server Certificate [myEPIC]-SC.crt from your file system and click OK
    4. Click Private Key
    5. Choose the key.pem _file you just downloaded from the _groov EPIC processor. If you renamed it as suggested above, it will be [myEPIC]-PK.crt. You can delete this file after you have completed this process.
    6. Skip the Intermediate Certificate button
    7. Click Upload at the top right
    8. You will be prompted to reload the page
    9. Click Reload and your connection will now be secure.
      • Note: If your connection does not immediately become secure you may need to restart your browser completely. If that does not work, try restarting your PC before attempting further troubleshooting.

Refresh to Complete the Process

At this point you can refresh your page and discard any previously made network exceptions as you will now have a valid, signed certificate with no insecure connection warning in Chrome and/or Firefox.

If you want any other devices to be able to securely visit this page you do not need to make any further changes to the EPIC SSL server, just install the CA certificate on the client device and you’re good to go. When you do give out the certificate file be sure not to give out the key as well, anyone who gets ahold of the key file can create and sign certificates that will be trusted by all clients that the associated CA certificate is installed on.

Top

Signing Additional CSR Files for More Devices

Once you have created the CA certificate and key, and put the files somewhere safe, you can repeat the signing and server SSL certificate update procedure without having to make and update a new trusted root CA. As long as the same key that signed your CA certificate is signing your device CSR’s you can have as many devices signed by the private CA as you want.

All you need to do is follow the steps on only this page, you can skip the preceding pages on creating the Certificate Authority (CA) and create and install the client certificate since you can reuse those files again when you repeat this process.

Also, you can add new clients to all of those devices by simply adding the CA certificate to the device’s trusted root store, then that client can freely visit all servers that have a certificate signed by your CA key. Keep in mind that if your key gets out then the Certificate Authority will not be trustworthy any more, and you would need a new CA and use that to re-sign all your server CSR’s as well as uploading new client CA certificates.

It is crucial that you keep your Certificate Authority key secret and safe.

Top

Go back to creating the Certificate Authority (CA) (step I), or create and install the client certificate (steps II & III), or the procedure overview

Or go to EPIC Developer Overview Home