SSL Certificates

SSL certificates are important features of a publicly facing CirrusPrint server.  They are available from many third party issuers, and implementers can place certificate files anywhere that the CirrusPrint service user can read them.  To specify the location of certificate files, use the browser interface Configuration or Companies pages.  Optionally, you can apply them with a cp30s command line.  In the absence of a publicly issued certificate, CirrusPrint generates a self-signed certificate. In a local network installation this may be considered satisfactory, but in a publicly accessible installation, a public certificate is preferred.

Public certificates are linked to one or more domain names.  A site certificate for CirrusPrint must include the domain name referenced in the External URL configured in the Configuration page of the CirrusPrint Administration interface.

Certificate Management

You can obtain certificates from a third party issuer and place them on the CirrusPrint server.  The server then needs to be told where tthe certificate and key files are.  Often there is a certificate chain file, and if so that is the file to configure CirrusPrint to use.  There is a site certificate level and there are optional company-specific certificate if they reach the server using a different domain.  You can configure the path to the certificate and key files using the Administration interface, or with a command line:

cp30s -installcert -certfile path-to-cert-chain-file -keyfile path-to-key-file [-global] [-compid compid]

The optional -global argument will store the paths in the data/gconfig.ini file, so that the same path can be used by multiple systems sharing the same configuration.  Without -global, the paths are stored in config.ini and are specific to the local system.

The optional -compid compid argument will cause the paths to be stored in the company record, not the config.ini or gconfig.ini files.

Note in the command line syntax above, the square brackets indicate optional arguments and are not part of the syntax.

In both cases, the CirrusPrint user must have read access to the two files.  On Linux, this is the cp30s user.  On Windows it is normally the local system account, but that can be changed by modifying the service properties.  Note this service user is generally different than the user running this command line, so permissions might require adjustment.

Let's Encrypt

An alternative third party issuer is Let's Encrypt (https://letsencrypt.org), which provides free certificates.  CirrusPrint can configure and utilize LetsEncrypt SSL certificates with the help of two third-party tools: acme.sh for Linux and win-acme for Windows.  Both are command line tools that must be executed as root or admin users to properly update system and CirrusPrint configuration items.

There are some system requirements that must be satisfied in order to obtain LetsEncrypt certificates:

•The CirrusPrint server must be publicly accessible with a domain or sub-domain name.  This requires a static public IP address and a DNS A record that points to it.

•The CirrusPrint server's Configuration screen must have this domain in its External URL setting.
 

•The CirrusPrint server must be configured to listen on ports 80 and 443.  This means there cannot be another web server listening on those ports.
 

•An email address is required to register with LetsEncrypt.  This address is used to send notifications related to the certificates issued, such as upcoming expiration in case there are failed renewal attempts.

When using automated SSL generation tools like Let's Encrypt, beware of high availability installations where the challenge data might be stored on a different system than the challenge check actually connects to.  It could be easier to manually control certificate installation in this case.

Linux - acme.sh

The acme.sh program must be installed for the root user.  Their documentation indicates this isn't required, but in order for the CirrusPrint user to access the certificates, they must be obtained by the root user so that they can be placed and configured in the /home/cp30s directory.  Here is how you can install it as the root user, using your email address as the registered email:

sudo su -c "curl https://get.acme.sh | sh -s email=your-email"

Once it is installed, it is simple to obtain a certificate:

sudo cp30s -lecerts /root/.acme.sh/acme.sh [-global]

This will run the acme.sh script and set up the certificates for the External URL domain.  Look for a success message on screen, then restart the CirrusPrint server.  The acme.sh program should manage certificate renewals automatically.  

If the -global option is supplied, the certificate path is stored in the data/gconfig.ini file rather that config.ini.  This enables a high-availability configuration to share a certificate generated and maintained on one machine and be used by other machines sharing the same data path.  The machine that obtains the certificate is considered the primary machine, and it will create encrypted copies of its certificate in the shared data path for use by the other machines.

For detailed status displays of the acme.sh process as it runs, you can set debug=1 in the data/gconfig.ini file.

For reference, here is the acme.sh web site: https://github.com/acmesh-official/acme.sh

Windows - win-acme

You can download win-acme from their website: https://www.win-acme.com.  The download is a zip file that you can extract somewhere on the CirrusPrint server.  In the extracted folder will be an executable wacs.exe.  This is what will manage the certificates.

To install the certificate for the configured External URL, open a command window with Run as Administrator.  You must use this method for wacs.exe to have permission to set up the scheduled task required for automatic renewal.

Change to the CirrusPrint folder (i.e. C:\SDSI\cp30\server), then run this command using a full path to wacs.exe and your email address:

cp30s.exe -lecerts \path\to\wacs.exe -email your-email