SSL/HTTPS Key Generation

SSL/HTTPS Key Generation
Prev	Appendix A. Tools - database, server-command scripting, and APIs (Advanced)	Next

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:

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 obtain a certificate signed by a trusted authority, see the section called “Using a custom signed SSL key”, 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.

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 signed SSL key

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 NG application server please see the section called “Importing an existing SSL key” below.

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.

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 leftovers from previous attempts and need to be deleted at this point.
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 SSL provider.
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
                        
```
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.
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 globaltrust 
    -file globaltrust.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.
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.
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 “Installing the Keystore” 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:

Open the Windows Control Panel and open Internet Options.
On the "Content" tab click "Certificates".
On the Personal tab select the certificate and click "Export ..." and click "Next" at the initial screen
Select 'Yes, export the private key' and click Next
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'
Type in a password for the PFX file. This is only used temporarily.
Save the PFX file to with the extension .pfx. (This is just temporary, you MUST delete this file later on.)
Finish the wizard to export the certificate.

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

Open the Windows management console, select your IIS server and open "Server Certificates".
Right-click the certificate and click "Export ...".
Choose a filename with the extension .pfx. (This is just temporary, you MUST delete this file later on.)
Type in a password for the PFX file. This is only used temporarily.
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:

Open a command prompt and change to the installation directory. E.g. on Windows:
```
cd c:\Program Files\PaperCut NG\
```
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.
You will be asked to enter the 'input keystore passphrase'. Enter the password that you used when you saved the file.
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.
Now that you have your keystore file, follow the instructions in the section called “Installing the Keystore” to install it and start serving up your new SSL certificate.

Installing the Keystore

The previous sections described how to create a keystore file - the section called “Using a custom signed SSL key” 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.

To configure the PaperCut 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 [app-path]/server/custom/my-ssl-keystore
Open the file [app-path]/server/server.properties with a text editor (e.g. Notepad).
Locate the section titled SSL Key/Certificate.
Remove the # (hash) comment marker from all lines starting with "server.ssl".
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
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