Generating a SSL Browser Certificate · Generating a SSL Browser Certificate Overview: GoPrint implements the Jetty open-source project providing a HTTP server, HTTP client and javax.servlet

© 2014 GoPrint Systems, Inc. All rights reserved. |SSL Installation 1

Generating a SSL Browser Certificate

Overview:

GoPrint implements the Jetty open-source project providing a HTTP server, HTTP client

and javax.servlet container using the Sun Java development tools. The default Java

keystore is called cacerts and is found under the GS4\JRE\Lib\Security directory.

Similar to other certificate stores, such as Microsoft Windows Certificate Store, it contains all known

Trusted Root and Immediate Root Certificates used by all major browsers.

A GoPrint installation comes installed with a self-signed certificate created in a Java Keystore

during the installation process called gtx.keystore and is found under the GS4 root directory.

Important: when attempting to import a certificate it’s important to backup the gtx.keystore!

Since the certificate is self-signed, it’s not considered trusted by web-browsers. As a result, when

using the Web Client Popup or Control Center users are presented with the following Security Alert

message:

To overcome the security message, a certificate purchased by a certification authority must be

installed in the gtx.keystore.

Option#2 - install or create a self-signed certificate in the Windows Certificate Trusted Root Store.

By clicking View Certificate and installing it in the local Trusted Root Store on EACH machine you

can eliminate the Windows Security alert message without having to purchase a certificate. This is

not recommended and not supported by GoPrint.

http://www.goprintsupport.com/importing_self_signed_cert.pdf

http://www.goprintsupport.com/importing_self_signed_cert.pdf


Before you even begin!

By far, the most common issue with SSL import issues is that additional formatting was added to

the file when either copying the CSR into Notepad for submission or when the CA Reply and its

trusted certificates were copied from your email program. You can yourself a headache by electing

to receive the certificates bundled in a zip file or P7B format.

Receiving them as individual X.509 files is just asking for trouble. If this occurs, contact your

certificate authority and demand they present them to you in a preferred format.

Example of individual certificates (x.509) as

they’re commonly sent in the body of an email to

the purchaser from the certification authority.

Each file needs to be copied from the email body

to Notepad for importing, as compared to a .P7B

bundle containing all certificates in a single file.

Preventing File Corruption

Be careful of HTML formatting in emails, such as

this Gmail example which indents or adds

margins to the body which might not be picked

up when copied to Notepad.

Always, Always, Always!

Double and triple check your file for any

formatting issues!


Note the spacing that exists at the beginning of each line. This is incorrect. The text must be flush

again the side margin.

Corrupt File: The Begin Certificate and End Certificate MUST exist on their own line!


CORRECT FORMAT!

Using the Control Center SSL Certification Import Tool

Important: the Control Center SSL import tool currently supports PKCS#7 (.P7B) formatted files

containing the CA Reply and trusted certificates (referred to as a bundle), and PKCS#12 (.p12 or

.pfx) for wildcard certificates.

If you receive the CA Reply and trusted certificates as individual files in the body of an email or zip

file, then you must follow the steps outlined on page #12 to import the files into the Microsoft

Certificate Store and Export them as a .P7B. Optionally, you can also elect to individually import

each X.509 file from the command line using the Java Keytool command, as referenced on page

11.

Step 1- System – SSL Certificate


Step 2 - Select New Server SSL Certificate

Selecting this option will generate a new private/public key pair (into the existing

GS4\gtx.keystore) for submission to a certificate authority.

Step 3 - Create your certificate signing request

Step 4 - Copy the contents into

Notepad to make a backup or to

email to the staff member

responsible for SSL submissions.


Copy to Notepad

Optional: If you’re submitting the CSR, at this point

you can simply past the contents directing into the

authorities submission field.

Reminder: If your certificate authority provides the option to download the certificate, then select

PKCS7 as the download option.


Step 5 – Import the CA-Signed Certificate

Reminder: if the CA Reply was not received as a .P7B file then you must import the certificates

from the command line using the Java Keytool. See instructions on page 10.

1.) Select Import a CA-Signed Certificate:

2.) Select Choose File:


3.) Preview Signed Certificate and Confirm Import

Import was successful


Troubleshooting

