SSL/HTTPS Key Generation

During the install process, PaperCut NG generates a 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:

  1. 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”.

  2. The browser will also warn the user that the certificate is not signed by a trusted authority. To overcome this you must obtain a certificate signed by a trusted authority, see the section called “Creating and installing a purchased SSL Certificate”, or if you already have one, see the section called “Importing an existing SSL key”.

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

In this section we detail how to recreate the self-signed certificate, use your own SSL certificate and further customise the SSL certificates that you want to use. This is a technically complex area and there is an assumed level of experience with SSL certificates in general.

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.

Caution

For backwards compatibility with 3rd party systems the default self-signed certificate is generated with a SHA1 algorithm. See the section called “Can I use other algorithms such as SHA2/SHA256?”

Creating and installing a purchased SSL Certificate

Large organizations may wish to use their own SSL key signed by a commercial certificate authority (CA) that is recognized by all popuplar web browsers including Internet Explorer, Mozilla Firefox, Safari and Chrome. A complete list can be found in Windows under Control Panel > Internet Options > Content > Certificates > Trusted Root Certification Authorities.

Some large organizations also operate a certificate authority of their own that is recognized by their users' web browsers by way of a root certificate that has been installed into all users' web browsers in a manual or automated way.

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."

If you are already in posession of a signed SSL key and certificate for the domain name of the PaperCut application server please see the section called “Importing an existing SSL key” below.

The following steps will cover the following high-level steps:

  • Create the SSL keystore and create the private key

  • Create the Certificate Signing Request (CSR)

  • Send the CSR to your Certificate Authority

  • Receive your signed certificate

    Optionally you will receive one or more intermediary certificates that will need to be installed as well

  • Install any intermediary certificates and then your new certificate

  • Restart the PaperCut NG Application Server and confirm that everything is working as expected

