DevPortal

How do I configure Secure Sockets Layer?

Table of Contents

How do I configure Secure Sockets Layer?

Pramati Server provides support for Secure Sockets Layer (SSL) 3.0. SSL may be used for providing Secure Communications and for Authenticating. Pramati Server SSL provides two key functionalities:

Securing the Server involves ensuring that all communication with the server happens on a secure, encrypted channel. The most common mechanism to trigger the SSL access is using HTTPS.

Pramati Server can be secured using a digital certificate with a public key as Public key cryptography uses certificates to prevent impersonation over a public domain network. Server provides this feature through the standard implementation of Java Secure Sockets Extension 1.0.2 (JSSE). This standard enables you to utilize secure, encrypted communication channels in the applications, which, in turn, simplifies application development by serving as a building block that you can integrate directly into the applications.

JSSE 1.0.2 provides Secure Sockets Layer (SSL) version 3.0, and Transport Layer Security (TLS) version 1.0 support to the Java 2 platform.

In certain critical application installations, there may be a need to ensure that strictly only authorized clients access the server instance and the application. This may be needed over and above the standard J2EE authentication (login) and Authorization mechanisms available to applications.

In Pramati Server, this mode is enabled by requiring a two-way SSL. Two-way SSL requires that both Server and the Client possess valid certificates. A certificate is valid if it is signed by a trusted Certifying Authority (CA). For the Server to trust the Client, the CA signing the client certificate must be registered with the server. In such a case, the Server accepts communication requests from clients posting certificates issued by one of the registered CAs.

For the client to trust the server, the CA signing the client certificate must be registered with the client.

For more details about SSL concepts, read Working with SSL on Pramati Server.

How do I configure Server for HTTPS Requests?

Perform the following steps to configure Server for HTTPS Requests:
  1. Open the server-config.xml. For both the Standalone Server and Cluster, the file is at <install_dir>/server/nodes/<node_name>/config/.
  2. Locate the following under the services tag: 
    <service name="WebContainer" enabled="true" class-name="com.pramati.web.WebServer">
  <property name="https-port" value="443"/>
</service>
  3. By default, the is set as 443. Set this value to the required HTTPS port.
  4. Open the web-config.xml. For both the Standalone Server and Cluster, the file is at: <install_dir>/server/nodes/<node_name>/config/.
  5. Locate the following tag under the web-container tag: <protocol http-enabled="true" ssl-enabled="false"/>
  6. By default, the <protocol http-enabled="true" ssl-enabled="false"/>. Set ssl-enabled to true as <protocol http-enabled="true" ssl-enabled="true"/>.
  7. If you require SSL mutual authentication, set the client-auth-require tag to true. This implies that the Server and the client should trust and authenticate each other's certificates before communication can begin. If you have enabled SSL and disabled client authentication, the Server accepts SSL connections but will not enforce SSL client authentication. Server uses the Trusted CA Certifications keystore to authenticate the client certificate. The client refers to its own trusted keystore to authenticate the Server.
  8. The client-auth-require tag is present under the <ssl _moz-userdefined=""> tag in web-config.xml.
  9. Save the changes and restart Server.

How do I configure Server for RMI over SSL Communication?

To enable RMI over SSL communication:

  1. Open the server-config.xml. For both the Standalone Server and Cluster, the file is at <install_dir>/server/nodes/<node_name>/config/.
  2. By default, the ssl-protocol-enabled attribute, present under the rmi-properties tag under the server-node tag is set as false. Set the tag to true. 
    <server>
  <server-node name="default" type="J2EE">
   <default-login-info username="root" password="pramati" realm="system"/>
   <rmi-properties socket-time-out="10" export-port="0" ssl-export-port="0" ssl-protocol-enabled="true"/>
   <class-file-server port="5020"/>
  <server-node>
  3. If you require mutual authentication, set the needMutualAuthentication property to true. This implies that server and client should trust each other's certificates and authenticate each other before communication begins. Server uses Trusted CA Certifications keystore to authenticate the client certificate. The client refers to its trusted keystore for authenticating the server. This property is optional.
  4. The needMutualAuthentication property is present under the init-options tag, under the rmi-ssl tag, in the security-config.xml. For both the Standalone Server and Cluster, the file is at <install_dir>/server/nodes/<node_name>/config/.
  5. Set the needMutualAuthentication property to true as: 
    <rmi-ssl>
  <other tags>
  <init-options>
    <entry>
      <name>needMutualAuthentication<name>
      <value>true<value>
    <entry>
  <init-options>
  <other tags>