If you received any of the following issues your file is either corrupt, your submitted a self-signed

certificate, your Trusted Root Authorities do not exist in the Java cacerts keystore, or you are

attempting to individually import each of the certificate files. You must import them as directed.

Public Key error

You MUST import your CA Reply into the SAME Keystore that the request (Public key) was

generated. If you’re trying to start over by creating new request and using a previous CA Reply it

will not work. In this case, you will need to take your new request and submit it to the Authority

that issued your originally certificate and request an updated CA Reply.

Reply has no certificates

There is an issue with the format of the .p7b file issued by your Certificate Authority. To resolve

Import the file into the Windows Certificate Store then Export the follow the directions in this

article to Export the Chain as .p7b format and import it.


No Chain and No Trust in Path

The Control Center SSL Tool ONLY supports importing .p7b files. Either one of these errors is an indication

you’re trying to import an individual (.x509) file for either the CA Reply or it’s corresponding trusted

certificates. If you cannot obtain the bundled certificates in a .p7b format you will need to either import each

certificate into the Windows Certificate store and following the directions in this article to export the chain as

.p7b or use the Java Keytool from a command line to import each certificate.

No Chain

No Trust


Step 6 – Re-Start the GoPrint GS-4 Services

Step 7 – Change the Web Client URL to point to the GTX server DNS name

If the web client popup was originally configured using the hostname of the GTX server then it

needs to be adjusted to reflect the dns name, as specified in the ssl certificate.

Click on the web client icon in the system and under Preferences look to

see if the Server Name or URL field displays the GTX computer name. If so,

update the field to reflect the GTX dns name, as displayed when the CSR

was generated.

This step must be performed on each workstation the web client is running.


Option #2 Create a Keystore, keypair, CSR, and import replies using Keytool

Why? (OPTIONAL)

Prior to the existence of the Control Center SSL Certificate Tool, signing requests and certificate

replies were created and imported from the command line using the Java Keytool command. If

issues exist using the Control Center certificate tool, it’s recommended to use the legacy process.

A copy of Sun JRE is included with a GoPrint installation and is found under the GS4\jre directory.

JRE uses the Keytool command to generate, manage, and import certificates.

Important: When you have installed your ssl certificate we strongly recommend that you

make a backup of your keystore, CSR file, ssl certificate, and any Root certificates (CA).

Your keystore, CSR, ssl certificate, and any required Intermediate ssl certificates (CA) are

required should you need to install or move your ssl certificate at a later date.

For keystore name, use keystore

For alias name, use goprintservercert

For password, use trustno1

Create the Keystore

Step 1 - Open a Windows command prompt and navigate to the GS4\jre\bin directory and

issue the keytool command to generate the private key and create the keystore.

Enter the following command:

keytool -genkey -keyalg RSA -keysize 2048 -keystore keystore -alias

goprintservercert -storepass trustno1


Step 2 – Enter your organization details

For the CSR to be valid the following information needs to be entered in the following fields:

Country, State (or Province), Locality (or City), Organization, Organizational Unit, and Common

Name.

Please note:

The Country is a two-digit code: for the United States, it's 'US'.

State and Locality are full names, i.e. 'California', 'Florida', Fort Worth, and Fort Myers.

The Organization Name is your Full Legal Company name as legally registered in your

locality.

The Organizational Unit is whichever branch of your institution is ordering the certificate

such as accounting, business office, IT etc.

The Common Name is the Fully Qualified Domain Name (FQDN) for which you are

requesting the SSL certificate.

If you are generating a CSR for a Wildcard Certificate your common name must start with *.

(for example: *.globalsign.com).

What is your first and last name?: goprnsrv.goprint.com (Must be the server FQDN name)

What is the name of your organizational unit?: IT

What is the name of your organization?: GoPrint Systems (Must be the full legal name)

What is the name of your City or Locality? : San Ramon (Must spell out the entire city

name)

What is the name of your State or Province?: California (Must spell out the entire city

name)

What is the two-letter country code for this unit?: US (must be the two-letter code ONL)

Is CN=testlaptop.goprintsystems.com, OU=IT, O=GoPrint Systems, L=San Ramon,

ST=California, C=US correct?

[no]: Enter key password for <trustno1>

