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.
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.
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
.
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
.
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 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 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
.
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.
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 – seperate '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.
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/HTTP Configuration
.
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.
© Copyright 1999-2011. PaperCut Software International Pty Ltd. All rights reserved.