Configuring HTTPS support. Overview. Certificates

(1)

Overview

Destiny provides the option to configure secure access when password information is transmitted between the client browser and the server. Destiny can switch from HTTP to HTTPS protocol whenever a page containing a user’s password is about to be transmitted, such as when logging in or when editing a patron. This is the same security mechanism commonly used for transacting e-commerce, such as online banking. The document explains the procedure to set up the HTTPS feature in Destiny.

Certificates

To support HTTPS, Destiny must be provided with a private/public encryption key pair, also referred to as a certificate. The certificate is used to encrypt the conversation between the browser and Destiny.

Although Destiny ships with a sample encryption certificate, this certificate should not be used in a production environment. The encryption provided by the HTTPS protocol is only truly secure when the private key inside the certificate is secure. Because the sample private key is part of all default Destiny installations, the sample certificate is not secure. The document explains the procedure to create your own unique, truly secure certificate.

Certificates are internally validated by being “signed”. Signing is a process where one certificate digitally validates another. You can sign your own certificate, or you can have it signed by a recognized Certificate Authority (CA). Certificate authorities charge a fee to sign your certificate, and typically you must renew it yearly. The advantage of using a CA-signed certificate is that the user’s browser doesn’t need to prompt the user to accept the certificate, because it is signed by an authority known to that browser.

Destiny accesses your certificate(s) when it is created from and stored in a “keystore”. A keystore is a special file that can contain one or more certificates. Destiny includes a certificate management utility called “keytool” that helps you create your keystore and certificate.

(2)

High-level process

The process to enable HTTPS support in Destiny is as follows: 1. Generate a keystore with a new self-signed certificate in it.

self-signed certificate

destiny.keystore generate

Step 2 is optional.

2. To have the certificate signed by a recognized Certificate Authority such as VeriSign or Thawte, you must perform the following steps:

A. Export a Certificate Signing Request (CSR) from the self-signed certificate in your new keystore and upload the CSR to your chosen Certificate Authority.

self-signed certificate destiny.keystore export upload Certificate Authority: VeriSign, Thawte, etc. request.csr (certificate signing request)

B. Download the CA’s publicly-known root certificate and import it into your keystore.

root.cer self-signed certificate destiny.keystore download Certificate Authority: VeriSign, Thawte, etc. import CA root certificate

C. Download the CA-signed certificate reply and import it into your keystore.

signed.cer CA-signed cert (replaces self-signed) destiny.keystore download Certificate Authority: VeriSign, Thawte, etc. import CA root certificate

(3)

YOUR DESTINY DOMAIN NAME

Spell out your state

Detailed process

Now we’ll work through these three major steps in detail. These instructions assume Destiny has been installed in “C:\FSC-Destiny”. If your Destiny application is installed in a different location, please adjust the commands accordingly.

Step 1: Generate a keystore with a new self-signed certificate in it

Destiny includes a Java 2 JDK utility called “keytool” that can help you perform all your certificate management tasks. We will use keytool to create a new keystore containing a new self-signed certificate.

A. Create a new subdirectory where you will place your keystore. We recommend placing this subdirectory outside the FSC-Destiny application. This subdirectory must be accessible by the account running the Destiny service (by default, the system account). However, you must protect this subdirectory with your operating system security so that others cannot access it and obtain your private key.

C:\> md mycert C:\> cd mycert C:\mycert>

B. Use the keytool utility to create your new keystore and certificate.

Use the following example command to create a new keystore file containing a single encryption key pair. • Make sure the keystore file does not exist prior to running this command.

• Substitute the password of your choice for mypassword.

• Keytool.exe exists in the C:\FSC-Destiny\java\bin subdirectory; hence, the keytool command is preceded by that path.

• If your certificate authority requires a keysize larger than 1024 (the default size), you can add the parameter,

-keysize, to the command with the size your provider requires. This example uses a keysize of 2048: C:\mycert> c:\fsc-destiny\java\bin\

keytool genkey alias destiny keyalg RSA –keysize 2048 –keystore destiny.keystore -storepass mypassword

What is your first and last name? [Unknown]: destiny.ausd.edu

What is the name of your organizational unit? [Unknown]: Allentown USD