(RETURN if same as keystore password)


Generated keystore sample:

The completed command creates a

keystore file under the GS4\jre\bin

directory


Create the Certificate Signing Request (CSR)

Step 3 - Generate Certificate Signing Request (CSR)

Issue the certreg command to create the Certificate Signing Request file:

GS4> jre\bin\keytool -certreq -keystore keystore -file signme.csr -alias

goprintservercert -storepass trustno1

For the file name use signme.csr

The generate certreg command creates the signme.cer file under the GS4\jre\bin directory.

Next: Open the file in Notepad


Step 4 – Open the file in Notepad and copy its contents

Select All, and copy the contents between the BEGIN NEW AND END NEW CERTIFICATE REQUEST

opening and closing tags; including the tags themselves.

This step is used to paste the contents, (in step 5) to your certification authority’s web-based

submission form.

Important: right-click on your mouse to use the SELECT ALL menu option instead of dragging your

mouse across the text and selecting copy. Doing so, could lead to a corrupt csr file.


Step 5 – Submit your CSR to an Certification Authority

GoPrint prefers ALL CA replies to be formatted as PKCS#7. This format is ideal because it includes

(bundles) the supporting certificate chains, in addition to the issued certificate, therefore requiring

the importing of only one file.

IMPORTANT: the vast majority of certification authorities will not create your CA reply in a

.P7B format because; 1) it takes too much time for them to generate, 2) they don’t have the

processes in place.

Instead, they generate the issued certificate and its required Trusted Intermediate, and

Root Certificate as single x.509 formatted files; and most cases, force you to return to their

website to download the Trusted Certificates. This means you must import the 3 certificates

individually, and in a specific order. We strongly recommend “not” selecting this method

because it “commonly” leads to errors and a great deal of wasted time

When your certification authority sends your CA Reply in this format contact their support

desk immediately and demand they reissue it as a .p7b file. Many CA’s provide a Support

section where you can change the server type, but you may need to ask for it. If

unsuccessful, refer to page 21 outlining the steps to convert the CA reply.

Server Platform: select Microsoft IIS7

To ensure you receive your CA reply in the desired format, select Microsoft IIS 7.0, because all

certification authority’s issue CA replies for the MS platform as a .P7B file.

Hint: although GoPrint

doesn’t integrate with

Microsoft IIS7 in any fashion,

we’re most concerned here

about obtaining the desired

file format.

Note: Before issuing your certificate, the CA verifies your identity. When the certificate is

issued, your identity is bound to the certificate, which contains your public key. Your

certificate also contains the CA's digital signature (which can be verified by anyone who

receives your certificate).


Because your certificate contains the identity of the issuing CA, an interested party that

trusts this CA can extend that trust to your certificate. The issuance of a certificate does not

establish trust, but transfers trust. If the certificate consumer does not trust the issuing CA,

it will not (or at least should not) trust your certificate.

A chain of signed certificates allows trust to be transferred to other CAs as well. This allows

parties who use different CAs to still be able to trust certificates (provided there is a

common CA in the chain, that is, a CA that is trusted by both parties).

Step 6 – Import the CA Reply

The certification authority will either email you or direct you to the website to download the

bundled certificate with its trusted chain certificates in one file with the extension .P7B.

Website download Option

Important: If the CA instructs you to visit their website and log in to your account to

download your certificate, follow the instructions to use the Select ALL menu option as seen

below to copy your certificate.


Import the Ca Rely

Download the file and unzip it to gs4\jre\bin

Use the import command to import the CA reply

For file name use the name of the certificate file

Keytool -import -trustcacerts -alias goprintservercert -file

goprnsrv_goprint_com.p7b -keystore keystore

Enter keystore password:

Certificate reply was installed in keystore

Results: Trusted Certificate Chain

The Trusted Root Certificate sits at the

highest level, followed by the

Intermediate Root, then the CA Reply.

.

Step 7 – Rename keystore to gtx.keystore

Rename the file keyStore to gtx.keystore

Hint: the changed name is used to replace the default

gtx.keystore under the GS4 root directory.

Reminder! Don’t forget to make a backup copy of the file!


Replace the existing gtx.keystore

Step 8 – Replace the Existing gtx.keystore

