Product
Support
Everything Else
Purchasing and Installing a Digital Certificate
Introduction

Although it is beyond the scope of this technote to explain the many ways of acquiring and installing a digital certificate, here are some notes we made during the testing process. This information tends to go out of date on a fairly regular basis, so they may or may not be useful to you.

Certificates can be purchased from a variety of vendors. If you have already registered a domain name, your domain name managerment vendor is most likely the best place to go, as they can provide ‘one stop’ shopping and can sometimes save a few steps in the process.

If you need help acquiring or installing a digital certificate, QSA ToolWorks technical support is available to assist with this process at our standard support rates. Through Autograph Systems, QSA ToolWorks can offer certificates from RapidSSL, GeoTrust, Symantec, Thawte, and Comodo at a discounted price. (About 25% off most certificates.)

Acquiring and Installing a Certificate in macOS Server
Purchasing macOS Server

Although not required, purchasing and installing Apple’s macOS Server application can make the process somewhat easier, particularly if you intend on using the server for other purposes.

Purchase macOS Server (for El Capitan and Sierra) via the App Store.

Once purchased, the ‘Server.app’ application is installed in your Applications folder, from where you launch it as you would any application.

Getting a Certificate

The process starts with the creation of a ‘Certificate Signing Request’ (CSR). In macOS Server.app, you do this by clicking on Certificates in the left hand column, then choosing Get a Trusted Certificate… from the menu shown in the image on the right.

Server.app walks you through the process of generating a CSR, providing labeled fields for filling in the critical information. At the end, the CSR is created that can be copied to the clipboard or saved to a file.

At this point, Server.app shows your new certificate in the list of certificates, with an expiration date of ‘pending’ and will not actually work until…

The CSR must now be submitted to a ‘Certificate Authority’ (CA), which typically follows up with an email back to the owner of the domain, asking for verification that this is a legitimate request. After verification, it can take anywhere from a few minutes to a few days for the certificate to be approved. In the end, the CA will inform you that the certificate has been issued, and provide instructions for downloading it.

Importing a Certificate

Once the certificate has been received, installing it is a simple* matter of double clicking on the ‘pending’ line for the certificate (in Server.app) and following the instructions in the dialog.

*We qualify the ‘simplicity’ of this process by saying that although the process is indeed simple, it is sometimes mind-numbingly, hair-pullingly confusing process of getting the certificate in the right format, with the right extension, and containing the right ‘intermediate certificates’ — if any are required at all! Instructions found on the internet range from ‘close’ to just plain wrong, and even the best become obsolete as both Apple and the security world at large make changes to stay ahead of the hackers who are constantly working to break the encryption being used today.

When the certificate is correctly installed, Server.app shows both the ‘issuer’ (the CA) and the expiration date of your certificate. Double clicking on the certificate now reveals additional details about the certificate, including its validtity and encryption methods.

Acquiring and Installing a Certificate in macOS
Getting a Certificate

Without macOS Server, you must manually manage the entire process of creating a ‘Certificate Signing Request’ (CSR) and installing the ‘Private Key,’ Certificate, and any Intermediate Certificates that may be required. This page is provides an overview of this process. (It is not a detaied guide.)

  1. Generate a Private Key: Without macOS Server, you use “Terminal.app” and the openssl command to generate a private key. Without detailing the options in openssl, here is the command we use to generate our private keys:

    openssl genrsa -out ~/Desktop/named_private.key 4096

    This creates a file on your Desktop (as per the ~/Desktop/ part of the path supplied to the -out parameter) that contains your Private Key. You can name the file as you wish*, but be sure to use the .key extension.

    *Avoid using spaces; they make life difficult!

    Make sure the key is stored in a secure location! If anybody gains access to your Private Key, your security is compromised.

  2. Generate a Certificate Signing Request: The Private Key is used to generate your CSR, the work being done again in Terminal.app:

    openssl req -new -key ~/Desktop/named_private.key -out ~/Desktop/named_request.csr

    This creates a file (on your Desktop) that contains your CSR. Name the file as you wish, but for sanity’s sake, be sure to use the .csr extension.

  3. Follow the instructions from your certificate vendor. Most likely, this will involve copying and pasting the contents of the .csr file into a form. If so, open the .csr file just created using a text editor — we recommend BBEdit — and copy the entire contents of the file.

    Do not send the contents of your Private Key file!

  4. Your vendor will follow up with an email, asking for verification that this is a legitimate request. After verification, it can take anywhere from a few minutes to a few days for the certificate to be approved. In the end, the CA will inform you that the certificate has been issued, and provide instructions for downloading it, along with any Intermediate Certificates that may be required.