To create your own SSL key and have it signed by a commercial or intra-organizational certificate authority you can use the 'keytool' tool supplied in the directory [app-path]/runtime/jre/bin.

  1. Open a command prompt window and change to the directory [app-path]/runtime/jre/bin. Any existing files called 'my-ssl-keystore' in this directory are likely leftovers from previous attempts and need to be renamed or deleted at this point.

  2. Enter this command to produce the SSL key:

    keytool -keystore [app-path]\server\custom\my-ssl-keystore -alias jetty -genkeypair
        -keyalg RSA

    Caution

    This process creates a 'my-ssl-keystore' file. Don't lose this file! You will need it when adding the public key later.

    We recommend making a copy of this 'my-ssl-keystore' and keeping it in a safe place. If it is lost or changed, your certificate will need to be re-issued, often resulting in costs from your Certificate Authority.

    If you are renewing your SSL certificate, please review the section called “Renewing your SSL certificate”

    As keystore password choose 'password' or another simple password as it is not very important. Enter the same password again later when asked for a key password.

    Note: Some organizations require larger key sizes than the default 1024 bit. In this case add the "-keysize 2048" or "-keysize 4096" parameter to the end of the above command line.

    You will be asked a series of questions. Enter the exact fully-qualified domain name of the PaperCut NG Application Server where it asks you for "first and last name". The server name must be the exact one that users will enter into their browsers to access PaperCut NG's web interface, e.g. 'printing.myschool.edu'. Depending on the certification authority's requirements you may also need to fill in some of the other fields.

    Enter keystore password:  password
    What is your first and last name?
      [Unknown]:  printing.myschool.edu
    What is the name of your organizational unit?
      [Unknown]:  
    What is the name of your organization?
      [Unknown]:  
    What is the name of your City or Locality?
      [Unknown]:
    What is the name of your State or Province?
      [Unknown]:
    What is the two-letter country code for this unit?
      [Unknown]:
    Is CN=printing.myschool.edu, OU=Unknown, O=Unknown,
    L=Unknown, ST=Unknown, C=Unknown correct?
      [no]:  yes
    
    Enter key password for <jetty>
            (RETURN if same as keystore password):  password

  3. Prepare your new SSL key for certification by the certificate autority:

    keytool -certreq -alias jetty -keystore [app-path]\server\custom\my-ssl-keystore
        -file [app-path]\server\custom\jetty.csr

    The contents of the resulting jetty.csr can be pasted into the online order forms of abovementioned commercial certificate authorities or passed to your organization's own certificate authority.

    When the certification process has completed, the authority will provide you with a certificate file that can be downloaded from the autority's web site. The filename will usually end in .crt, .cer or .cert. The contents of the file should look something like this:

    -----BEGIN CERTIFICATE-----
    MIIDLTCCApagAwIBAgIQJc/MOTjAW0HrPI/4rGtDCDANBgkqhkiG9w0BAQUFADCB
    hzELMAkGA1UEBhMCWkExIjAgBgNVBAgTGUZPUiBURVNUSU5HIFBVUlBPU0VTIE9O
     ... more here ... 
    Awjhfz9EfxN2l1UYP15xZZyNO4DO3X/LliCG9pdFf4hUHl8tRnhQBvRR1F0v9UHB
    PC6L9jNjMbQUoQ9NG/S8Nn7ZcSHNy+P53ntIBaEfTv7+qvXNWvSb5wj4pd05wGF1
    Bw==
    -----END CERTIFICATE-----

    Save the file as jetty.crt.

    Caution

    If you have not already, take the opportunity now to backup your my-ssl-keystore at this time.

  4. Before you can make use of your newly obtained certificate, you may have to import the certificate authorities "root certificate". PaperCut comes with a number of root certificates pre-installed that you can list using this command (still from the directory [app-path]/runtime/jre/bin as above):

    keytool -keystore ../lib/security/cacerts -storepass changeit -list

    Add the option "-v" at the end to obtain the same list with more details, such as expiration dates.

    If your certificate authority is not listed there, or you have been notified that they have recently started using new root certificates, then you need to first import the certificate authority's root certificate into your keystore before importing your newly obtained own certificate. The CA's root certificate will usually be available for download on the CA's web site as a file ending on .pem or .crt. Save the file using a filename indicative of the CA's name, e.g. globaltrust.pem. Import the root certificate using this command, specifying an alias that is indicative of the CA's name (type this all in one line):

    keytool -keystore [app-path]\server\custom\my-ssl-keystore -importcert -alias globaltrustroot 
        -file globaltrustroot.pem

    When asked whether to trust this certificate, answer yes:

    Trust this certificate? [no]:  yes

    Some certificate authorities also provide additional "intermediate certificates" that will have to be imported the same way as the root certificate. You should use a different alias each time. For example:

    keytool -keystore [app-path]\server\custom\my-ssl-keystore -importcert -alias globaltrustinter 
        -file globaltrustinter.pem

  5. Now you can import your own certificate previously saved as jetty.crt (type this all in one line):

    keytool -keystore [app-path]\server\custom\my-ssl-keystore -import -alias jetty
        -file jetty.crt -trustcacerts

    Caution

    The 'my-ssl-keystore' in the above command is the original my-ssl-keystore you created in step 2.

  6. Your new keystore file my-ssl-keystore is now ready and should be moved to the location [app-path]/server/custom.

Now that you have your keystore file, follow the instructions in the section called “Configuring PaperCut to use the new certificate” to install it and start serving up your new SSL certificate.

Importing an existing SSL key

If you have an existing SSL key with certificate you can import it into the PaperCut NG keystore. Reasons for having an existing signed key include:

  • You have obtained an SSL key specifically for use with your PaperCut NG Application Server using a method other than using 'keytool' as described above. As a result you have – on Windows – a certificate with an attached private key either stored in the Windows certificate store or in a so-called PCKS#12 file (*.p12/*.pfx), or, – on Linux – separate 'PEM encoded' key and certificate files.

  • Your organization's intranet as served by Internet Information Server (Windows), Apache (Linux) or another web server uses a certificate that can be re-used for PaperCut NG. NOTE: Unless your intranet server and PaperCut NG run on the same server (i.e. on different ports), the server name of your intranet server will be different from your PaperCut NG Application Server. E.g. the intranet address might be internal.myschool.edu while the PaperCut NG Application Server can be reached at printing.myschool.edu. In this case the certificate can only be re-used if it is a so-called wild-card certificate that allows arbitrary subdomains under the myschool.edu domain name that it was issued for.