1. Stop the GoPrint GS-4 Services:

2. Rename the existing gtx.keystore to gtx.Keystore_old

Navigate to the GS4 root and rename the

gtx.keystore file to gtx.keystore_old

Note: if issues occur, you can restore the

system using the old gtx.keystore file.

3. Copy and paste the new gtx.keystore to the GS4 directory

Navigate to the gs4\jre\bin directory (where the new keystore was created)

and copy and paste it to the GS4 root directory.


Step 9 – Start the GoPrint GS-4 Services

Step 10 – Change the Web client URL to point to the GTX server FQDN name

If the web client popup was originally configured using the hostname of the GTX server then it

needs to be adjusted to reflect the FQDN name, as specified in the SSL certificate.

Click on the web client icon in the system and under Preferences look to

see if the Server Name or URL field displays the GTX computer name. If so,

update the field to reflect the GTX FQDN name, as displayed when the CSR

was generated.

This step must be performed on each workstation the web client is running.


Importing Certificates into the Windows Certificate Store

Converting a X.509 CA Reply to a .P7B format

When a certification authority emails you a X.509 CA Reply, you will receive an email similar to the

two below informing you to visit their website and download the Intermediate and Root certificates.

As previously stated, this is not the recommended method. Contact your CA immediately and

request that they reissue your certificate in a .P7B format.

If the certification authority refuses to comply with your request, then you must convert it yourself;

or manually import all 3 certificates.

Step 1 – Import the CA Reply to the Microsoft Certificate Store

The easiest method to import the CA Reply and its root certificates into the MS Certificate store is

to save the files with a .cer extension. This is the recognized extension for certificates by Microsoft

and allows you to simply right-click on the file and select “Install Certificate” from the drop down

menu.

If necessary, change the file extension for the

CA Reply, Intermediate, and Root certificates

files to .cer

Step 2 – Confirm the Certificates were successfully imported

The Microsoft Certificate Store can be accessed from the Run command by typing certmgr.msc or

as a new snap-in under Microsoft Management Console.

1.) Expand Personal or Other People Certificates Tree to detect your certificate


2.) Confirm the imported server certificate appears

3.) Confirm the trusted certificate path exists

Let’s make sure the intermediate and Root

certificates exist in the chain.

1. Right click the certificate and select Open to view

its contents

2. Select the Certificate Path tab


A successful import displays the certificate as well as its corresponding Trusted Chains.

If the Trusted Root and Intermediate Root Certificates exist in the Microsoft Certificate Store,

they’re automatically appended to the imported

certificate.

The Root certificate always appears at the top of the

chain followed by the Intermediate and lastly by the

CA Reply.

If the certificate path appears to be in order, you’re now ready to Export the files to a .P7B

formatted bundle.

Step 3 – Export the Certificate Chain as a P7B format

1.) Right-click on the certificate and Select All

Tasks - Export

2.) Select Cryptographic Message Syntax Standard – PKCS #7 Certificates (.P7B) and check

“Include all certificates in the certification path if possible”


3.) Save the file to the GS4\jre\bin directory

Step 4 – Import the file into the Java Keystore using Keytool or the Control Center SSL

Certificate Tool

Keytool Command

C:\GS4\jre\bin>keytool -import -trustcacerts –alias goprintservercert

-file goprnsrv_goprintsupport_com.p7b -keystore keystore -storepass

trustno1

Certificate was added to keystore

Control Center SSL Certificate Tool

1.) Select Import a CA-Sign Certificate


2.) Choose File

3.) Preview Signed Certificate and Confirm Import


Handling Wildcard Certificates and Other Certificate Stores

Importing PKCS#12 and .PFX files

Important: GoPrint requires the certificate chain password to be trustno1

When importing certificates into the Java Keystore that was generated on another server, typically

Wildcard certificates, the private key must also be included. The process includes exporting the

certificate and its trusted certificates along with the private key in a PKCS#12 format or .PFX for

Windows.

Typically, these certificates where created prior to the GoPrint installation, in the case of Wildcard

certificate, or the Certificate Signing Request were generated from a Windows Certificate Store or

OpenSSL server.

