SSL/HTTPS Key Generation

SSL/HTTPS Key Generation
Prev	Appendix A. Tools (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 and Safari. Such commercial CAs include: AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, ValiCert, Verisign, beTRUSTed, amongst others.

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.
Enter this command to produce the SSL key:
```
keytool -keystore my-ssl-keystore -alias jetty -genkeypair -keyalg RSA
                        
```
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 my-ssl-keystore -file 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.
Unless you have obtained a certificate from Verisign or Thawte, you first need to 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 my-ssl-keystore -importcert -alias globaltrust 
    -file globaltrust.pem
                            
```
When asked whether to trust this certificate, answer yes:
```
Trust this certificate? [no]:  yes
                            
```

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

keytool -keystore my-ssl-keystore -import -alias jetty
    -file jetty.crt -trustcacerts

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

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 chosen above. The file should look something like this:

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

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.

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 an existing signed key include:

You have obtained an SSK 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 a certificate with an attached private key either stored in the Windows certificate store or in a so-called PCKS#12 file with the file extension .p12 or .pfx.
Your organization's intranet as served by Internet Information Server 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.

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.

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.

To import the certificate into your own PaperCut NG keystore:

Open a command prompt and change to the application, e.g.:
```
cd c:\Program Files\PaperCut NG
```
Create a subdirectory called custom if it doesn't exist already.
```
mkdir custom
```
Enter the following command (type this all in one line) (this command is for recent versions of PaperCut NG only. If you are running an older version please contact support):
```
runtime\jre\bin\java.exe -classpath server\lib\jetty-6.1.19.jar
    org.mortbay.jetty.security.PKCS12Import "<pfx file>"
    custom\my-ssl-keystore
                            
```
For <pfx file> substitute the file name ending on .pfx or .p12 that contains the certificate and the key.
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'. Then proceed to configure the PaperCut NG Application Server to use the new keystore my-ssl-keystore with this new keystore password as described above.

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