On Windows, if the certificate with key exist in the Windows certificate store only, export it:

  1. Open the Windows Control Panel and open Internet Options.

  2. On the "Content" tab click "Certificates".

  3. On the Personal tab select the certificate and click "Export ..." and click "Next" at the initial screen

  4. Select 'Yes, export the private key' and click Next

  5. If you selected the last option correctly, you will only be able to export as a .PFX file

    • TICK 'Include all the certificates in the certification path if possible'

    • UNTICK 'Enable strong protection'

    • UNTICK 'Delete the private key if the export is successful'

  6. Type in a password for the PFX file. This is only used temporarily.

  7. Save the PFX file to with the extension .pfx. (This is just temporary, you MUST delete this file later on.)

  8. Finish the wizard to export the certificate.

On Windows, if the certificate with key exists in the IIS Server Certificates store, export it:

  1. Open the Windows management console, select your IIS server and open "Server Certificates".

  2. Right-click the certificate and click "Export ...".

  3. Choose a filename with the extension .pfx. (This is just temporary, you MUST delete this file later on.)

  4. Type in a password for the PFX file. This is only used temporarily.

  5. Click OK.

On Linux, if the key and certificate are in separate 'PEM encoded' files:

  • Use the 'OpenSSL' tool that is part of many Linux distributions to combine both files to a PKCS#12 file with the following command (type this all in one line):

    openssl pkcs12 -export -inkey <key file> -in <certificate file> 
        -out <pfx file>

    <pfx file> is the target PKCS#12 file for which you should choose a filename with the extension .pfx. (This is just temporary, you MUST delete this file later on.)

Then import the certificate into your own PaperCut NG keystore:

  1. Open a command prompt and change to the installation directory. E.g. on Windows:

        cd "c:\Program Files\PaperCut NG\"

  2. Enter the following command (type this all in one line):

    "runtime/jre/bin/java" -classpath server/lib/jetty-6.1.22.jar
        org.mortbay.jetty.security.PKCS12Import "<pfx file>"
        server/custom/my-ssl-keystore

    Substitute <pfx file> with the .pfx or .p12 file containing your certificate and key.

    The Jetty version number (6.1.22) changes from time to time. If you receive a NoClassDefFoundError message look for a jetty-*.jar file in the [app-path]/server/lib/ directory and update the command as appropriate.

  3. You will be asked to enter the 'input keystore passphrase'. Enter the password that you used when you saved the file.

  4. You will be asked to enter the 'output keystore passphrase'. Enter a new password such as 'password'. Once this command completes a new file should be created at [app-path]/server/custom/my-ssl-keystore. This file is your keystore and contains your certificate and key.

  5. Now that you have your keystore file, follow the instructions in the section called “Configuring PaperCut to use the new certificate” to install it and start serving up your new SSL certificate.

Configuring PaperCut to use the new certificate

The previous sections described how to create a keystore file - the section called “Creating and installing a purchased SSL Certificate” for putting a new certificate from a certificate authority into a keystore, and the section called “Importing an existing SSL key” for generating and putting your own "self-signed" certificate in a keystore. This section describes how to install your keystore so that PaperCut can start serving up your new certificate.

Important