Personal Information Exchange Overview (PKCS #12)

The Personal Information Exchange format (PFX, also called PKCS #12) supports secure storage of

certificates, private keys, and all certificates in a certification path.

The PKCS #12 file format is the only file format that can be used to export a certificate and its

private key.

HOW IT WORKS!

If the certificate reply was created in the Windows certificate store, then the certificate chain and

private key may be exported.


Important: a password is required to protect the key. If requesting the file from a staff member

it’s important to obtain the password. To import seamlessly with GoPrint, it’s recommended to

request a password of “trustno1”

If you did not receive your certificate with this password then skip to page 32 to learn how

to change it.


Step 1 – Create a new blank Key Store

keytool -importkeystore -destkeystore c:\gs4\certs\gtx.keystore -deststorepass

trustno1 -srckeystore c:\gs4\certs\wildcard.pfx -srcstoretype PKCS12 -srcstorepass

trustno1

The PKCS#12 was successfully imported and the new gtx.keystore created!!!

Entry for alias le-72d11884-bbab-4d4d-a79f-b5f3072a715e successfully

imported. Import command completed: 1 entries successfully imported, 0

entries failed or cancelled

Step 2 - change the default Alias to goprintservercert

The Goprint system requires a Keystore alias name of ‘goprintservercert’ and by default the

importkeystore command generates a generic alias, as highlighted below:

Entry for alias le-72d11884-bbab-4d4d-a79f-b5f3072a715e successfully

imported. Import command completed: 1 entries successfully imported, 0

entries failed or cancelled

Issue the command:

keytool -changealias -alias le-72d11884-bbab-4d4d-a79f-b5f3072a715e -destalias

goprintservercert -keystore c:\gs4\certs\gtx.keystore


Step 3 - view the contents of the Keystore to confirm the alias change

Issue command:

C:\GS4\jre\bin>keytool -v -list -keystore c:\gs4\certs\gtx.keystore

Enter keystore password:

Step 4 - backup the current gtx.keystore

The current gtx.keystore is found under the GS4\ root directory:

Rename the current gtx.keystore to gtx.keystore_old


Step 5 – replace with the new Keystore

Copy and paste the new gtx.keystore to the GS4 directory

Step 6 – restart the GoPrint GS-4 Services


Step 7 – ensure web client profiles reflect the FQDN name specified in the CA

Reply

If the Web Client popup was installed using the hostname of the GTX server then in order to apply

the SSL certificate the Web Client preference setting must be updated.

Step 8 – make a backup of your new gtx.keystore file and certificate files and save

in a secure place from the server!

Changing the Exported PKCS#12 (.PFX) Password

When exporting a certificate chain from a certificate store you’re required to create a password.

GoPrint requires the password of ‘trustno1’. If your administrator did not create this password,

then you will need to import it into the Local Certificate Store and Export it where you can then

change the password.

Exporting a Windows Certificate Chain

1. Open the Certificate Store where certificate chain was imported.

2. Highlight your certificate and right-click, select All Tasks - Export


3. Select the Personal Information Exchange – PKCS#12 (.PFX) radio button

Check the “Include all

certificates in the certificate

path if possible” radio button

Check Export all extended

properties.

Select Next


4. Select Yes, export the private

Key and click Next

5. Enter a File name and desired path

and click Next

Note: It’s recommended to save the

file under the GS4\certs directory


6. Create a password of trustno1 (this is the same password required to use when

creating the Java keystone and MUST match.

Important: this MUST be the same password

used by the GoPrint Keystore

DO NOT use another password!

The Completing the Certificate Export Wizard

appears:

7. Click Finish

8. Follow the previous steps to import your

certificate into the Java Keystore


Control Center Certificate Import Tool

Step 1 – Navigate to System – SSL Certificates

1. Scroll down to Wildcard SSL Certificates

2. Click link Wildcard SSL Certificates

3. Certificate File: Browse to the PKCS #7 file representing the certificate chain

4. Private Key File: browse to the PKCS #8 file representing the private key.

5. Restart the GS4-Services


Handling Nested Domain Names

Anything that has a sub2 level in it is going to be nested and is NOT covered by the wildcard by default.

Example: sub1.domain.com vs. sub2.sub1.domain.com

Hint: A nested subdomain is a subdomain that is deeper than one level:

To fix it for that specific name, you need to add it as a SAN name on the certificate.

1. Create a new GoPrint CSR using the instructions followed previously.

2. Visit your Certification Authorities support site and follow their instructions:

Example: http://www.digicert.com/ssl-support/wildcard-san-names.htm

1. Log into your account, select the order number, click on 'Get a Duplicate', Paste the new CSR, then specify the name in the SAN field

Note: SAN names are just additional names secured by the certificate.

Miscellaneous Topics

Moving a Certificate from Apache to a Java Keystore

1. Backup your certificate:

To import your certificate to Windows, you will first need to combine your primary

certificate, Intermediate (CA) Certificate, and your private key file into a .pfx type

backup file. To do this, use the following command:

openssl pkcs12 -export -out MyCertBackup.pfx -inkey

your_private_key_file.txt -in your_domain_name.crt -certfile

MyCertCA.crt

This creates a backup of your primary certificate called MyCertBackup.pfx. Copy this file to your

GoPrint Windows Server.

Once the .pfx file is copied to your Windows server, follow these instructions to Convert and import

your PFX file into a Java KeyStore.

http://www.digicert.com/ssl-support/wildcard-san-names.htm


Test the new keystore

Open the Web Client Popup or Control Center using a secure https port. If not prompt to trust the

certificate, then the KeyStore has successfully been generated.

Common Error Message:

Error1: After restarting the GS-4 Services, if the CPU races up to 100% which is due to the Java

process racing. This is an indication the KeyStore has been improperly formatted.

Solution: Typical this scenario may occur when the Private Key was generated on another server

and does not exist in the Java KeyStore. If this is the case, see the instructions below on how to

import a Private Key.

Troubleshooting SSL Errors

Error: After restarting the GoPrint GS-4 Services, the CPU races up to 100% and Task

Manager displays the Java process racing. This is an indication the keystore has been

improperly formatted.

Solution: This scenario occurs when the Private Key was generated on another server and

does not exist in the Java keystore. To solve, see the instructions on how to import a Private

Key in the document; “Advanced_SSL_Certificates.pdf

Error: keytool error: java.lang.Exception: Input not an X.509 certificate

Keytool -import -trustcacerts -alias server -file goprnsrv_goprintsupport_com.p7b -

keystore keystore

Solution: the alias name was incorrect, it should be goprintservercert

Or

keytool -import -trustcacerts -alias goprintservercert -file

goprnsrv_goprintsupport_com.p7b -keystore keystores

Solution: the keystore name is incorrect, is should keystore not keystores

Error: keytool error: java.lang.Exception: Certificate reply does not contain public key for

<goprintservercert>

Solution: The CA Reply file is tied to the public key of another keystore. When a new

keystore and keypair are created, you cannot use the CA reply generated from another

keystore. When issues occur, you must generate a new keystore and keypair and submit a


new CSR to the CA and import the updated CA reply.

Error: keytool error: java.lang.RuntimeException: Usage error, goprnsrv_goprint_com.p7b is

not a legal command

keytool -import -trustcacerts -alias goprintservercert-file goprnsrv_goprint_com.p7b -

keystore keystore

Solution: Typo, a space needs be entered before the –file switch.

Error: keytool error: java.lang.Exception: Failed to establish chain from reply

keytool -import -trustcacerts -alias goprintservercert -file ssl.crt -keystore

keystore

Solution: attempting to import the CA First, intermediate has to go first.

keytool -import -trustcacerts -alias goprintservercert -file intermediate.crt -

keystore keystore

Error: keytool error: java.lang.Exception: Public keys in reply and keystore don't match

Solution: When importing individually, each certificate in the chain must have its own Alias,

and only the returned certificate can be imported into the –Alias goprintservercert

keytool -import -trustcacerts -alias inter -file intermediate.crt -keystore keystore

-storepass trustno1

Certificate was added to keystore

Java Keytool Basic Commands

View the contents of a Keystore

c:\GS4\jre\bin>keytool -list -v -keystore gtx.keystore

Documents

Generating a SSL Browser Certificate · Generating a SSL Browser Certificate Overview: GoPrint implements the Jetty open-source project providing a HTTP server, HTTP client and javax.servlet