Web Services over HTTPS

Documentation home

Introduction. 1

Certificates 1

Certificate Authority (CA) 1

Importing Certificates 2

Introduction

If the web service uses an HTTPS connection, then this will communicate using SSL. SSL, or Secure Socket Layer, is a technology which allows the web service client and remote web service server to communicate over a secured connection. The data is encrypted before being transmitted and decrypted when the data is received before processing. This is a two-way process, meaning that both the server AND the browser encrypt all traffic before sending out data. A certificate is required for SSL communication.

Certificates

A public key certificate (know just as a certificate) is a digitally-signed statement that binds the value of a public key to the identity of the person, device, or service that holds the corresponding private key. One of the main benefits of certificates is that passwords are not needed for individual clients who need to be authenticated as a prerequisite to access. Instead, the host merely establishes trust in a certificate issuer.

Most certificates used are based on the X.509v3 certificate standard.

Certificates contain the following information:

• The subject's public key value.
• The subject's identifier information, such as the name and e-mail address.
• The validity period (the length of time that the certificate is considered valid).
• Issuer identifier information.
• The digital signature of the issuer. A certificate is valid only for the period of time specified within it; every certificate contains valid from and valid to date, which set the boundaries of the validity period.

Certificate Authority (CA)

A Certificate Authority (CA) is an organization that issues certificates to other organizations that wish to prove their identity. The CA asks the certificate requester to provide information about itself and the CA gives back a certificate in return. The returned certificate is chained to the root certificate, establishing a chain of trust. In this way someone dealing with a company identifying itself through a certificate issued by a certain CA doesn't have to trust every company, but it is sufficient to trust the root CA.

Java (J2SE) recognises the common root certificates Verisign, Twarte etc...; these are stored in the JRE's lib/security/cacerts truststore. But sometimes the certificate is not recognised and the certificate must be imported into a Java keystore.

Importing Certificates

If the web service provider is using a self-signed certificate or one signed by an in-house CA, it must be imported and saved in the keystore of the client Java system. A keystore is a file that contains all the trusted certificates available for HTTPS communication between Ebase and the remote web service server. Certificates can be imported into the keystore using java’s keytool utility. The keytool is part of the standard Java Development Kit (JDK) shipment and can be found in the $JDK_HOME/bin directory. If the certificate has not been imported, a call to the web service may throw an exception such as: "ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target".

If the certificate has been signed by one of the recognised CAs, the certificate does not normally need to be imported.

Follow the instructions below to import a certificate. This example uses Internet Explorer 9 to obtain the certificate, but other browsers or equivalent tools can also be used.

If you already have the Certificate .cer file then proceed to step 9.

1. Open up a browser, open the target URL and click the secure icon (padlock).

2. Click on the view certificates.

3. Select the Certification Path tab on the open dialog, select the root certificate and click on the View Certificate button.

4. Select the Details tab on the new certificate dialog which shows the details of the root certificate. Click the Copy to File button.

5. Click the Next button on the Certificate Export Wizard.

6. Choose Base 64 encoded X.509 (.cer). Click the Next button.

7. Enter the filename and the path to store the certificate. Click the Next button.

8. Click the Finish button.

Import the certificate into the Java key store

9. Open a console window and navigate the location where the certificate is saved. Set the PATH to the JDK/bin directory: e.g set PATH=c:\jdk1.6\bin

10. Execute the command:

keytool -import -alias <alias-name> -file <certificate-filename> -keystore <keystore-filename>

Where:

o alias-name - is a memorable name to give to the certificate. This cannot already exist in the keystore.

o certificate-filename – is the saved trust certificate to import e.g geoTrust.cer

o keystore-filename – is the keystore filename to import the certificate into. If the keystore does not exist, it will be created automatically. e.g ebaseKeystore.keystore

o Enter the password for the keystore. If the keystore does not exist, enter a new password for this keystore.

The certificate is now stored within the keystore. The keystore can now be used by the Ebase for SSL authentication.

Ebase Designer and Ebase Server start-up parameters

To use the keystore created above or an existing keystore containing the required certificate; the following line (Java system property) must be added to the designer and server start-up files:

-Djavax.net.ssl.trustStore=<keystore-filename-location>

Where:

o Keystore-filename-location – is the absolute path to the keystore created in the Importing Certificates section.

Ebase Designer start-up (used for WSDL Imports using HTTPS):

11. Open the start_ebase_designer.bat (Windows) or start_ebase_designer.sh (Unix). This is located <Ebase-Installation-Directory>/UfsClient.
12. Add the system property described above to the JAVA_PROPERTIES line e.g:

set JAVA_PROPERTIES=%JAVA_PROPERTIES% -Dawt.useSystemAAFontSettings=true -Dsun.java2d.noddraw=true -Djavax.net.ssl.trustStore=<keystore-filename-location>

Ebase Server start-up:

13. Open the start_ebase_server.bat (Windows) or start_ebase_server.sh (Unix). This is located <Ebase-Installation-Directory>/UfsClient.
14. Add the system property described above to the JAVA_OPTS line e.g:

set JAVA_OPTS=-Djavax.net.ssl.trustStore=c:\Ebase\security\ebaseKeystore.keystore -Xmx512m -Djava.net.preferIPv4Stack=true -Dderby.system.home=%~dsp0/DB

Windows Service:

If the Ebase Server is running as a windows service:

1. Stop the Ebase Server
2. Remove the service: type service.bat –remove or service.bat –remove <service-name> (where <service-name> is the name of the service when installed), followed by the enter key.
3. Open the service.bat located in <Ebase-Installation-Directory>/UfsServer/tomcat/bin.
4. Locate “:doInstall” (normally located towards the bottom of the script file).
5. add -Djavax.net.ssl.trustStore=<keystore-filename-location> to ++JvmOptions section
6. Save the file and exit.
7. Open a command window and navigate to the location of the service.bat
8. Install the service: type service.bat –install or service.bat –install <service-name> (where <service-name> is the display name of the service), followed by the enter key.