What is the name of your organization? [Unknown]: Allentown USD

What is the name of your City or Locality? [Unknown]: Allentown

What is the name of your State or Province? [Unknown]: Illinois

What is the two-letter country code for this unit? [Unknown]: US

Is <CN=destiny.ausd.edu, OU=Allentown USD, O=Allentown USD, L=Allentown, ST=Illinois, C=US> correct?

[no]: YES

Enter key password for <destiny>

(RETURN if same as keystore password):

The –keystore argument specifies the keystore filename and location. If the keystore does not already exist, it is created. Store this file on a secure folder, accessible by Destiny, on your server. Do not store this file in the FSC-Destiny folder tree.

The –storepass argument will be the password used to access the keystore. Save this password; you will need it in subsequent steps.

Abbreviate “US”

(4)

When generating the certificate, you will be prompted for a “first and last name”. This is not your name. It is important to enter the DNS name that will be used by a client browser to access the Destiny server. For example, if Destiny will be made available through the URL “http://library.mydistrict.org”, enter “library.mydistrict.org” for the first and last name. Alternatively, you may use a name that contains the base portion of the URL. For example, if you wanted to provide a single certificate for all web sites within the district you could enter “mydistrict.org” for the name. This is important because, when a client browser accepts the public key, it validates the URL against the name specified in the key. If the URL does not match, the client is warned that the site did not identify itself correctly.

Verify

To verify that the keystore and self-signed certificate were created properly: 1. In your C:\mycert directory you should now have this file: destiny.keystore.

Be sure to create a backup of this file and save its password before going any further. 2. Use keytool to display the contents of your new keystore:

C:\mycert> c:\fsc-destiny\java\bin\keytool -list -v -keystore destiny.keystore -storepass

mypassword

Keystore type: jks Keystore provider: SUN

Your keystore contains 1 entry:

Alias name: destiny Creation date: Sep 22, 2003

Entry type: keyEntry

Certificate chain length: 1 Certificate[1]:

Owner: CN=destiny.ausd.edu, OU=Allentown USD, O=Allentown USD, L=Allentown, ST=Illinois, C=US Issuer: CN=destiny.ausd.edu, OU=Allentown USD, O=Allentown USD, L=Allentown, ST=Illinois, C=US

Serial number: 3f6f1d05

Valid from: Mon Sep 22 11:02:13 CDT 2003 until: Sun Dec 21 10:02:13 CST 2003 Certificate fingerprints:

MD5: 3F:7D:DD:0E:3F:17:5F:10:22:58:ED:14:EA:E9:A5:85

SHA1: 8E:B4:39:17:4D:25:04:7C:B8:1E:68:55:5B:06:9F:0B:A2:C1:57:A4 *******************************************

*******************************************

You should see “1 entry”

Note the alias “destiny”

Your certificate MUST be of type “keyEntry” Make sure you see “Certificate chain length: 1”

(5)

Step 2: Have the certificate signed by a Certificate Authority

This step is optional. In step 1, you created a self-signed certificate, which will allow your uses to access Destiny. However, in this case, when a browser makes a connection to a server using the HTTPS protocol, the user must explicitly accept the certificate from the server.

For example, Internet Explorer presents the end user with the following dialog:

To prevent your Destiny users from having to explicitly accept your certificate, a certificate authority (CA) can sign the certificate. Two companies that provide signing services are www.verisign.com and www.thawte.com. Earlier we looked at the general outline of the signing process. Your chosen certificate authority will provide additional details for their specific process.

C. Export a Certificate Signing Request (CSR) from the self-signed certificate in your new keystore. This command exports a certificate request from the keystore created in Step 1:

C:\mycert> c:\fscdestiny\java\bin\keytool certreq file request.csr alias destiny

-keystore destiny.-keystore -storepass mypassword

When you order a signed certificate, the certificate provider will require the contents of the request.csr file. Verify

To verify that the certificate signing request was created:

1. In your C:\mycert directory, you should now have this file: request.csr. 2. Enter this file name onscreen to verify that its content looks like the following:

C:\mycert> type request.csr

---BEGIN NEW CERTIFICATE REQUEST---

