[Sblim-commit] jsr48-client/src/org/sblim/cimclient/doc-files secure_indications.html, NONE, 1.1.2.

SourceForge Headquarters 225 Broadway Suite 1600 San Diego, CA 92101 +1 (858) 422-6466

Update of /cvsroot/sblim/jsr48-client/src/org/sblim/cimclient/doc-files
In directory vz-cvs-3.sog:/tmp/cvs-serv16074/src/org/sblim/cimclient/doc-files

Added Files:
      Tag: Experimental
	secure_indications.html 
Log Message:
3536398 - Update HTML: add secure_indications.html

--- NEW FILE: secure_indications.html ---
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<!--
 *
 * (C) Copyright IBM Corp. 2012
 *
 * THIS FILE IS PROVIDED UNDER THE TERMS OF THE ECLIPSE PUBLIC LICENSE 
 * ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS FILE 
 * CONSTITUTES RECIPIENTS ACCEPTANCE OF THE AGREEMENT.
 *
 * You can obtain a current copy of the Eclipse Public License from
 * http://www.opensource.org/licenses/eclipse-1.0.php
 *
 * @author : Dave Heller, IBM, hel...@us...
 *
 * Change History
 * Flag       Date        Prog         Description
 *-------------------------------------------------------------------------------
 * 3536398    2012-08-20  hellerda     Update HTML to reflect secure indication support
-->
</head>
<body style="background-color: white;">

<h1>Getting Started with Secure Indications</h1>
<a href="#intro">Introduction</a><br />
<a href="#global">Global Keystore Configuration</a><br />
<a href="#configs">Configurations for secure indication listener</a><br />
<a href="#c1">"No authentication" configuration</a><br />
<a href="#c2">"CIMOM authentication" configuration</a><br />
<a href="#c3">"Listener authentication" configuration</a><br />
<a href="#c4">"Mutual authentication" configuration</a><br />
<a href="#independent">Configuring client and listener keystores independently</a><br />
<br />
<a id="intro" name="intro" /><h2>Introduction</h2>

The following text will explain how to configure a secure indication listener for the SBLIM CIM Client for Java.
It is suggested the reader first review <a href="secure.html">Getting Started with Secure Connections</a>, as this document relies on the topics covered there.
As described in <a href="indications.html">Getting Started with Indications</a>, indication delivery reverses the role of of HTTP client and server. The indication sender (typically the CIMOM) is now the HTTP client and the indication listener is the HTTP server.
For SSL/TLS (HTTPS) connections, configuration of a keystore is optional for the HTTPS client. For a HTTPS server however, a keystore is mandatory. This is because the keystore contains the private key the server will use to initiate encryption for the connection. So we must configure a keystore to enable a secure indication listener.
The keystore also contains the certificate the HTTPS server (i.e. the indication listener) will use to assert its identity. The HTTPS client (the indication sender or CIMOM) may optionally choose to verify the server cert against the contents of its own truststore.

Similarly, the listener may choose to verify the certificate of the indication sender. To do this we need to additionally configure a truststore for the listener.

<a id="global" name="global" /><h2>Global Keystore Configuration</h2>

SSL/TLS authentication is X509 certificate-based. Each side provides a X509 certificate that confirms its identity. The certificates are 
exchanged and each side validates the received certificate against a local copy.

For the listener, just as for the client, two files are used to store the certificates: a keystore and a truststore. The process for managing the keystores is described in <a href="secure.html">Getting Started with Secure Connections</a>. The following properties allow you to configure the keystores:

   <ul>
     <li><em>javax.net.ssl.keyStore</em>: The file path of the SSL keystore.</li> 
     <li><em>javax.net.ssl.keyStoreType</em>: The type of the SSL keystore repository. Typically this is <i>JKS</i> or <i>Java KeyStore</i> type, which is the default.</li> 
     <li><em>javax.net.ssl.keyStorePassword</em>: The password of the keystore.</li> 
     <li><em>javax.net.ssl.trustStore</em>: The file path of the SSL truststore.</li> 
     <li><em>javax.net.ssl.trustStoreType</em>: The type of the SSL truststore repository. Typically this is <i>JKS</i>, which is the default.
     <li><em>javax.net.ssl.trustStorePassword</em>: The password of the truststore.</li> 
   </ul>