<rmi-ssl>
  6. Save the changes and restart the Server.

Any communication between server and client now proceeds smoothly.

How do I use Certificates with Pramati Server?

SSL communication involves the following types of certificates:

These certificates are stored in the following two keystores:

Both these keystores can be protected with different passwords. The default password is pramati. It is a good practice to change the password periodically. For both the Standalone Server and File-based Clusters, the keystore is located at <install_dir>/server/nodes/<node_name>/config/.

Administrators need a public and private key and a certificate signed from a CA. Pramati Server provides support from the Console for generating server-side certificates. These are self-signed certificates. To make this a trusted certificate, a Certificate Signing Request (CSR) can be generated and sent to a CA, like Verisign, for signing. The signed certificate is imported into the Server keystore.

How do I manage Security Certificates using the Console?

Select Configure > Security Certificates in the Explore panel of the Console. This displays details regarding:

What are Server Certificates?

This section displays details regarding the Server certificates which are sent to the client in SSL. The details provided are:

Table 1: Server certificates

FieldsDescription
AliasAn alias name for the Server certificate.
Issued ByName of the issuer of the certificate.
Issued ToName of the requestor the certificate was issued to.
ValidityDate upto which the issued certificate is valid.
AddUse this to add a new Server certificate.
DeleteUse this to delete a Server certificate.
Change keystore PasswordUse this to make changes to the keystore password. Read the section ‘Changing the keystore password’ below.

What details are provided for Certificates issued by Certification Authorities?

This section displays details regarding the certificates that have been certified by the CAs. The details provided are:

Table 2: Certification Authority Certified Certificates

FieldsDescription
AliasAlias names for the Certification Authorities trusted by Server.
Issued ByName of the issuer of the certificate.
Issued ToName of the requestor the certificate was issued to.
ValidityDate upto which the issued certificate is valid.
AddUse this to add a new Certification Authority certified Certificate.
DeleteUse this to delete a Certification Authority certified Certificate.
Change keystore PasswordUse this to make changes to the keystore password. Read the section Changing the keystore password below.

How do I set up Server Certificates?

The following steps are involved in setting up a Server Certificate:
  1. Generating a Server Certificate
  2. Generating a CSR and Certifying a Public key through a third-party
  3. Importing Signed Certificates

Note: You can add certificates to the keystore of the server configuration during runtime using the Console. However, these will take effect only after you restart the server because the SSLSocketFactories are not refreshed.

These certificates assist in:

How do I add Server Certificates?

To add a Server Certificate:
  1. Click Add in the Server Certificate section. The Security > Certificate screen is displayed.
  2. Enter an alias with which the pair is identified.
  3. Enter the following details about the user generating the Server Certificate:
    1. Name
    2. Department
    3. Organization
    4. City
    5. State
    6. Country
    7. Validation Duration
  4. Select the cipher suite Key Algorithm used to encrypt the key using the drop-down list. The options provided are RSA and DSA.
  5. Select the Key Size in bits using the drop-down list. The options provided are 512, 1024, and 2048. The greater the size of the key, the more difficult it would be to crack it.
  6. Select the algorithm used for generating the signature of the certificate using the drop-down list. The options provided are MD5 with RSA and SHA1 with DSA.
  7. Click Save.

The Server Certificate is generated. It is stored in the keystore (ServerCerts) and added to the table of server certificates.

Note: Popular browsers Netscape and IE expect the Server certificates to be RSA based. DSA based certificates are not accepted by these browsers. For more information, refer http://java.sun.com/products/jsse/doc/guide/API_users_guide.html.

How do I generate Certificate Signing Request using Third-Parties?

