================ SSL Certificates ================ Overview ======== AuthControl Sentry Appliances ship with a self-signed certificate which prompts users to accept a security warning when the TURing image or Sentry web interface is presented within a web browser. When an AuthControl Sentry system goes into production, a valid signed certificate from a Trusted Certificate Authority (CA) should be installed onto the appliance. This article describes how to install a valid certificate using the AuthControl Sentry Appliance. Prerequisites ============= * AuthControl Sentry Appliance with Console Management Interface (CMI) access (via SSH or console). * A valid DNS name for the AuthControl Sentry instance (usually pointing to the public IP address or VIP). * **Backup:** Ensure a backup of the existing keystore exists before making changes. Considerations -------------- **HA Appliances using VIP** For HA appliances, if a VIP (Virtual IP) is used, the certificate must be bound to the hostname that resolves to that VIP. Once a signed certificate is setup on the Primary appliance, the keystore can be copied to the Standby appliance. **NAT Address and Certificates** Where the AuthControl Sentry Appliance or HA VIP is behind a NAT, the DNS entry used for the public IP address is usually used as the hostname for the certificate. Installation Methods ==================== There are three methods to install a certificate on the AuthControl Sentry Appliance. Please choose the one that best fits your requirements: * **Method 1: Import Existing PFX (Recommended)** This method is faster and less prone to error. It involves using a complete certificate file (PKCS#12/.pfx) which may have been provided directly by your Certificate Authority, or exported from another server (e.g., Windows IIS). * **Method 2: Generate CSR via Appliance** This method involves creating a private key on the appliance, generating a request, and importing the individual certificate files returned by the CA. * **Method 3: Automated ACME Deployment (Roadmap)** ✨ Coming in 2026, this method will support the ACME protocol for automatic certificate issuance and renewal (e.g., Let's Encrypt). Method 1: Import Existing PFX (Recommended) =========================================== 1. Prepare the PFX File ----------------------- Ensure you have a valid ``.pfx`` (or ``.p12``) file. This file may have been provided directly by your Certificate Authority (CA) or exported from another server. It must contain: * The Private Key. * The Server Certificate. * The full Intermediate/Root Chain. 2. Upload to Appliance ---------------------- Use a tool like **WinSCP** or **FileZilla** (SFTP) to upload your ``.pfx`` file to the appliance folder: ``/backups/upload/`` 3. Import via CMI Menu ---------------------- 1. Log in to the CMI via SSH or Console. 2. Navigate to **Tomcat** > **Certificates**. 3. Select **Import / Roll Back to Previous Keystore**. .. image:: images/SSLCertificate/ImportRollbackMenu.png :alt: The Import or Roll Back Keystore menu options 4. Select **Import Keystore**. 5. The system will display the files located in ``/backups/upload/``. .. note:: If your file is not listed, select the **REFRESH DIRECTORY** option. The numbering of files may change as new files are added or removed. .. image:: images/SSLCertificate/ImportPFXFileList.png :alt: List of files in the backups upload directory available for import 6. Select the number corresponding to your PFX file from the list and press Enter. 7. Follow the onscreen prompts to complete the import (you may be asked for the PFX password). 8. Once the import is complete, proceed to **Restart Tomcat**. Method 2: Generate CSR via Appliance ==================================== Use this method if you do not have a PFX file and wish to generate the Private Key directly on the appliance. 1. Access Certificate Menu -------------------------- 1. From the CMI **Main Menu**, select **Tomcat**. 2. Select **Certificate Management**. .. image:: images/SSLCertificate/CertManagementMenu.png :alt: The main Certificate Management menu in CMI 2. Create a Local Certificate ----------------------------- 1. Select **Create a local Certificate**. 2. **Alias:** The default and recommended alias is ``swivel``. 3. **Keystore Password:** Default is usually ``lockbox``. 4. **Certificate Details:** * **First and Last Name (CN):** The **Hostname** or **FQDN** (e.g., ``sentry.example.com``). * **Organizational Unit, Organization, City, State, Country:** Enter your organization's details. .. image:: images/SSLCertificate/CreateLocalCertDetails.png :alt: Example of entering certificate details such as FQDN and Organization 3. Generate a CSR ----------------- 1. Select **Generate CSR**. 2. Enter the alias used above (``swivel``). 3. Download the generated CSR file from ``/backups/upload/.csr`` using WinSCP. 4. Apply for the Certificate ---------------------------- Submit the CSR to your CA, selecting **Tomcat** or **Java** as the server type. Download the certificate (Response) and the Root/Intermediate bundle. 5. Import the Certificate ------------------------- **Important:** You must import the certificates in the correct order: **Root/Intermediates first**, then the **Response**. **A. Copy Certificates to the Appliance** Upload your Root CA, Intermediate CA(s), and Server Certificate to ``/backups/upload/``. **B. Import Intermediate/Root Certificates** 1. In **Certificate Management**, select **Import to New / Existing Alias**. 2. The system will display the list of files. Select the number corresponding to your Intermediate or Root certificate. 3. When prompted to select an alias, type a unique **New Alias** name (e.g., ``intermediate1``). 4. Repeat this process for all intermediate and root certificates, giving each a unique alias. **C. Import the Server Certificate (Response)** 1. Select **Import to New / Existing Alias**. 2. Select the number corresponding to your Server Certificate file (Response) from the list. 3. When prompted, select the **Existing Alias** option. .. image:: images/SSLCertificate/ImportSelectAliasType.png :alt: Selecting Import to Existing Alias vs New Alias 4. Choose the alias corresponding to your private key (usually ``swivel``). Method 3: Automated ACME Deployment (Roadmap) ============================================= .. note:: **Roadmap Feature:** Support for the ACME standard is currently in development and scheduled for release in **2026**. Future versions of AuthControl Sentry will support the **Automated Certificate Management Environment (ACME)** protocol. This will enable appliances to automatically interface with Certificate Authorities such as **Let's Encrypt** to request, validate, and install trusted SSL certificates without manual intervention. This roadmap feature addresses the industry shift towards shorter certificate lifecycles and aims to provide: * **Zero-Touch Renewal:** Certificates will renew automatically before expiration. * **Simplified Validation:** Support for HTTP-01 and DNS-01 validation challenges. * **Cost Reduction:** Native integration with free, automated CAs. Please check the Swivel Secure release notes and announcements for updates on the availability of this feature. Final Steps (All Methods) ========================= Verify Keystore --------------- 1. Go to **Tomcat** > **Certificate Management** > **View Keystore**. 2. Check the ``swivel`` alias. 3. Ensure **Entry Type** is ``PrivateKeyEntry``. 4. Ensure **Certificate chain length** is greater than 1. Restart Tomcat -------------- For changes to take effect, restart the service: 1. Go to the **Tomcat** menu. 2. Select **Stop** then **Start** (or Restart). 3. Verify access via your browser (e.g., ``https://sentry.example.com:8443``). Exporting Certificate to Standby Appliance (HA) =============================================== In a High Availability (HA) pair using a VIP, generate/import the certificate on the Primary appliance, then copy the keystore to the Standby. 1. **Backup:** Backup ``/home/swivel/.keystore`` on the Standby. 2. **Copy:** Copy ``/home/swivel/.keystore`` from Primary to Standby (same location). 3. **Permissions:** Run the following on the Standby via Command Line: .. code-block:: bash chown swivel:swivel /home/swivel/.keystore chmod 600 /home/swivel/.keystore 4. **Restart:** Restart Tomcat on the Standby appliance. Troubleshooting =============== **"Public keys in reply and keystore don't match"** (Method 2 Only) You are importing a certificate onto an alias that did not generate the CSR. Ensure you strictly follow the "Import to Existing Alias" step on the correct ``swivel`` alias. **Certificate shows as "trustedCertEntry"** This means the private key is missing. * **Method 1:** The PFX import failed to map the key. Check the source alias. * **Method 2:** You likely imported the response as a "New Alias". **Restoring a Previous Keystore** If an import fails or breaks the service, you can roll back to a previous state: 1. Navigate to **Tomcat** > **Certificates**. 2. Select **Import / Roll Back to Previous Keystore**. 3. Select **Roll Back Keystore**. 4. Choose a backup file from the list to restore.