TLS Certificate Procedures for Eyeglass

Introduction

This guide covers replacing the TLS certificate used by the Eyeglass appliance web UI, either with a newly generated self-signed certificate or with a certificate signed by an internal or external Certificate Authority (CA).

Quick Replace: Generate a New Self-Signed Certificate

caution

This only replaces the main port 443 certificate. If you also need to replace the certificate used for websockets and the web UI, follow the external CA signing procedure below instead.

note

There will be a service interruption on Eyeglass while this procedure is performed.

1. SSH to Eyeglass as admin (default password 3y3gl4ss).
2. Elevate to root:

   sudo su
   (default password 3y3gl4ss)
3. Stop the services:

   systemctl stop sca
   systemctl stop lighttpd
4. Move the old key aside:

   mv /opt/superna/sca/.secure/ssl.pem /tmp/ssl.pem.old
5. Generate the new self-signed certificate:

   /opt/superna/bin/create_ssl_keys.sh /opt/superna/sca/.secure/ssl
6. Fix ownership:

   chown sca:users /opt/superna/sca/.secure/*
7. Restart the services:

   systemctl start sca
   systemctl start lighttpd

Using an Internal or External Certificate Authority

Option A: Create a CA Root Certificate on the Eyeglass Appliance

Use this option if you don't have an existing external CA and want to sign the certificate without one.

1. SSH to Eyeglass as admin, then sudo -s.
2. Create a working directory:

   mkdir -p /opt/ca
   cd /opt/ca
3. Create the root CA key:

   openssl genrsa -passout pass:foobar -out rootCA.key 2048
   Change the passphrase and store it — it's needed to sign certificates in the future. To have clients/browsers trust certificates issued by this root, install rootCA.pem in each client's trusted certificate store.
4. Self-sign the root CA certificate:

   openssl req -x509 -new -nodes -key rootCA.key -days 3650 -out rootCA.pem
   You'll be prompted for organization details (country, province, city, etc.). -days 3650 sets a 10-year validity — adjust as needed.
5. Create the appliance private key:

   openssl genrsa -out eyeglass.key 2048
6. Create the certificate request:

   openssl req -new -key eyeglass.key -out eyeglass.csr
   You'll be prompted for environment details (country, city, company, email) and can optionally set a passphrase.
7. Sign the request with the root CA:

   openssl x509 -req -in eyeglass.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out eyeglass.cer -days 365
   Adjust -days to control the certificate's validity period. Verify it with:

   openssl x509 -in eyeglass.cer -text -noout
8. Continue with Installing a Signed Certificate below.

Option B: Request a Certificate from an External CA

Use this option if your organization has an external CA server.

1. Create a config file at /tmp/iglscert.cnf on the Eyeglass appliance:

   [ req ]
   default_bits = 2048
   prompt = no
   encrypt_key = no
   default_md = sha256
   distinguished_name = dn
   req_extensions = v3_req
   
   [ dn ]
   CN = iglscert.superna.local
   emailAddress=support-team@superna.net
   O = SUPERNA
   OU = Support Team
   L = Ottawa
   ST = Ontario
   C = CA
   
   [ v3_req ]
   subjectAltName = @alt_names
   
   [ alt_names ]
   DNS.1 = iglscert.superna.local
   DNS.2 = *.superna.local
   note

   CN should be the appliance's FQDN. alt_names should match the appliance's FQDN — using a wildcard (*.domain) is common. You can also add IP.1=<x.x.x.x> here if the appliance needs to be reachable by IP address.

2. Generate the CSR and private key:

   openssl req -new -config /tmp/iglscert.cnf -keyout /tmp/iglscert.key -out /tmp/iglscert.csr

3. Verify the CSR:

   openssl req -text -noout -verify -in /tmp/iglscert.csr

4. Submit the CSR to your CA (Windows Server CA or other) to be signed. The signed certificate must be in Base-64-encoded X.509 (.cer) format. See Signing with a Microsoft CA Server below for an example (consult your CA vendor's documentation for the exact steps).

5. Copy the signed .cer file back to the Eyeglass appliance (e.g. via WinSCP).

6. Continue with Installing a Signed Certificate below.

Installing a Signed Certificate

1. Confirm you have the signed certificate in .cer format, along with its matching private key (.key).
2. SSH to Eyeglass as admin, then sudo -s, and copy the certificate file onto the appliance (e.g. via WinSCP).
3. If you used the Eyeglass Root CA procedure (Option A):
   • Confirm you're root: whoami
   • Verify the certificate format:

     openssl x509 -in /tmp/iglscert.cer -text
     caution

     If this returns "unable to load certificate," the file is not in CER format. Do not continue — all further steps will fail until the file is corrected.

   • Install the certificate:

     scacli replace-certificate --privateKey=/opt/ca/eyeglass.key --certificate=/opt/ca/eyeglass.cer
   • Skip to step 6 below.
4. If you used an external CA (Option B): convert the private key to PEM format:

   openssl rsa -in /tmp/iglscert.key -out /tmp/iglscert.pem
5. Replace the existing certificate:

   scacli replace-certificate --privateKey=/tmp/iglscert.pem --certificate=/tmp/iglscert.cer
6. Navigate to the certificate directory:

   cd /opt/superna/sca/.secure
7. Back up the existing certificate file:

   mv ssl.pem ssl.pem.orig
8. Concatenate the new key and certificate into the combined file lighttpd expects:

   cat ssl.pem.orig ssl > ssl.pem
9. Fix ownership:

   chown sca.users /opt/superna/sca/.secure/*
10. Restart the services:

    systemctl restart lighttpd sca
11. Log in to the Eyeglass web UI using the appliance's FQDN and verify the certificate details and expiry in your browser. The FQDN used to access Eyeglass should match the value set in the CSR's alt_names.

Signing with a Microsoft CA Server

If you're using a Microsoft Certificate Authority to sign the request:

1. SSH to Eyeglass as admin, then sudo -s.
2. Display the CSR contents:

   cat /tmp/iglscert.csr
3. Copy the output into a new file named iglscert.req on a machine with access to the Microsoft CA management console.
4. In the CA console, right-click the CA server name and select Submit New Request, then browse to iglscert.req and submit it.
5. Open the Pending Requests folder for the CA.
6. Right-click the pending request, choose All Tasks, then Issue.
7. Open the Issued Certificates folder, find the issued certificate, and double-click it to view details.
8. On the Details tab, click Copy to File to launch the Certificate Export Wizard.
9. Select Base-64 encoded X.509 (.CER) as the export format.
10. Save the file as iglscert.cer, then follow Installing a Signed Certificate above.