The certificate that is generated using Server is a self-signed certificate. For getting the certificate signed by a CA, a Certificate Signing Request (CSR) must be sent to the CA. To generate the CSR:
  1. In the Console, select Configure > Security Certificates in the Explore panel.
  2. Click the desired Alias name link (Server Certificate) for which the CSR has to be generated. The Security > Server Certificate screen is displayed. All the details related to the selected Alias name are displayed.
  3. Click Save CSR. This prompts a message if you wish to save the file to disk or open it. Select Save this file to disk and specify the directory in which the file is to be stored.

Once the CSR is generated, the CSR file has to be mailed as an attachment to the CA. The CA adds a public key to the public key sent by you and a chain of certificates is generated.

In the Certificate Signing Request Reply section, select the downloaded file using the browse option. Click Import to import the signed certificate into the Server keystore.

The public key combination is associated with the relevant private key and stored as .cer file in the configuration directory of the Server node. The certificate is now certified.

How do I import Server Certificates?

To import a Server Certificate reply:
  1. In the Console, select Configure > Security Certificates in the Explore panel.
  2. Click the desired Alias name link in the Server Certificate section for which the CSR reply has to be imported. The Security > Server Certificate screen is displayed.
  3. Specify the location from which the CA certified certificate is to be imported in the Certificate Signing Request Reply section.
  4. Click Import.

How do I export Server Certificates for Java Clients?

In SSL handshake, when the Server sends certificate to the client, the client must trust this certificate. For the client to trust it, the Server Certificate signed by the CA must be present in the clients Trusted CA store.

To export a certificate so that it can be placed in the clients Trusted CA store:

  1. In the Console, select Configure > Security Certificates in the Explore panel.
  2. Click the desired Alias name link in the Server Certificate section for which the server certificate has to be exported. The Security > Server Certificate screen is displayed.
  3. Click Export and specify the directory to which the file is saved. Export the public key certificate as a mail attachment.
The certificate is stored in X509 format and exported as a .cer file.

How do I deploy applications in Secure Mode?

Some of the enterprise applications deployed on the server might be returning or accepting sensitive information as method parameters. To prevent network eavesdropping, communication between the client and the application may be encrypted. To do this, applications may be deployed in the secure mode and then accessed from browsers and Java clients.

How do I secure bean components with SSL?

While deploying a bean in Server you can mark it as a secure bean. This automatically encrypts all the network calls between the clients and the enterprise beans, transparent to the application developer.

Deploying beans in the secure mode can be applied selectively for individual beans using Deploy Tool. To deploy individual beans in the secure mode:

  1. Start the Deploy Tool using Start > Programs > Pramati <version no.> > Deploy Tool.
  2. Open the selected application and click Bean Properties.
  3. Select the SSL property and click Save.
The individual bean is secured.

How do I secure Web Components with SSL?

To deploy Web components in a secure mode, modify the transport-guarantee tag in the web.xml file. This file is stored in the application’s war file. The transport-guarantee element defines the communication between client and server and can take three values:

If you specify Integral or Confidential, it implies that SSL is required for transmission. For example:

<security-constraint>
....<other tags>
	<user-data-constraint>
		<description>No Description<description>
		<transport-guarantee>Integral<transport-guarantee>
	</user-data-constraint>
<security-constraint>

How do I access secured applications using browsers?

To access a secure document using a browser, enter the location of the deployed application in the browser as https://<host on which the server is running>:<port number on which the secured list is started>/<context root>/.

A certificate is sent by Server to the client. This must be accepted by the client for transmission to proceed.

If you do not specify a port number in the URL, the default port 443 is assumed. However, you can configure the port number to any value in the server-config.xml file. For both Standalone Server and cluster, this file is located at <install_dir>/server/nodes/<node_name>/config/.

To configure the HTTPS port:

  1. Open the server-config.xml. The file is located at <install_dir>/server/nodes/<node_name>/config/.
  2. Locate the following tag under the services tag: 
    <service name="WebContainer" enabled="true" class-name="com.pramati.web.WebServer">
  <property name="https-port" value="443"/>
</service>
  3. By default, the is set as 443. Set this value to the required HTTPS port.
  4. Save the file. The HTTPS port value is changed.

How do I access secured applications using Java Clients?

