Configuring HTTPS support. Overview. Certificates

Transcription

1 Configuring HTTPS support 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. generate self-signed certificate destiny.keystore 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 export upload Certificate Authority: VeriSign, Thawte, etc. request.csr (certificate signing request) destiny.keystore B. Download the CA s publicly-known root certificate and import it into your keystore. CA root certificate self-signed certificate import root.cer download Certificate Authority: VeriSign, Thawte, etc. destiny.keystore C. Download the CA-signed certificate reply and import it into your keystore. CA root certificate CA-signed cert (replaces selfsigned) import signed.cer download Certificate Authority: VeriSign, Thawte, etc. destiny.keystore 3. Configure the Destiny server Page 2 of 11 Copyright 2010 Follett Software Company Rev A

3 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 YOUR DESTINY DOMAIN NAME Spell out your state 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 Don t enter a new password Rev A Copyright 2010 Follett Software Company Page 3 of 11

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 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. 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]: You should see 1 entry Note the alias destiny Your certificate MUST be of type keyentry Make sure you see Certificate chain length: 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 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 Page 4 of 11 Copyright 2010 Follett Software Company Rev A

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 and 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:\fsc-destiny\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. 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----- Upload the CSR to your chosen Certificate Authority. Rev A Copyright 2010 Follett Software Company Page 5 of 11

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. Download the CA s publicly-known root certificate. 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 For VeriSign certificates you may need to use the intermediate root certificate found at 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. 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: Address=server-certs@thawte.com, CN=Thawte Server CA, OU=Certification Services Issuer: Address=server-certs@thawte.com, CN=Thawte Server CA, OU=Certification Services Serial number: 1 Valid from: Wed Jul 31 19:00:00 CDT 1996 until: Thu Dec 31 17:59:59 CST 2020 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. Page 6 of 11 Copyright 2010 Follett Software Company Rev A

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 Owner: CN=Thawte Server CA, OU=Certification Services Issuer: CN=Thawte Server CA, OU=Certification Services Serial number: 1 Valid from: Wed Jul 31 19:00:00 CDT 1996 until: Thu Dec 31 17:59:59 CST 2020 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 To verify that your keystore now contains the CA s public root certificate, use keytool again to display the contents of your 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 2 entries: Your keystore now contains 2 entries (the CA root, and your selfsigned certificate) Alias name: root Creation date: Sep 22, 2003 Entry type: trustedcertentry You should now see the new root alias you just imported. It MUST be of Entry type: trustedcertentry. Owner: Address=server-certs@thawte.com, CN=Thawte Server CA, OU=Certification Services Issuer: Address=server-certs@thawte.com, CN=Thawte Server CA, OU=Certification Services Serial number: 1 Valid from: Wed Jul 31 19:00:00 CDT 1996 until: Thu Dec 31 17:59:59 CST 2020 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 Your self-signed certificate with the alias Creation date: Sep 22, destiny should still be intact. The order of the 2003 Entry type: keyentry two certificates in the keystore is not relevant. 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 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 Rev A Copyright 2010 Follett Software Company Page 7 of 11

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. 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 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. C:\mycert> c:\fsc-destiny\java\bin\keytool -import -file signed.cer -alias destiny -keystore destiny.keystore -storepass mypassword -trustcacerts Certificate reply was installed in keystore Make sure this says Certificate reply Page 8 of 11 Copyright 2010 Follett Software Company Rev A

9 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: C:\mycert> c:\fsc-destiny\java\bin\keytool -list -v -keystore destiny.keystore -storepass mypassword Keystore type: jks Keystore provider: SUN Your keystore contains 2 entries: Alias name: root Creation date: Sep 22, 2003 Entry type: trustedcertentry Owner: Address=server-certs@thawte.com, CN=Thawte Server CA, OU=Certification Services Issuer: Address=server-certs@thawte.com, CN=Thawte Server CA, OU=Certification Services Serial number: 1 Valid from: Wed Jul 31 19:00:00 CDT 1996 until: Thu Dec 31 17:59:59 CST 2020 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 Certificate chain length: 2 Certificate[1]: Owner: CN=destiny.ausd.edu, OU=Allentown You should see your destiny alias certificate with a chain length of 2 (not 1). This signifies a properly signed chain. 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 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 Valid from: Wed Jul 31 19:00:00 CDT 1996 until: Thu Dec 31 15:59:59 CST 2020 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 Rev A Copyright 2010 Follett Software Company Page 9 of 11

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 Note the forward slashes / 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 [copy] Copying 1 file to C:\FSC-Destiny\jboss\server\destiny\deploy\jbosswebtomcat.sar\META-INF [copy] Copying 1 file to C:\FSC-Destiny\jboss\server\destiny\conf [copy] Copying 1 file to C:\FSC-Destiny\jboss\bin [copy] Copying 1 file to C:\FSC-Destiny\jboss\bin BUILD SUCCESSFUL Total time: 3 seconds G. Restart the Destiny server. Note: If the Destiny server is accessed through your firewall, make sure that port 443 is open. Page 10 of 11 Copyright 2010 Follett Software Company Rev A

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. Congratulations! Rev A Copyright 2010 Follett Software Company Page 11 of 11