|Purchasing and Installing a Digital Certificate|
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.
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.)
|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…
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…
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.
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.
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.