When these properties are configured globally, by either setting their values in the properties file or setting them programmatically via a call to <code>System.setProperty()</code>, their values will be effectively set for both the client and listener (they will in fact be be set for all new instances of client and listener). This means the client and listener will share the same set of keystores, even though they access these these keystores for entirely independent roles.

It is also important to understand: with global configuration, the keystore and truststore are automatically activated whenever their respective configuration properties are set. This is true for both client and listener. Put another way, if a keystore or truststore is configured at the global level it is activated for both client and listener, even if this is not the intended action. The side effects are described in the table below.

There is currently no way to control the activation of the keystore for client and listener independently when the properties are configured globally. If you activate the keystore for the listener (as is required for SSL) it will be activated for the client as well, and the client will now begin to send a certificate during its SSL handshake. This would cause a change in behavior only if the CIMOM is conifigured for optional peer verification. If it is, and the CIMOM is unable to verify the new client certificate, the connection would fail. To fix this you must either import the client certificate to the CIMOM's truststore, or disable peer verification at the CIMOM.

Finally, there is a way to set the keystore properties independently between client and listener, and in this manner it is possible to configure a separate set of keystores for each. However, this cannot be done via the properties file; it can only be done programmatically. This is described <a href="#independent">here</a>.

<a id="configs" name="configs" /><h2>Configurations for secure indication listener</h2>

The table below shows the possible keystore configurations for the listener. Note we refer to the CIMOM in its capacity as indication sender, not server.
<table border="1" cellpadding="5">
 <tr><th>Configuration</th><th>Encryption/Hashing</th><th>CIMOM authenticated</th><th>Listener authenticated</th><th>Side effect if configured globally</th></tr>
 <tr align="center"><td><a href="#c1">No authentication</a></td><td>yes</td><td>no</td><td>no</td><td>client now sends cert</td></tr>
 <tr align="center"><td><a href="#c2">CIMOM authentication</a></td><td>yes</td><td>yes</td><td>no</td><td>client now authenticates CIMOM</td></tr>
 <tr align="center"><td><a href="#c3">Listener authentication</a></td><td>yes</td><td>no</td><td>yes</td><td>client now sends cert</td></tr>
 <tr align="center"><td><a href="#c4">Mutual authentication</a></td><td>yes</td><td>yes</td><td>yes</td><td>client now authenticates CIMOM and sends cert</td></tr>
</table>

<a id="c1" name="c1" /><h2>"No authentication" configuration</h2>
<ul>
    <li>Confidentiality: given</li>
    <li>Integrity: given</li>
    <li>Authentication: no</li>
    <li>Keystore: always required</li>
    <li>Truststore: No</li>
</ul>

As previously stated we must always configure a keystore to enable a secure listener. Follow the procedure here to <a href="secure.html#keystore">create a keystore</a> and set the appropriate configuration properties. Once this is done the keystore will be activated and the listener will be capable of receiving secure indications.

The process for creating a new indication listener is described <a href="indications.html#setup">here</a>. The sample code supports either a http or https listener. Don't forget to change "http" to "https" in the CIM_ListenerDestinationCIMXML instance when creating a secure subscription.

Note: The indication sender CIMOM (i.e. the indication sender) may be configured to send its own X509 certificate. In this scenario we decided not to evaluate this certificate..

Note: Because the listener acts as a HTTPS server it will always present its certificate to the client (the indication sender or CIMOM). The CIMOM is free to verify the listener cert if desired. See your CIMOM documentation to determine if this feature is available. If so, the configuration will likely involve importing the listener certificate into the CIMOM truststore. See <a href="secure.html#export">exporting a certificate</a> for a description on how to export a certificate from your keystore so that you can import it into the CIMOM's truststore.