Installing a Certificate

All authoritative certificates follow a ‘chain of authority’ up to one of a handful of world-authoritative sources. macOS contains many, but not all, of the intermediate certificates that create an authorized chain. It may be necessary to add intermediate certificates to the keychain.

If an option to download a pkcs or p12 file is provided, this is the easiest option for macOS, as it contains your certificate along with any intermediate certificates you need in a single file. Otherwise, download your certificate (or copy/paste it into a text file) and save it with a .crt extension. Then…

  1. Launch Keychain Access, choose System and Certificates on the left
  2. Choose Import Items… from the File menu
  3. Import the .crt file
  4. Select the certificate to confirm that the system accepts it as valid.

If that fails with a complaint that the certificate can’t be verified, you may have to create a .p12 file containing everything the keychain needs to create a valid certificate…

  1. Save your certificate and the issuer’s intermediate certificate(s) in a single text file
  2. Use Terminal to create a .p12 file using this command:
    openssl pkcs12 -export -out named_file.p12 -inkey private.key -in named_file.crt
  3. Launch Keychain Access, choose System and Certificates on the left
  4. Choose Import Items… from the File menu
  5. Import the .p12 file
  6. Check the certificate to make sure it is valid
Verifying Installation
Keychain Access

You can verify that the certificate is installed correctly by checking it in the Keychain Access application (found in the Utilities folder).

In Keychain Access, choose System and My Certificates on the left, then select your certificate in the list, as shown in the image on the right. If the certificate is installed correctly, the upper right panel will show the basic information about the certificate along with a (green) checkmark next to the text “This certificate is valid.” If you see this, your certificate is correctly installed and recognized by macOS.

If the certificate is invalid or otherwise problematic, the message that appears here will hopefully guide you to resolving the issue. Contact your certificate vendor for assistance.

If the certificate is valid, but does not seem to work correctly, read on for some advanced troubleshooting suggestions.

Troubleshooting

This section is of use only if your system requires authentication when a Client connects to Helix Server. These suggestions may or may not resolve certificate issues.

The most frustrating issue we encountered when testing the secure Server was a situation where the certificate was installed correctly and shown as valid, but each time a Client attempted to connect to the Server, a dialog appeared (on the Server) requesting permission to access the keychain. That’s clearly an unacceptable way to run a Server.

To resolve this (and other issues you may encounter) it might be necessary to adjust the Access Control to the certificate. Open the disclosure triangle next to the certificate to show the private key. Open the private key, switch to the ‘Access Control’ panel, and set the access to ‘allow all applications to access this item’ and/or add Helix Server to the apps that are always allowed to access the key, a shown at right.

You may also be able to resolve issues by changing the ‘Trust’ settings for the certificate itself. Our limited experience is that setting ‘X.509 Basic Policy’ to Always Trust can resolve some issues.

Additional Notes
Self-Signed Certificates

Although it may be possible to secure a Server using a self-signed certificate, we do not recommend this, and we have no troubleshooting information appropriate to this situation. Our expectation is that although you may be able to secure a Server using a self-signed certificate, each time a Client connects they will be presented with a dialog warning then that the certificate is untrusted.

Secure connections to Helix Server is a new and largely uncharted area. If you gain any insights that may be of use to other Helix Server users, we encourage you to share your findings with us, for possible inclusion in an updated version of this technote.