When a Java client tries to access beans from a server, the user name and password can be accessed by the other users. To avoid this, and provide a greater security, the applications use SSL. When an application is thus accessed, all critical information is passed in an encrypted format, which is decrypted only by the bean being accessed.

To access beans deployed using SSL, the Java client must store the Server’s public key in the following key store in the default directory under Java home: java home\jre\lib\cacerts

To perform a secure look up using SSL, the client must set ssl in the security protocol as:

Properties props = new Properties();
props.put(Context.PROVIDER_URL, "rmi://"+Host+":"+details.port);
props.put(Context.INITIAL_CONTEXT_FACTORY,
  "com.pramati.naming.client.PramatiClientContextFactory");
  props.put(context.SECURITY_PROTOCOL,"ssl");

Note: Using SSL may slow down the speed of access, hence it is advisable to authenticate specific beans that need to be provided the maximum security.

How do I use SSL Certificates for Client Authentication?

SSL can be used to authenticate clients accessing applications. If SSL communication needs client authentication, the client will be asked to provide its certificate during the SSL-Handshake. The communication will proceed only if the server trusts the CA which issued this client certificate. Pramati Server permits SSL-based client authentication. Client authentication can be done both in HTTPS and RMI-SSL. In both cases Trusted CAs must be setup in the Server. Add the CA certificate that the server should trust to this trusted CA certificate store.

How do I set up two-way SSL?

The following steps are required to set up a two-way SSL: Note: You can add certificates to the Key store of the Server configuration during runtime using the Console. However, these will take effect only after you restart the server because the SSLSocketFactories are now refreshed.

How do I set up Trusted CA Keystores?

The CA certificate the server should trust must be added to this trusted CA certificate store and the certificates issued to the clients, must be from this CA.

Client-side certificates are typically generated outside the Server, and signed through a CA that is trusted by the Server. The Console provides the tool to register trusted CAs. The information on trusted CAs is placed in the Trusted CA keystore.

To import a Certificate Certified by the Certification Authority:

  1. In the Console, click Configure > Security Certificates in the Explore panel.
  2. Click Add in the Certification Authority trusted by Server section. The Security > Certification Authority Certified screen is displayed.
  3. Provide the Alias name and browse for the Certification Authority Certificate that has to be imported.
  4. Click Import. This imports the certificate into the trustedcacerts keystore of the server.

How do I enable Client Authentication?

Client authentication may be enabled for:

How do I set up Client Authentication in HTTPS?

Client authentication in HTTPS requires:

Enabling two-way SSL

In web-config.xml, under web-container tag, change client-auth-require to true as:

<ssl>
  <client-auth-require>true</client-auth-require>
</ssl>
Set up the Trusted CAs in the Server. Add the CA certificate whom the server should trust. The certificates issued to the clients must be from this CA.

Setting up application's web.xml

Application can define a set of pages which can be transported only over HTTPS using web.xml. You can add security-constraint tag in the web.xml to specify the set of URL patterns, which will use HTTPS. Given below is a snippet from web.xml:

