Menu
▾
▴
[Sblim-commit] jsr48-client/src/org/sblim/cimclient/doc-files configuration.html, 1.5.2.5, 1.5.2.6 indications.html, 1.5.2.9, 1.5.2.10 secure.html, 1.3.2.4, 1.3.2.5
|
From: Dave H. <hel...@us...> - 2012-08-20 18:44:49
|
Update of /cvsroot/sblim/jsr48-client/src/org/sblim/cimclient/doc-files
In directory vz-cvs-3.sog:/tmp/cvs-serv16186/src/org/sblim/cimclient/doc-files
Modified Files:
Tag: Experimental
configuration.html indications.html secure.html
Log Message:
3536398 - Update HTML to reflect secure indication support
Index: indications.html
===================================================================
RCS file: /cvsroot/sblim/jsr48-client/src/org/sblim/cimclient/doc-files/indications.html,v
retrieving revision 1.5.2.9
retrieving revision 1.5.2.10
diff -u -d -r1.5.2.9 -r1.5.2.10
--- indications.html 3 Jan 2012 23:14:51 -0000 1.5.2.9
+++ indications.html 20 Aug 2012 18:44:47 -0000 1.5.2.10
@@ -24,6 +24,7 @@
* 2972697 2010-03-18 blaschke-oss Fix spelling errors in HTML files
* 2990370 2010-04-22 blaschke-oss Development/unittest HTML out of date
* 3469210 2012-01-03 blaschke-oss Include reliable indications in HTML
+ * 3536398 2012-08-20 hellerda Update HTML to reflect secure indication support
-->
</head>
<body style="background-color: white;">
@@ -32,7 +33,7 @@
</p>
<p> The delivery of indications reverses the roles of client and server. The CIMOM acts as HTTP client, the SBLIM CIM Client for Java as an HTTP server. The indication delivery is asynchronous and completely independent from an open client-to-CIMOM connection.
</p>
- <h2>Setting up an indication listener</h2>
+ <a id="setup" name="setup" /><h2>Setting up an indication listener</h2>
<p>The following code snippet illustrates how to set up a simple indication 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: 10px;">
@@ -142,6 +143,7 @@
<li><em>sblim.wbem.listenerDeliveryRetryInterval</em>: Sets the default value to use for the CIM_IndicationService DeliveryRetryInterval property. This value should match the value of the property of the CIM_IndicationService instance on the CIMOM dispatching the indications.</li>
<li><em>sblim.wbem.listenerReliableIndicationHashtableCapacity</em>: Sets the default value to use for the reliable indication handler's initial hash table capacity. A value of 0 indicates use a linked list instead. Linked lists are better suited for a small number of listener destinations per WBEMListener while hash tables are better suited for a large number.</li>
</ul>
+ <a id="example2" name="example2" />
<p>The following code snippet illustrates how to set up a simple indication listener with reliable indication support enabled.</p>
<div style="border: 1px dashed #3c78b5; font-size: 14px; font-family: Courier; margin: 10px; line-height: 17px;">
<div style="background-color: #f0f0f0; padding: 10px;">
Index: configuration.html
===================================================================
RCS file: /cvsroot/sblim/jsr48-client/src/org/sblim/cimclient/doc-files/configuration.html,v
retrieving revision 1.5.2.5
retrieving revision 1.5.2.6
diff -u -d -r1.5.2.5 -r1.5.2.6
--- configuration.html 22 Apr 2010 14:39:53 -0000 1.5.2.5
+++ configuration.html 20 Aug 2012 18:44:47 -0000 1.5.2.6
@@ -2,7 +2,7 @@
<html><head>
<!--
*
- * (C) Copyright IBM Corp. 2006, 2010
+ * (C) Copyright IBM Corp. 2006, 2012
*
* THIS FILE IS PROVIDED UNDER THE TERMS OF THE ECLIPSE PUBLIC LICENSE
* ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS FILE
@@ -20,6 +20,7 @@
* 2799260 2009-06-01 raman_arora Fix left over @author tag from Java5 upgrade
* 2972697 2010-03-18 blaschke-oss Fix spelling errors in HTML files
* 2990370 2010-04-22 blaschke-oss Development/unittest HTML out of date
+ * 3536398 2012-08-20 hellerda Update HTML to reflect secure indication support
-->
</head>
<body style="background-color: white;">
@@ -92,6 +93,17 @@
setProperty()</code></a>. Note that most properties will have no effect if set after the
<a href="../../../../javax/wbem/client/WBEMClient.html#initialize(javax.cim.CIMObjectPath,%20javax.security.auth.Subject,%20java.util.Locale[])">
<code>initialize()</code></a> method was called.</p>
+<h3>Listener Settings</h3>
+<p>It is possible to override the global configuration for an individual <a href="../../../../javax/wbem/listener/WBEMListener.html"><code>
+WBEMListener</code></a> instance. These settings are shared between all threads using that listener instance. In order to do this cast the
+<code>WBEMListener</code> to <a href="../WBEMListenerSBLIM.html"><code>
+WBEMListenerSBLIM</code></a> and call <a href="../WBEMListenerSBLIM.html#setProperty(java.lang.String,%20java.lang.String)"><code>
+setProperty()</code></a>. Note that most properties will have no effect if set after the
+<a href="../../../../javax/wbem/listener/WBEMListener.html#addListener(javax.wbem.listener.IndicationListener,%20int,%20java.lang.String)">
+<code>addListener()</code></a> method was called. It is also possible to set a listener's properties by creating a new <code>java.util.Properties</code>
+object and passing it to the <a href="../WBEMListenerSBLIM.html"><code>WBEMListenerSBLIM</code></a> variant of
+ <a href="../WBEMListenerSBLIM.html#addListener(org.sblim.cimclient.IndicationListenerSBLIM,%20int,%20java.lang.String,%20java.lang.String,%20java.util.Properties)">
+<code>addListener()</code></a> that accepts properties.</p>
<h3>Local Settings</h3>
<p>Imagine you've multiple threads using the same client instance concurrently and you want to reconfigure the instance in one thread, but keep the other threads
unaffected. This is what the local settings do. They override the client and global settings, but are recognized by the current thread only. You can set
@@ -103,10 +115,10 @@
<p>The client has four possible layers for any configuration property. They override each other in the following order:</p>
<ol>
<li>local setting</li>
-<li>client setting</li>
+<li>client or listener setting</li>
<li>global setting</li>
<li>default value</li>
</ol>
-<p>The global settings can be initialized either from a configuration file or via method calls, client and local settings via method calls only. The default values
+<p>The global settings can be initialized either from a configuration file or via method calls. Client, listener and local settings are initialized via method calls only. The default values
are compile time constants and not subject to change.</p>
</body></html>
Index: secure.html
===================================================================
RCS file: /cvsroot/sblim/jsr48-client/src/org/sblim/cimclient/doc-files/secure.html,v
retrieving revision 1.3.2.4
retrieving revision 1.3.2.5
diff -u -d -r1.3.2.4 -r1.3.2.5
--- secure.html 22 Apr 2010 14:39:53 -0000 1.3.2.4
+++ secure.html 20 Aug 2012 18:44:47 -0000 1.3.2.5
@@ -2,7 +2,7 @@
<html><head>
<!--
*
- * (C) Copyright IBM Corp. 2006, 2010
+ * (C) Copyright IBM Corp. 2006, 2012
*
* THIS FILE IS PROVIDED UNDER THE TERMS OF THE ECLIPSE PUBLIC LICENSE
* ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THIS FILE
@@ -20,6 +20,7 @@
* 2799260 2009-06-01 raman_arora Fix left over @author tag from Java5 upgrade
* 2972697 2010-03-18 blaschke-oss Fix spelling errors in HTML files
* 2990370 2010-04-22 blaschke-oss Development/unittest HTML out of date
+ * 3536398 2012-08-20 hellerda Update HTML to reflect secure indication support
-->
</head>
<body style="background-color: white;">
@@ -31,7 +32,6 @@
<a href="#c2">"CIMOM authentication" configuration</a><br />
<a href="#c3">"Client authentication " configuration</a><br />
<a href="#c4">"Mutual authentication" configuration</a><br />
-<a href="#indications">Indications</a><br />
<a href="#keystore">Creation of a keystore</a><br />
<a href="#export">Export of a certificate</a><br />
<a href="#truststore">Creation of a truststore</a><br />
@@ -69,13 +69,12 @@
<p>To store the certificates two files are used. The first is the so-called keystore and contains your own certificate with all private and public key information.
The second is the so-called truststore and contains local copies of certificates from other systems you trust. These copies contain only the public
key information.</p>
-<p>How to create a keystore for Java is explained <a href="#keystore">here</a>. As of today, the SBLIM CIM Client for Java does not support truststores.</p>
+<p>How to create a keystore for Java is explained <a href="#keystore">here</a>.</p>
<p>The described mechanism would enforce every receiver to have the certificate of every trusted sender stored in its truststore. Certificate chains
were invented to get around this. In a certificate chain an organization certifies the authenticity of an entity's certificate and the receiver
just validates the authenticity of the organization's certificate. Therefore with just the certificate of the organization in the truststore the
receiver can validate all entities that have certificates based on the organization's certificate.</p>
-<p>The table below shows the possible configurations. Note that since the current SBLIM CIM Client for Java
-release does not use truststores, the CIMOM and mutual authentication configurations are not supported.
+<p>The table below shows the possible configurations.
<h3>Configurations for client connections</h3>
<table border="1" cellpadding="5">
<tr><th>Configuration</th><th>Encryption/Hashing</th><th>CIMOM authenticated</th><th>Client authenticated</th><th>Secure indication<br />listeners supported</th></tr>
@@ -111,8 +110,7 @@
<li>Keystore: No</li>
<li>Truststore: Required</li>
</ul>
-<p>When we want to check the identity of the CIMOM we need to <a href="#truststore">create a truststore</a>.
-Once this is set up, the client checks automatically the CIMOM certificate against the truststore.
+<p>In this scenario we configure the client to check the identity of the CIMOM. To do this we need to <a href="#truststore">create a truststore</a> and set the appropriate configuration properties. Once this is done the keystore will be activated and the client 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 decided to evaluate the CIMOM's X509 certificate. In order to do that we have to
import the CIMOM's certificate into our truststore. See <a href="#import">importing a certificate</a> for
@@ -130,62 +128,27 @@
<li>Keystore: Required</li>
<li>Truststore: No</li>
</ul>
-<p>In order to enable the CIMOM to check our identity we have to send it a certificate. For that we
-need to <a href="#keystore">create a keystore</a>.
-Once this is set up, the client automatically sends our certificate on request by the CIMOM.
+<p>In this scenario we configure the CIMOM to check the identity of the client. We want our client to send a certificate to the CIMOM and for that we
+need to <a href="#keystore">create a keystore</a> and set the appropriate configuration properties. Once this is done the keystore will be activated and the client will automatically send our certificate on request by the CIMOM.
Everything else is equal to the "no authorization" configuration.</p>
-<p>Note: In this scenario we decided not to evaluate the CIMOM's X509 certificate. The client is
-free to do that.</p>
-<p>Note: The CIMOM has to be enabled to validate our certificate. This can be done by either
-copying our certificate to the CIMOM's truststore, deducing our certificate from an organization certificate
-the CIMOM already trusts, copying our certificate to an organization's central certificate store (e.g. LDAP)
-the CIMOM queries, etc. See <a href="#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>
+<p>Note: In this scenario we decided not to evaluate the CIMOM's X509 certificate. The client can be configured to do that as described above.</p>
+
+<p> Note: The CIMOM has to be enabled to validate our certificate. To do this we must import into the CIMOM's truststore either a copy of our client cert or an appropriate "Certificate Authority" (CA) cert that is a <i>signer</i> for our client cert. (Really , the most general case is that the CA cert is the signer of one or more certs in a <i>trust chain</i> leading to our client cert.) The simplest case is where the CIMOM has a copy of our client cert. See <a href="#export">exporting a certificate</a> for a description on how to export a certificate from your client keystore so that you can import it into the CIMOM's truststore or other central certificate store (e.g. LDAP).</p>
+
+<p>Finally, note that most CIMOMs have three configurable settings governing authentication of the client: SFCB has ignore, accept, require. OpenPegasus has disabled, optional, required. In the case of ignore (disabled), the CIMOM will not check the client certificate. In the case of require (required) it will. The often confusing case is accept (optional); here the CIMOM will enforce the certificate check only if the client provides one. If your CIMOM is so configured you may find that it happily accepts the connection without the client sending any X509 certificate. But once the client keystore is configured and the client does send a certificate, the CIMOM will suddenly behave as if require (required) is configured, and will refuse the connection if it is unable to verify the client cert.</p>
<a id="c4" name="c4" /><h2>"Mutual authentication" configuration</h2>
<ul>
<li>Confidentiality: given</li>
<li>Integrity: given</li>
- <li>Authentication: client only</li>
+ <li>Authentication: client and CIMOM</li>
<li>Keystore: Required</li>
<li>Truststore: Required</li>
</ul>
-<p>When we want to check the identity of the CIMOM we need to <a href="#truststore">create a truststore</a>.
-Once this is set up, the client checks automatically the CIMOM certificate against the truststore.<br />
-In order to enable the CIMOM to check our identity we have to send it a certificate. For that we
-need to <a href="#keystore">create a keystore</a>.
-Once this is set up, the client sends automatically our certificate if the CIMOM requests it.
-Everything else is equal to the "no authorization" configuration.</p>
-<p>Note: In this scenario we decided to evaluate the CIMOM's X509 certificate. In order to do that we have to
-import the CIMOM's certificate into our truststore. See <a href="#import">importing a certificate</a> for
-details.</p>
-<p>Note: The CIMOM has to be enabled to validate our certificate. This can be done by either
-copying our certificate to the CIMOM's truststore, deducing our certificate from an organization certificate
-the CIMOM already trusts, copying our certificate to an organization's central certificate store (e.g. LDAP)
-the CIMOM queries, etc. See <a href="#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>
-<a id="indications" name="indications" />
-<h2>Indications</h2>
-<p>If we want to receive indications on secure connections the SSL/TLS implementation will require the
-server side of a connection (that's us in this case!) to provide a certificate. It might be used for
-authentication, but more importantly provides a public key for the session key negotiation handshake. Therefore
-receiving indications on a secure connection requires either the "client authentication" or "mutual authentication"
-configuration.</p>
-<p>To start a secure HTTP server to receive indications replace your unsecure call</p>
-<div style="border: 1px dashed #3c78b5; font-size: 14px; font-family: Courier; margin: 10px; line-height: 17px;">
-<div style="background-color: #f0f0f0; padding: 10px;">
-<pre>
-HttpServerConnection indicationServer = new HttpServerConnection(connectionHandler, port);
-</pre></div></div>
-<p>with this</p>
-<div style="border: 1px dashed #3c78b5; font-size: 14px; font-family: Courier; margin: 10px; line-height: 17px;">
-<div style="background-color: #f0f0f0; padding: 10px;">
-<pre>
-HttpServerConnection indicationServer = new HttpServerConnection(connectionHandler, port, <b>true</b>);
-</pre></div></div>
-<p>Don't forget to change "http" to "https" in the CIM_ListenerDestinationCIMXML instance when you
-subscribe.</p>
+<p>In this scenario we configure certificate validation in both directions simultaneously.</p>
+
+<p>In short, this configuration comprises the "CIMOM authentication" and "Client authentication" together.</p>
<a id="keystore" name="keystore" />
<h2>Creation of a Keystore</h2>
@@ -238,20 +201,28 @@
</pre></div></div>
Please refer to the CIMOM's documentation regarding the export of the CIMOM's certificate.
+<p>A note on terminology: we use the terms <i>keystore</i> and <i>truststore</i> to refer to the certificate stores that perform
+the roles described above. Be aware that the term <i>keystore</i> is also used in the general sense to describe any certificate store,
+regardless of role. This latter definition is used by <code>keytool</code>, and for that reason you will use the -keystore
+option to point to either your keystore or truststore.</p>
+
+<p>Also note: Your JVM might ship with a default truststore (containing common CA certificates issued by well-known certificate authorities). If so, the above command would import the cert into the existing truststore. If not, a new truststore will be created. In either case <code>keytool</code> will prompt you for a password. For an exisitng truststore the password will be the one already set for the truststore (commonly this is "changeit" for the default JVM truststore). For a new truststore, the password you provide will be the one set going forward. In either case you can optionally specify the password on the command line using the -password option.</p>
+
<a id="export" name="export" />
<h2>Export of a certificate</h2>
-<p>If you want to export the public part of your certificate to a file (e.g. for transfer to a CIMOM's truststore) you can do that
+<p>If you want to export the public part of your certificate to a file (e.g. for import into to a CIMOM's truststore) you can do that
with keytool:</p>
<div style="border: 1px dashed #3c78b5; font-size: 14px; font-family: Courier; margin: 10px; line-height: 17px;">
<div style="background-color: #f0f0f0; padding: 10px;">
<pre>
keytool -export -alias mykey -keystore keystore -rfc -file mykey.cer
</pre></div></div>
+<p>The -rfc option ensures the cert is exported in PEM format, the format commonly required by the CIMOM.</p>
Please refer to the CIMOM's documentation regarding the import of the certificate into the CIMOM's truststore.
<a id="params" name="params" />
<h2>Configuration parameters for secure connections</h2>
-<p>The configuration parametes can be found <a href="../WBEMConfigurationProperties.html">here</a>. The properties beginning with
+<p>The configuration parameters can be found <a href="../WBEMConfigurationProperties.html">here</a>. The properties beginning with
<code>KEYSTORE_</code>, <code>TRUSTSTORE_</code> or <code>SSL_</code> control the SSL configuration.</p>
<p>Note: The SSL system properties globally configure the JREs SSL support. If you want to use settings different from the global
JRE configuration, you'll have to use <code>WBEMClientSBLIM.setProperty()</code> to override the global setting. Keep in mind that
|