Note also: if the keystore properties are configured globally the keystore will be activated for (Java CIM) client as well as the listener. This may have unintended consequences if your CIMOM is configured to check the client cert. See <a href="#c3">client authentication</a> for a details.

<a id="c2" name="c2" /><h2>"CIMOM authentication" configuration</h2>
<ul>
    <li>Confidentiality: given</li>
    <li>Integrity: given</li>
    <li>Authentication: CIMOM only</li>
    <li>Keystore: always required</li>
    <li>Truststore: required</li>
</ul>
<p>In this scenario we configure the listener to check the identity of the CIMOM (i.e. the indication sender). To do this we need to <a href="secure.html#truststore">create a truststore</a> and set the appropriate configuration properties. Once this is done the truststore will be activated and the listener will automatically check the CIMOM certificate against the truststore.
Everything else is equal to the "no authorization" configuration</p>
<p>Note: In this scenario we will check  the CIMOM's X509 certificate. In order to do that we have to
import the CIMOM's certificate into our truststore. See <a href="secure.html#import">importing a certificate</a> for 
details.</p>

Note: Because the listener acts as a HTTPS server it will always present its certificate to the client (the indication sender or CIMOM). The CIMOM is free to verify the listener cert if desired.

Note also: if the truststore properties are configured globally the truststore will be activated for (Java CIM) client as well as the listener. The client will now attempt to verify the CIMOM on every CIM request, which will cause the requests to fail unless the CIMOM certificate has been imported into the truststore as described <a href="secure.html#c2">here</a>. (Assuming the cert is different from the one you already imported for listener operation; in most cases it will be the same).

<a id="c3" name="c3" /><h2>"Listener authentication" configuration</h2>
<ul>
    <li>Confidentiality: given</li>
    <li>Integrity: given</li>
    <li>Authentication: listener only</li>
    <li>Keystore: always required</li>
    <li>Truststore: no</li>
</ul>
<p>In this scenario we configure the CIMOM (i.e. the indication sender) to check the identity of the listener. As previously stated, the listener will <i>always</i> present its certificate to the indication sender, so there is no further configuration required on the listener side. All that is required  is to enable listener verification at your CIMOM. See your CIMOM documentation to determine if this feature is available.  If so, the configuration will likely involve importing the listener certificate into the CIMOM truststore. See <a href="secure.html#export">exporting a certificate</a> for a description on how to export a certificate from your keystore so that you can import it into the CIMOM's truststore.</p>

Note: In this scenario we decided not to evaluate the CIMOM's X509 certificate. The listener can be configured to do that as described above.

Note also: if the keystore properties are configured globally the keystore will be activated for (Java CIM) client as well as the listener. This may have unintended consequences if your CIMOM is configured to check the client cert. See <a href="#c3">client authentication</a> for a details.

<a id="c4" name="c4" /><h2>"Mutual authentication" configuration</h2>
<ul>
    <li>Confidentiality: given</li>
    <li>Integrity: given</li>
    <li>Authentication: listener and CIMOM</li>
    <li>Keystore: always required</li>
    <li>Truststore: required</li>
</ul>

<p>In this scenario we configure certificate validation in both directions simultaneously.</p>

<p>In short, this configuration comprises the &quot;CIMOM authentication&quot; and &quot;Listener authentication&quot; together.</p>

Remember, if the keystore or truststore properties are configured globally, the keystore or truststore will be activated for the client as well as the listener. If this is not your intent you must set the keystore configurations independently.

<a id="#independent" name="independent" />
<h2>Configuring client and listener keystores independently</h2>

While it is not possible to configure client and listener keystores independently via the global configuration, it is possible to do so programmatically, by setting the desired property on the client or listener object directly, using the object's <code>setProperty()</code> method. In the case of the client this must be done after obtaining a reference to the client object but before the call to <code>initialize()</code>. For the listener it is done after obtaining the listener object but before the call to <code>addlistener()</code>.

<p>The ablity to configure client and listener keystores independently has two basic applications:</p>

