SSL/HTTPS Key Generation

SSL/HTTPS Key Generation
Prev	Appendix A. Tools (Advanced)	Next

Configuring SSL can be a confusing experience of encryption keys, certificates, protocols and formats. During the install process, PaperCut NG generates an self-signed key/certificate issued for the host's machine name. This key is used by default when the system is accessed via HTTPS on port 9192.

The default SSL certificate provides good security, however there are two downsides to using a self-signed certificate:

When users access the HTTPS site using a fully-qualified domain name, the browser will issue a "Domain mismatch warning". To avoid this warning, re-create the self-signed certificate with the machine's fully qualified domain name, see the section called “Re-create the self-signed certificate”.
The browser will also warn the user that the certificate is not signed by a trusted authority. To overcome this you must use a certificate signed by a trusted authority, see the section called “Using a custom/or signed SSL Key”.

Eliminating these warnings provides a smoother experience for the end users of PaperCut NG.

Re-create the self-signed certificate

The tool create-ssl-keystore can be used to re-create the key/certificate (stored in a keystore file) for a different hostname eliminating the browser domain mismatch warning. An example of the command's use:

    cd [app-path]/server/bin/win
    create-ssl-keystore -f "myserver.fullname.com"

More information is available via the --help command line option.

Usage: create-ssl-keystore [-f] [-k FILE] [SYSTEM_NAME]

   -f        Force. Overwrite any existing keystore file.

   -k FILE:  Define a keystore file location. If not set the keystore 
             is created in the default location 
             (server/data/default-ssl-keystore).

   SYSTEM_NAME: The name of the computer/server used to generate keystore.
                If not defined, the current computer name is used.

Using a custom/or signed SSL Key

Large organizations may wish to use their own SSL key signed by a trusted certificate authority (CA). Such trusted CAs include: AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, beTRUSTed, amongst others. The advantage of a signed certificate is that it eliminates the browser warning, "The security certificate presented by this website was not issued by a trusted certificate authority."

Caution

Configuring SSL and generating signed keystores is complex! The following documentation assumes that the reader has a good understanding of the SSL/HTTPS process and has configured SSL on other web based application servers such as Apache, IIS, or secured mail servers.

A good summary of the process of generating a PaperCut NG compatible certificate keystore is explained in detail on the Jetty HTTP Server website at: http://jetty.mortbay.org/jetty5/faq/faq_s_400-Security_t_ssl.html.

To configure the PaperCut NG Application Server to use the new key/certificate:

Copy your signed keystore onto the server running the PaperCut NG Application Server. The suggested location is in the directory [app-path]/server/custom/.
Open the file [app-path]/server/server.properties with a text editor (e.g. Notepad).
Locate the section titled SSL/HTTP Configuration
Remove the # (hash) comment maker from all server.ssl lines.

Define the location of your keystore and the keystore and key password. The file should look something like this:

    server.ssl.keystore=custom/my-ssl-keystore
    server.ssl.keystore-password=mypassword
    server.ssl.key-password=mypassword

Restart the PaperCut NG Application Server and verify all is working. If the server fails to start, error messages will be recorded in logs located in the server's logs directory.

Prev	Up	Next
The XML Web Services API	Home	User Client Options