<security-constraint>
	<web-resource-collection>
		<web-resource-name>txPages<web-resource-name>
		<description>No Description<description>
		<url-pattern>/bank/*<url-pattern>
		<http-method>GET<http-method>
	<web-resource-collection>
	<auth-constraint>
		<description>No Description<description>
	<auth-constraint>
	<user-data-constraint>
		<description>No Description<description>
		<transport-guarantee>INTEGRAL<transport-guarantee>
	</user-data-constraint>
</security-constraint>

In the above snippet, all the pages which satisfy the given URL pattern will be secured according to user-data-constraint. If the transport-guarantee is INTEGRAL or CONFIDENTIAL, the communication will use HTTPS, else it will be over HTTP.

How do I set up Client Authentication in RMI over SSL?

Client authentication for a Java client participating in RMI over SSL needs:

Enabling two-way SSL

In security-config.xml, under init-options under rmi-ssl define an entry for needMutualAuthentication and set its value to true.

<rmi-ssl>
  <server-socket-factory> com.pramati.util.socket.DefaultRMISSLServerSocketFactory </server-socket-factory>
  <client-socket-factory> com.pramati.util.socket.DefaultRMISSLClientSocketFactory </client-socket-factory>
  <init-options>
	<entry>
		<name>needMutualAuthentication<name>
		<value>true<value>
	<entry>
  <init-options>
<rmi-ssl>

Setting up VM Properties using Java Client

The Java Client, which is participating in RMI-SSL, must set these properties to VM:

What is Authorization?

If an application uses SSL with client-authorization enabled, and the application is marked with standard J2EE security, then in addition to authenticating the clients using the certificates, the client will also be required to login. The client ID in the certificate used to authenticate through the SSL will not be used for the J2EE Security Authorizations.

How do I generate Client-side Certificates outside Pramati?

If certificates are generated outside Pramati Server, the trusted CAs who are signing the client-side certificates need to be registered with the Server, and two-way SSL needs to be enabled.

To get the key certified by a third party CA like Verisign, send the certificate signing request to the CA.

How do I generate Client-side Certificates locally?

If the client-side certificates are to be generated within Pramati, the following steps are involved:
  1. Setting up OpenSSL (available pre-configured on Linux)
  2. Creating the CA to issue the client certificate
  3. Registering the CA as a trusted CA with the Server

How do I set up OpenSSL?

  1. Install OpenSSL (this is pre-configured on Linux).
  2. Create a certificate directory /certs under the Server Installation Directory.
  3. If the scripts, CA.sh and sign.sh, are not available in the OpenSSL directory, create the scripts as produced below.

How do I create Certification Authorities?

  1. Change directory to /certs and ensure that OpenSSL bin directory is in the PATH
  2. Generate ca.key using the command openssl genrsa -des3 -out ca.key 1024
  3. Generate ca.crt using the command openssl req -new -x509 -days 365 -key ca.key -out ca.crt

How do I register Certification Authorities as Trusted CAs with Server?

Trusted CAs can be registered with the Server using the Console.
  1. Select Configure > Security Certificates in the Explore panel.
  2. In the Certification Authorities trusted by Server section, click Add.
  3. In the screen that is displayed, enter the Alias name of Certificate and get the location of the certificate (ca.crt, created above).
  4. Click Import.

How do I export Certification Authority Certified Certificates?

To export a certificate:
  1. In the Console, select Configure > Security Certificates in the Explore panel.
  2. Click the desired Alias name link in the Certification Authorities trusted by Server section for which the Certification Authority Certified Certificate has to be exported. For example, thawteserverca. The Security > Trusted Certificate screen is displayed.
  3. Click Export and specify the directory to which the file is saved. Export the certificate as a mail attachment.

The certificate is stored in X509 format and exported as a .cer file.

How do I generate Client Certificate for Clients?

Create Client Certificate using sh CA.sh -newreq. This prompts for the information on the client for whom the certificate is generated.

How do I sign and send Certificates?

  1. Sign the Client Certificate with CA key using sh sign.sh newreq.pem
  2. Extract the key into a separate file using openssl rsa newkey.pem
  3. Export the generated .pem file into pkcs12 format using openssl pkcs12 -export -in newreq.crt -inkey newkey.pem -out client.p12 openssl pkcs12 -export -in ca.crt -inkey ca.pem -out ca.p12
  4. Send the Client Certificate (client.p12) to the client machine.

How do I set up Certificates on Client Machines?

Instructions to set up the certificate depend on the client environment. For Internet Explorer, the steps are below:
  1. Click Tools > Internet Options > Content > Certificates > Import.
  2. In the Certificate Import Panel, select the certificate (client.p12) and click Import.

How do I change Keystore Passwords?

Both the server and trusted keystores are protected by a password. The default password for both the keystores is pramati. However, you can change this value. Also, the passwords can be different for each of the keystores. To change the keystore password:
  1. Select Configure > Security certificates.
  2. Click Change Keystore Password in the Server Certificates or the Certification Authorities trusted by Server section, as required. This displays the Security > Change Keystore Password screen.
  3. Enter old password.
  4. Enter new password.
  5. Re-enter new password for confirmation.
  6. Click Save.
The password is changed. This change is reflected when you start the server the next time.

© Pramati Technologies 2007 Runs on Pramati Server | Feedback | Legal