|author||sushma.fernandes <sushma.fernandes>||2006-09-29 17:38:10 +0000|
|committer||sushma.fernandes <sushma.fernandes>||2006-09-29 17:38:10 +0000|
TITLE: PEP 259 SSL Certificate Management Command Interfaces - phase 4 DESCRIPTION: Removed export SSL connection code and config parameters exportSSLTrustStore and enableExportSSLClientVerification. Added cimcrl and cimtrust man pages. Updated SSL guidelines document.
Diffstat (limited to 'doc')
1 files changed, 30 insertions, 72 deletions
diff --git a/doc/PegasusSSLGuidelines.htm b/doc/PegasusSSLGuidelines.htm
index 03929bf..5701de3 100644
@@ -17,7 +17,7 @@
<li><a href="#CONFIGURE">Configuring Pegasus for SSL</a> </li>
<li><a href="#DESIGN">SSL Design Question List</a> </li>
<li><a href="#TRUSTSTORE">Truststore Management</a> </li>
- <li><a href="#CLI">ssltrustmgr CLI</a> </li>
+ <li><a href="#CLI">cimtrust & cimcrl CLI</a> </li>
<li><a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a> </li>
<li><a href="#AUTH">SSL Authorization</a> </li>
<li><a href="#EXT">Critical Extension Handling</a> </li>
@@ -58,8 +58,6 @@ together in a cohesive and simplified format.
<li>PEP#060 - SSL support in CIM/XML indication delivery</li>
<li>PEP#074 - SSLContext and Certificate verification interface
- <li>PEP#155 - Support for Client SSL Certificate Verification in CIM
-Server for CIMExport requests</li>
<li>PEP#165 - SSL Client Verification</li>
<li>PEP#187 - SSL Certificate Management Enhancements</li>
<li>PEP#200 - Recommended OpenPegasus 2.5 Build and Configuration
@@ -176,7 +174,7 @@ The following table shows the recommended privileges:
- <td>sslTrustStore, exportSSLTruststore</td>
@@ -196,9 +194,9 @@ when starting up:
<li>The sslKeyFilePath and the sslCertificateFilePath are readable by
- <li>The sslTrustStore, exportSSLTrustStore, and crlStore are readable
+ <li>The sslTrustStore and crlStore are readable
by the CIMOM if they are a single file.</li>
- <li>The sslTrustStore, exportSSLTrustStore, and crlStore are readable
+ <li>The sslTrustStore and crlStore are readable
and writable by the CIMOM if they are a directory.</li>
@@ -260,8 +258,7 @@ SSL Certificate</a> for more information.
This setting controls how the cimserver (i.e. the HTTPS port) is
-configured. It does not control the configuration of the export
-connection. There are three possible settings: disabled, required,
+configured. There are three possible settings: disabled, required,
optional. There is no "right" setting for this property. The default is
disabled and it is fine to leave the setting as disabled if you are
going to use basic authentication to authenticate all client requests.
@@ -298,9 +295,9 @@ for more information.
This setting controls the truststore for the cimserver's HTTPS
connection. It can be
either a directory or a single root CA file. When set to a directory,
-it is recommended that you use the ssltrustmgr CLI to populate the
+it is recommended that you use the cimtrust CLI to populate the
truststore as there are strict naming requirements for trusted
-certificate files. See the <a href="#CLI">ssltrustmgr CLI</a>
+certificate files. See the <a href="#CLI">cimtrust & cimcrl CLI</a>
section for further information.
@@ -314,37 +311,13 @@ under the root CA will be associated with this user and the username
will be propagated to providers. If applications desire for there to be
a one-to-one correspondence between users and certificates, it is
recommended that each certificate be registered individually using the
-<a href="#CLI">ssltrustmgr CLI</a>. </p>
+<a href="#CLI">cimtrust CLI</a>. </p>
This is where the CRL (Certificate Revocation List) store resides.
-There is only one CRL store for all truststores. Currently, only two
-truststores are supported (cimserver and export) and these both share
-the same CRL store. It is important to note that certificates are
+It is important to note that certificates are
checked first against the CRL (if specified) and then against the
-truststore. The <a href="#CLI">ssltrustmgr CLI</a> should be used for
+server truststore. The <a href="#CLI">cimcrl CLI</a> should be used for
CRL management. </p>
-This setting controls whether an ADDITIONAL port is used to listen for
-incoming indications. This port is used only as a CIM indication
-and only supports HTTPS. The port number of the export connection is
-currently not configurable; the port is determined by looking
-in /etc/services for the service name wbem-exp-https.
-The export port is primarily used as a way to authenticate client
-indication requests. Because indications are generated by providers
-and do not have a username/password associated with them, traditional
-basic authentication cannot be sent in the export request. To work
-around this, a truststore can be configured to authenticate incoming
-requests. This truststore is configured like the "required"
-setting of sslClientVerificationMode.
-This setting controls the truststore for the export connection. It may
-be the same as the sslTrustStore. Additionally, it can be
-either a directory or a single root CA file. When set to a directory,
-it is recommended that you use the <a href="#CLI">ssltrustmgr CLI</a>
-to populate the truststore as there are strict naming requirements for
-trusted certificate files. </p>
The following are configuration limitations:
@@ -372,15 +345,6 @@ configure Pegasus CIM Server.</p>
Yes, especially if you are sending passwords with requests. The HTTP
port can be disabled for additional security if desired.
-<b>Should I enable the export port?</b><br>
-Currently, the export connection provides the only way to authenticate
-incoming CIM indication requests. Because basic authentication cannot
-be used with these requests, the export connection should be enabled if
-there is a concern over rogue client export requests. Otherwise, the
-export requests can still be sent over HTTPS using the standard port;
-the information will be encrypted but the client's identity will not be
<b>Should I configure the CIMOM to use a truststore?</b><br>
This depends on the infrastructure of the application. If all clients
are using basic authentication over the secure port
@@ -421,7 +385,7 @@ format inside of a single CA file.
If you anticipate getting requests from a heterogeneous set of clients,
then it probably makes sense to use the directory option to allow
flexibility in the future. In the latter scenario, the same single root
-CA file can still be used with the additional step of using ssltrustmgr
+CA file can still be used with the additional step of using cimtrust
to register it.
It's important to note that when registering a root CA, only one user
can be associated with ALL certificates under that CA. Following the
@@ -445,7 +409,7 @@ supports them). Pegasus itself
does not check CRL validity dates during startup. Therefore, it is the
responsibility of the administrator
to regularly download or acquire the CRL and import it into the CRL
-store using the <a href="#CLI">ssltrustmgr CLI</a>.
+store using the <a href="#CLI">cimcrl CLI</a>.
<font style="color: rgb(0, 0, 0);" color="MAGENTA">CRLs are not checked
for expiration during the SSL callback. This means that if a CRL for a
particular issuer has expired,
@@ -458,7 +422,7 @@ extension it will be ignored.
If using self-signed certificates, however, a CRL is most likely not
needed (You can create a self-signed CRL but it is not really
necessary). Because of this, the certificate deletion option available
-via ssltrustmgr is primarily intended for self-signed certificates.
+via cimtrust is primarily intended for self-signed certificates.
Technically, CRL's are the correct way to revoke compromised or invalid
@@ -509,15 +473,15 @@ PEGASUS_OVERRIDE_SSL_CERT_VERIFICATION_RESULT should be defined.</i>
<p>See the <a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a>
section below on how to setup the client's truststore.
-<h3><a name="CLI">ssltrustmgr CLI</a></h3>
-Pegasus 2.5 comes with a new CLI, ssltrustmgr, that should be used to
-manage the cimserver's truststore, the export truststore, and the CRL
-The CLI interfaces with a certificate control provider that runs as
+<h3><a name="CLI">cimtrust & cimcrl CLI</a></h3>
+cimtrust CLI may be used to add, remove or list X509 certificates in a
+PEM format truststore. cimcrl CLI may be used to add, remove or list
+X509 Certificate Revocation Lists in a PEM format CRL store.
+The CLIs interface with a Certificate control provider that runs as
part of Pegasus's core. It operates on the PG_SSLCertificate and
-classes in root/pg_internal.
-It is recommended that this CLI be used in place of manual
+PG_SSLCertificateRevocationList classes in root/PG_Internal.
+It is recommended that the CLIs be used in place of manual
configuration for several reasons:
<li>OpenSSL places strict naming restrictions on certificates and
@@ -525,34 +489,32 @@ CRLs in a directory (the files are looked up via a subject hash code)</li>
<li>Certificate instances are stored in the repository along with the
corresponding username. If the certificate is not properly registered,
the username mapping will fail.<font color="MAGENTA"> <span
- style="color: rgb(0, 0, 0);">As of 2.5.1, ssltrustmgr supports the
+ style="color: rgb(0, 0, 0);">cimtrust CLI supports the
ability to register a certificate without a username for root
certificates and intermediate certificates, since these certificates
represent a collection of users. In this scenario, each leaf
certificate must be registered to an individual user. See the
Authorization section for more information on username validation.</span></font>
- <li><font color="MAGENTA"><span style="color: rgb(0, 0, 0);">The CLI,
-or more correctly the provider it operates on, supports dynamic
+ <li><font color="MAGENTA"><span style="color: rgb(0, 0, 0);">The CLIs,
+or more correctly the provider they operate on, supports dynamic
deletion of certificates by resetting the cimserver's SSL context.</span>
</font> Normally, you would need to stop and start the cimserver to
- <li>The CLI, or more correctly the provider it operates on, performs
+ <li>The CLIs, or more correctly the provider they operate on, performs
a ton of error checking you would not get by manually configuring the
stores. This alerts the administrator to various error conditions (e.g.
the certificate expired) associated with a certificate or CRL.</li>
-The CIMOM must be up and running while executing ssltrustmgr. The
-ssltrustmgr manpage provides more information on commands and syntax.
+The CIMOM must be up and running while executing cimtrust/cimcrl CLI. The
+cimtrust and cimcrl manpages provide more information on commands and syntax.
<h3><a name="CLIENT">Configuring the Pegasus CIM Client for SSL</a></h3>
<p> A Pegasus CIM client can be configured to use SSL by using a
constructor that takes an SSLContext. The construction of the
SSLContext is really what controls the behavior of the client during
the SSL handshake. Without going into minute details about what happens
under the covers, here is a description of the various SSLContext
-constructor parameters. The descriptions are written from a client
-perspective even though the same constructors are utilized by the
-cimserver HTTPS port and export port. </p>
+constructor parameters. </p>
<p> Here's a code snippet that shows how to call a client constructor
that connects to a server over SSL and can present its own trusted
certificate if the server requests it. In this scenario, the client
@@ -605,7 +567,7 @@ for the client:
truststore and (optionally) a user-specified callback function.</li>
<li>The client should employ a truststore in order to properly verify
the server. The truststore should contain a file or directory of
-trusted CA certificates. The ssltrustmgr CLI cannot be used to
+trusted CA certificates. The cimtrust CLI cannot be used to
configure client truststores. The trusted certificate(s) should be
placed in a protected file or directory specified by the trustStore
parameter. Keep in mind that the SSL context generally has to be
@@ -675,11 +637,7 @@ the initial handshake, BEFORE any further authentication takes place.
If a certificate fails, the connection can be terminated immediately,
resulting in a connection exception. This scenario will occur if the
sslClientVerification property is set to "required" and no certificate
-or an untrusted certificate is sent. The export connection will also
-terminate the connection if an untrusted certificate is presented. Once
-a certificate is verified, no further <i><b>authentication</b></i> is
-attempted. This effectively results in any basic or local
-authentication headers being ignored. </p>
+or an untrusted certificate is sent. </p>
<p> Further <i><b>authorization</b></i> checks must be performed when
validating the user that is mapped to the certificate. First, the user
that is registered to the certificate is validated as a valid system