Changes are not applied until the PaperCut NG Application Server has been restarted.

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

  1. Copy your signed keystore onto the server running the PaperCut NG Application Server. The suggested location is [app-path]/server/custom/my-ssl-keystore

  2. Open the file [app-path]/server/server.properties with a text editor (e.g. Notepad).

  3. Locate the section titled SSL Key/Certificate.

  4. Remove the # (hash) comment marker from all lines starting with "server.ssl".

  5. Define the location of your keystore, keystore password and key password as chosen previously. The file should look something like this:

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

    NOTE: On Mac OS please specify the FULL path to your keystore, e.g. /Applications/PaperCut NG/server/custom/my-ssl-keystore

  6. 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.

Important

Now that you have a working SSL certificate for your PaperCut NG server, it's time to set a reminder in your calendar (or similar) to ensure that your SSL certificate is renewed before it expires! Go do that now!

Renewing your SSL certificate

To ensure that the trust mechanisms in SSL are adhered to, SSL certificates are designed to expire so that your environment is kept up-to-date. To renew your SSL certificate you will essentially need to retrace your steps when originally creating a new SSL certificate. See: the section called “Creating and installing a purchased SSL Certificate”. However the exact steps will depend on your Certificate Authority as some may require you to submit a brand new CSR, some allow you to just request a new SSL certificate.

The easiest way to do this is to use a new keystore, e.g. you substitute my-ssl-keystore with my-ssl-keystore-20151127.

The new my-ssl-keystore-20151127 will only be put into production once you've modified the server.properties as per the the section called “Configuring PaperCut to use the new certificate”. and have restarted the PaperCut NG Application Server. This means you have time to create the private key, complete the CSR and receive the signed certificate before using the new keystore. If there is an issue with the new certificate or setup, you can quickly revert back to the original my-ssl-keystore.

For example, the SSL key generation command originally was

    keytool -keystore [app-path]\server\custom\my-ssl-keystore -alias jetty -genkeypair
    -keyalg RSA

and it becomes

    keytool -keystore [app-path]\server\custom\my-ssl-keystore-20151127 -alias jetty -genkeypair
    -keyalg RSA

Further customization

Extended keytool.exe usage

In this documentation we have provided the more common scenarios around keytool.exe usage. If you require further customisation please review the documentation available from Oracle:

  1. PaperCut NG version 15.2 and newer: Java 8 (1.8) keytool Documentation

  2. PaperCut NG version 14.0 and newer: Java 7 (1.7) keytool Documentation

  3. PaperCut NG version 13.5 and older: Java 6 (1.6) keytool Documentation

Can I have more than one hostname / FQDN?

One of the benefits of using a SSL certificate is making sure that the URL matches the certificate, preventing a 3rd party from masquerading as you. If you have more than one URL or Fully Qualified Domain Name (FQDN) that PaperCut NG is available from then you will have two main options:

  1. Obtain a "wildcard" certificate from your Certificate Authority. Please contact your Certificate Authority for further details as to this service.

  2. Use a "Subject Alternative Name" or "SAN" when creating the SSL certificate. This should require no special action from your Certificate Authority as this is done as part of the certificate generation process with keytool.exe. Note: You will require keytool.exe from PaperCut NG version 14.0 and newer.

    An example is:

        keytool.exe -keystore "my-ssl-keystore" -alias jetty -genkeypair -keyal RSA -ext san=dns:external.company.com

    Then, when asked for your "first and last name", enter the other FQDN:

        What is your first and last name?
        [Unknown]:  internal.company.lan

    Before completing you will then need to confirm the information is correct, you will see similar to:

        Is CN=internal.company.lan, OU=Unknown, O=Unknown, L=Unknown, ST=Unknown, C=Unknown correct?

    Once you have received your certificate from your Certificate Authority you can confirm your "Subject" and "Subject Alternative Name" are valid. Please make sure that you test the new certificate with multiple operating systems, browsers and hardware environments including laptops, mobile devices and printers/copiers.

Can I use other algorithms such as SHA2/SHA256?

In a word, yes. As we use keytool.exe, you can use the documentation above in the section called “Extended keytool.exe usage”.

For example, generating the private SSL key:

    keytool -genkey -alias server -keyalg rsa -sigalg sha256withrsa -keysize 2048 -keystore sha256