<ol>
    <li><u>It allows the use of separate keystore/truststore files for client and listener</u>. For most applications this should not be necessary.  Understand that sharing a truststore between client and listener does not mean you are limited to a single CA certificate for both, since a truststore can contain more than one certificate. The same is not exactly true for the keystore:  While a keystore can contain more than one key pair, the Java CIM Client's KeyManager will use the first acceptable key pair it finds in the keystore in order to complete the SSL handshake.  So there is no simple way to make the client use one key pair and the listener use another. If your application requires this you must separate the client and listener keystores. The circumstances where this is required would be unusual, since it is most common in a public key infrastructure to assign a single indentity to an endpoint, and this technique would actually assign two indentities to the endpoint. Nevertheless it is supported.
    <li><u>It allows peer authentication to be enabled separately for client and listener</u>.  When the truststore is configured globally it is automatically enabled for both client and server even if this is not the intent. Configuring the truststore independently allows peer authentication (a.k.a. peer verification) to be controlled independently as well, since any property set on the client or listener directly will override the global value of that property.  So there are two strategies here: you can either forego setting the truststore properties globally and set them only on the client or listener as required; or, you can force peer verification off for client or listener by setting the truststore path to a null string. The latter is recommended as it ensures it will not be inadvertently enabled if the global configuration is later modified.
</ol>

<p>For the client, using the code snippet in <a href="firststeps.html">First Steps</a> as a reference: to configure a truststore for use solely by the client, insert the following lines after the call to <code>getClient()</code> but before the call to <code>client.initialize()</code>:</p>
<div style="border: 1px dashed #3c78b5; font-size: 14px; font-family: Courier; margin: 10px; line-height: 17px;">
<div style="background-color: #f0f0f0; padding: 3px;"><pre>
client.setProperty(WBEMConfigurationProperties.TRUSTSTORE_PATH, "/path/to/client/truststore.pks");
client.setProperty(WBEMConfigurationProperties.TRUSTSTORE_PASSWORD, "password");
</pre></div></div>

<p>To disable peer verification for the client:</p>

<div style="border: 1px dashed #3c78b5; font-size: 14px; font-family: Courier; margin: 10px; line-height: 17px;">
<div style="background-color: #f0f0f0; padding: 3px;"><pre>
client.setProperty(WBEMConfigurationProperties.TRUSTSTORE_PATH, "");
</pre></div></div>

<p>For the listener, using the code snippet in <a href="indications.html#setup">Setting up an indication listener</a> as a reference: to configure a truststore for use solely by the listener, insert the following lines after the call to <code>getListener()</code> but before the call to <code>listener.addListener()</code>:</p>

<div style="border: 1px dashed #3c78b5; font-size: 14px; font-family: Courier; margin: 10px; line-height: 17px;">
<div style="background-color: #f0f0f0; padding: 3px;"><pre>
listener.setProperty(WBEMConfigurationProperties.TRUSTSTORE_PATH, "/path/to/listener/truststore.pks");
listener.setProperty(WBEMConfigurationProperties.TRUSTSTORE_PASSWORD, "password");
</pre></div></div>

<p>To disable peer verification for the listener:</p>

<div style="border: 1px dashed #3c78b5; font-size: 14px; font-family: Courier; margin: 10px; line-height: 17px;">
<div style="background-color: #f0f0f0; padding: 3px;"><pre>
listener.setProperty(WBEMConfigurationProperties.TRUSTSTORE_PATH, "");
</pre></div></div>

Finally, note it is also possible to control the listener configuration by creating a new <code>java.lang.Properties</code> object and passing it to <code>addListener()</code>, as shown in the example <a href="indications.html#example2">here</a>. The result will be the same as the example above. If for some reason both methods are used, the properties passed to <code>addListener()</code> will take precedence.

</body></html>

[Sblim-commit] jsr48-client/src/org/sblim/cimclient/doc-files secure_indications.html, NONE, 1.1.2.

[Sblim-commit] jsr48-client/src/org/sblim/cimclient/doc-files secure_indications.html, NONE, 1.1.2.1