MIIBvzCCASgCAQAwfzELMAkGA1UEBhMCVVMxETAPBgNVBAgTCElsbGlub2lzMRIwEAYDVQQHEwlB bGxlbnRvd24xFjAUBgNVBAoTDUFsbGVudG93biBVU0QxFjAUBgNVBAsTDUFsbGVudG93biBVU0Qx GTAXBgNVBAMTEGRlc3RpbnkuYXVzZC5lZHUwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBALGF HLFJNbZtFEI64IBOUsyHKrV28OqERyGP86LR48PWw2yTN1mbKRVGB18XtR1GTfHhV4c3bjsO8oaa e3K87F0qyfNxXLYzFx/evFuHsSFN3zee5gcGWDXJrqPKyRfXt+kBuddGl1mn9fFQJfMidTfQcHHF GAyzb9aMdwk1mO+xAgMBAAGgADANBgkqhkiG9w0BAQQFAAOBgQAuvt//upMMynzu8UX4N0nwa8Ff dz36j52sCMxha+RMDDMjSpbnS3GZwsUigwr6+j51ods16QdrE6FP/7cHXyGLO/s3lq1Pt06jQ10W /vOMmTr4T2MSNqDQsXo7hBReOrV6lrrWfMibGA8IoJLsrBFzxl29TVp+sx4k7l1dNQiaeg== ---END NEW CERTIFICATE REQUEST---

(6)

The CSR file you have just created must be uploaded to your chosen certificate authority. Refer to their website for additional information. If your CSR asks you which web server you are using, answer “Tomcat”. If this is not an option, select “Apache”.

Dow nload t he CA’ s publicly-know n root cert if icat e.

Your certificate authority will return to you a signed certificate file. Before you can import your signed certificate, you must import the certificate authority’s public root certificate. Their root certificate can be downloaded from their website. For example, the Thawte public root certificate can be downloaded from

http://www.thawte.com/html/SUPPORT/keygen/serverbasic.crt.

For VeriSign certificates you may need to use the intermediate root certificate found at

http://www.verisign.com/support/install2/intermediate.html. In this example, we assume you have downloaded the

CA root certificate and saved it with the name C:\mycert\root.cer.

You may receive certificates in either x.509 (binary / non-displayable) format or PEM (text / displayable) text format. In the case of a PEM (text) certificate, you may find that it is returned to you as a page in your browser. If that is the case, you can cut/paste from your browser into a text editor such as Notepad, and save as

C:\mycert\root.cer.

Important: If you need to download one or more intermediate certificates, you must import the root certificate first. Place any intermediate certificates beneath the root certificate and above the server certificate. Please see your certificate vendor for specifics.

Verify

To verify that you have received a proper root certificate:

1. In your C:\mycert directory, you should now have this file: root.cer (or substitute the name you gave the file when you downloaded it).

2. Use keytool to display the contents of the root certificate:

C:\mycert> c:\fsc-destiny\java\bin\keytool -printcert -file root.cer

Owner: [email protected], CN=Thawte Server CA, OU=Certification Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

Issuer: [email protected], CN=Thawte Server CA, OU=Certification Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

Serial number: 1

Valid from: Wed Jul 31 19:00:00 CDT 1996 until: Thu Dec 31 17:59:59 CST 2020 Certificate fingerprints:

MD5: C5:70:C4:A2:ED:53:78:0C:C8:10:53:81:64:CB:D0:1D

SHA1: 23:E5:94:94:51:95:F2:41:48:03:B4:D5:64:D2:A3:A3:F5:D8:8B:8C

Important: If the certificate is a PEM-format text file, it MUST have at least one blank line after all the text; otherwise, keytool may not recognize it properly. You can add a blank line after the last header by editing the text file in Notepad and pressing [Enter] twice after the last line in the file.

(7)

D. Import the CA root certificate into your keystore. Note that in this step we give the root certificate its own unique alias:

C:\mycert> c:\fsc-destiny\java\bin\keytool -import -file root.cer -alias root -keystore

destiny.keystore -storepass mypassword

Serial number: 1

MD5: C5:70:C4:A2:ED:53:78:0C:C8:10:53:81:64:CB:D0:1D