and generating the CSR:

    keytool -certreq -alias server -keystore sha256 -file 256.csr -sigalg sha256withrsa

Troubleshooting SSL

Verify certificate path in Windows

If you are getting errors with your new SSL certificate one of the first things to check is that the intermediary certificates have been loaded correctly. You can do this via Internet Explorer, and every other modern web browser, the steps differ slightly.

Load Internet Explorer and visit the HTTPs URL for your PaperCut NG server then click on the padlock near the URL bar as below.

Accessing Certificate Information in Internet Explorer v11

Figure A.1. Accessing Certificate Information in Internet Explorer v11

Then click View Certificates and navigate to the Certificate Path and verify it is correct.

Viewing the Certificate Chain in Windows

Figure A.2. Viewing the Certificate Chain in Windows

If the path is invalid, you may need to confirm that you have correctly inserted the required intermediary certificates. See the section called “Creating and installing a purchased SSL Certificate”

Verify certificate path via command line with OpenSSL

A quick way to easily validate the chain output by the server. This requires either Linux or Cygwin with openssl’s packages installed:

    openssl s_client -connect [server]:[port] -crlf

Once the text has been output, type in:

    QUIT

For example, a self-signed certificate will likely look like this:

    openssl s_client -connect localhost:9192 -crlf
    CONNECTED(00000003)
    depth=0 C = Unknown, ST = Unknown, L = Unknown, O = Unknown, OU = Unknown, CN = print-server
    verify error:num=18:self signed certificate
    verify return:1
    depth=0 C = Unknown, ST = Unknown, L = Unknown, O = Unknown, OU = Unknown, CN = print-server
    verify return:1
    ---
    Certificate chain
     0 s:/C=Unknown/ST=Unknown/L=Unknown/O=Unknown/OU=Unknown/CN=print-server
       i:/C=Unknown/ST=Unknown/L=Unknown/O=Unknown/OU=Unknown/CN=print-server
    ---

An example of a certificate that uses a chain, note the 0, 1, 2 and how the i: (issuer) matches with the s:(subject): of the next certificate.

    $ openssl s_client -connect www.google.com:443 -crlf
    CONNECTED(00000003)
    depth=2 C = US, O = GeoTrust Inc., CN = GeoTrust Global CA
    verify error:num=20:unable to get local issuer certificate
    ---
    Certificate chain
     0 s:/C=US/ST=California/L=Mountain View/O=Google Inc/CN=www.google.com
       i:/C=US/O=Google Inc/CN=Google Internet Authority G2
     1 s:/C=US/O=Google Inc/CN=Google Internet Authority G2
       i:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA
     2 s:/C=US/O=GeoTrust Inc./CN=GeoTrust Global CA
       i:/C=US/O=Equifax/OU=Equifax Secure Certificate Authority
    ---

ERR_SSL_VERSION_OR_CIPHER_MISMATCH & SSLHandshakeException: no cipher suites in common

If you receive an error message of ERR_SSL_VERSION_OR_CIPHER_MISMATCH in your web browser or notice SSLHandshakeException: no cipher suites in common in the [app-path]\server\logs\server.log it is likely that the certificate chain is not complete or the SSL certificate is in the wrong alias in the key-store. See the section called “Check that the correct Alias has been used in the keystore” to confirm the correct alias is in use.

Check that the correct Alias has been used in the keystore

PaperCut NG is configured to use the alias "jetty". If your SSL certificate is installed into another alias it will not be loaded correct. To confirm run the following command:

    keytool -list -v -keystore my-ssl-keystore-20151127
    Enter keystore password:  [password]

    Keystore type: JKS
    Keystore provider: SUN

    Your keystore contains 1 entry

    Alias name: jetty
    Creation date: 27/11/2015
    Entry type: PrivateKeyEntry

The PrivateKeyEntry needs to be present in the jetty Alias. If it has been imported into another alias, you can use keytool.exe to rename it. See the section called “Extended keytool.exe usage”