SHA1: 23:E5:94:94:51:95:F2:41:48:03:B4:D5:64:D2:A3:A3:F5:D8:8B:8C Trust this certificate? [no]: YES

Certificate was added to keystore

Verify

To verify that your keystore now contains the CA’s public root certificate, use keytool again to display the contents of your keystore:

mypassword

Your keystore contains 2 entries:

Alias name: root

Creation date: Sep 22, 2003 Entry type: trustedCertEntry

Serial number: 1

MD5: C5:70:C4:A2:ED:53:78:0C:C8:10:53:81:64:CB:D0:1D

SHA1: 23:E5:94:94:51:95:F2:41:48:03:B4:D5:64:D2:A3:A3:F5:D8:8B:8C *******************************************

*******************************************

Alias name: destiny

Creation date: Sep 22, 2003

Entry type: keyEntry

Owner: CN=destiny.ausd.edu, OU=Allentown USD, O=Allentown USD, L=Allentown, ST=Illinois, C=US Issuer: CN=destiny.ausd.edu, OU=Allentown USD, O=Allentown USD, L=Allentown, ST=Illinois, C=US

Serial number: 3f6f1d05

Valid from: Mon Sep 22 11:02:13 CDT 2003 until: Sun Dec 21 10:02:13 CST 2003 Certificate fingerprints:

MD5: 3F:7D:DD:0E:3F:17:5F:10:22:58:ED:14:EA:E9:A5:85

SHA1: 8E:B4:39:17:4D:25:04:7C:B8:1E:68:55:5B:06:9F:0B:A2:C1:57:A4

******************************************* *******************************************

Your keystore now contains 2 entries (the CA root, and your self-signed certificate)

You should now see the new “root” alias you just imported. It MUST be of “Entry type:

trustedCertEntry”.

Your self-signed certificate with the alias “destiny” should still be intact. The order of the two certificates in the keystore is not relevant.

(8)

E. Import the intermediate CA, if necessary.

C:\mycert>c:\fsc-destiny\java\bin\keytool -import -file intermediate.cer -alias intca - keystore destiny.keystore -storepass mypassword

You will not be asked if you trust this CA, since it is part of a trusted chain. The keytool displays the following message:

Certificate was added to keystore

F. Import the signed certificate:

C:\mycert>c:\fsc-destiny\java\bin\keytool -import -file signed.cer -alias destiny -keystore destiny.keystore -storepass mypassword -trustcacerts

The keytool displays the following message:

Certificate reply was installed in keystore

G. Download the CA-signed certificate reply and import it into your keystore.

Your certificate authority will return to you a signed certificate file. Save your downloaded, signed certificate to this location: C:\mycert\signed.cer.

The signed certificate you receive may be in either x.509 (binary / non-displayable) format or PEM (text /

displayable) text format. In the case of a PEM (text) certificate, you may find that it is returned to you as a page in your browser. If that is the case, you can cut/paste from your browser into a text editor such as Notepad.

Important: When you import the signed certificate file, it must find the CA root certificate already in your keystore. Before proceeding with this step, make sure you have already imported your CA’s root certificate.

Verify

To verify that you have downloaded a proper signed certificate:

1. In your C:\mycert directory, you should now have this file: signed.cer (or substitute the name you gave the file when you downloaded it).

2. Use keytool to display the contents of the signed certificate:

C:\mycert> c:\fsc-destiny\java\bin\keytool -printcert -file signed.cer

Owner: CN=destiny.ausd.edu, OU=Allentown USD, O=Allentown USD, L=Allentown, ST=Illinois, C=US Issuer: CN=Thawte Server CA, OU=Certification Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

Serial number: 8ec1

Valid from: Mon Sep 22 16:04:21 CDT 2003 until: Mon Oct 13 16:04:21 CDT 2003 Certificate fingerprints:

MD5: 77:8F:71:03:51:40:F0:C2:B1:E9:03:12:D5:41:F9:24

SHA1: 6B:00:B3:8E:A2:C7:BE:AD:06:09:F7:1B:ED:F1:4E:39:97:8A:5A:41

Important: If the certificate is a PEM-format text file, it MUST have at least one blank line after all the text; otherwise, keytool may not recognize it properly. You can add a blank line after the last header by editing the text file in Notepad and pressing [Enter] twice after the last line in the file.

H. Import the signed certificate into your keystore. This signed certificate must replace the self-signed certificate already in your keystore, so be sure to include the parameter “-alias destiny”.

(9)

Verify

To verify that your keystore now contains both the CA’s public root certificate and your new CA-signed certificate, use keytool again to display the contents of your keystore:

mypassword

Your keystore contains 2 entries:

Alias name: root

Creation date: Sep 22, 2003 Entry type: trustedCertEntry

Serial number: 1

MD5: C5:70:C4:A2:ED:53:78:0C:C8:10:53:81:64:CB:D0:1D

SHA1: 23:E5:94:94:51:95:F2:41:48:03:B4:D5:64:D2:A3:A3:F5:D8:8B:8C

******************************************* *******************************************

Alias name: destiny

Creation date: Sep 22, 2003 Entry type: keyEntry

Owner: CN=destiny.ausd.edu, OU=Allentown USD, O=Allentown USD, L=Allentown, ST=Illinois, C=US

Issuer: CN=Thawte Server CA, OU=Certification Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

Serial number: 8ec1

Valid from: Mon Sep 22 16:04:21 CDT 2003 until: Mon Oct 13 16:04:21 CDT 2003 Certificate fingerprints:

MD5: 77:8F:71:03:51:40:F0:C2:B1:E9:03:12:D5:41:F9:24

SHA1: 6B:00:B3:8E:A2:C7:BE:AD:06:09:F7:1B:ED:F1:4E:39:97:8A:5A:41 Certificate[2]:

Owner: CN=Thawte Server CA, OU=Certification Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

Issuer: CN=Thawte Server CA, OU=Certification Services Division, O=Thawte Consulting cc, L=Cape Town, ST=Western Cape, C=ZA

Serial number: 0

MD5: 5E:E0:0E:1D:17:B7:CA:A5:7D:36:D6:02:DF:4D:26:A4

SHA1: 39:C6:9D:27:AF:DC:EB:47:D6:33:36:6A:B2:05:F1:47:A9:B4:DA:EA *******************************************

*******************************************

You should see your “destiny” alias certificate with a chain length of 2 (not 1). This signifies a properly signed chain.

(10)

Step 3: Configure the Destiny server

Now we will edit Destiny’s configuration file to point to your keystore, and turn on HTTPS support. A. If running, stop your Destiny service.

B. In your command prompt window, change directory to C:\FSC-Destiny\fsc\bin. C:\mycert> cd \FSC-Destiny\fsc\bin

C:\FSC-Destiny\fsc\bin>

C. Back up your config.properties file.

C:\FSC-Destiny\fsc\bin> copy config.properties config.properties.orig

1 file(s) copied.

D. Use Notepad to edit the config.properties file.

C:\FSC-Destiny\fsc\bin> notepad config.properties E. Modify the following lines:

Change:

## Specify the full path to your HTTPS keystore ## KEYSTORE_PATH=D:/mydistrict/district.keystore KEYSTORE_PASSWORD=changeit

SECURITY_ENABLED=

To (Use the actual values for path and password generated in Step 1):

KEYSTORE_PATH=C:/mycert/destiny.keystore KEYSTORE_PASSWORD=mypassword

SECURITY_ENABLED=true

For the KEYSTORE_PATH you must use the forward slash “/” as the path separator. For the KEYSTORE_PASSWORD, enter the password you used to create your keystore.

F. Save this file and run config.bat from within this directory. Config.bat is a script that populates other Destiny

configuration files from the values in config.properties. You must run config.bat whenever config.properties is changed. C:\FSC-Destiny\fsc\bin> config.bat Buildfile: config.xml -verify-config-properties-present: -fail-if-config-properties-not-present: -build-run-classpaths:

[propertyfile] Updating property file: C:\FSC-Destiny\fsc\bin\run-classpath.properties

configure-destiny:

[copy] Copying 1 file to C:\FSC-Destiny\jboss\server\destiny\deploy

(11)

Verification

After restarting Destiny, open a web browser and access Destiny via normal HTTP.

Go to the district login page and press the login button. You should be redirected from HTTP to HTTPS. Upon completing the login process, you will be set back to HTTP.