version 1.2, 2005/09/02 18:32:28
|
version 1.2.12.1, 2006/03/24 18:52:12
|
|
|
<HTML> |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
<TITLE>OpenPegasus SSL Guidelines</TITLE> |
<html> |
|
<head> |
<BODY> |
<title>OpenPegasus SSL Guidelines</title> |
<H2>OpenPegasus 2.5 SSL Guidelines</H2> |
</head> |
|
<body> |
<P><B>Version: </B>1.0<BR> |
<h2>OpenPegasus 2.5.1 SSL Guidelines</h2> |
<B>Created: </B>July 20, 2005</P> |
<p><b>Version: </b>1.1<br> |
<UL> |
<b>Created: </b>July 20, 2005</p> |
<LI><A HREF="#OVERVIEW">Overview</A> |
<b>Updated: </b>March 20, 2006 |
|
<p></p> |
<LI><A HREF="#RELATED">Related Information</A> |
<ul> |
<LI><A HREF="#BUILDING">Building Pegasus with SSL</A> |
<li><a href="#OVERVIEW">Overview</a> </li> |
<LI><A HREF="#CERTS">Creating SSL Certificates</A> |
<li><a href="#RELATED">Related Information</a> </li> |
<LI><A HREF="#CONFIGURE">Configuring Pegasus for SSL</A> |
<li><a href="#BUILDING">Building Pegasus with SSL</a> </li> |
<LI><A HREF="#DESIGN">SSL Design Question List</A> |
<li><a href="#CERTS">Creating SSL Certificates</a> </li> |
<LI><A HREF="#TRUSTSTORE">Truststore Management</A> |
<li><a href="#CONFIGURE">Configuring Pegasus for SSL</a> </li> |
<LI><A HREF="#CLI">ssltrustmgr CLI</A> |
<li><a href="#DESIGN">SSL Design Question List</a> </li> |
<LI><A HREF="#CLIENT">Configuring the Pegasus CIM Client for SSL</A> |
<li><a href="#TRUSTSTORE">Truststore Management</a> </li> |
<LI><A HREF="#AUTH">SSL Authorization</A> |
<li><a href="#CLI">ssltrustmgr CLI</a> </li> |
<LI><A HREF="#RESOURCES">Resources</A> |
<li><a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a> </li> |
</UL> |
<li><a href="#AUTH">SSL Authorization</a> </li> |
|
<li><a href="#EXT">Critical Extension Handling</a> </li> |
|
<li><a href="#RESOURCES">Resources</a> |
<H3><A NAME="OVERVIEW">Overview</A></H3> |
</li> |
|
</ul> |
<P> |
<h3><a name="OVERVIEW">Overview</a></h3> |
The following document serves as a guide on how to build and configure Pegasus for SSL support. It also discusses how to utilize a certificate-based |
<p> |
infrastructure and configure the Pegasus CIM client. |
The following document serves as a guide on how to build and configure |
<P> |
Pegasus for SSL support. It also discusses how to utilize a |
This guide requires a basic understanding of SSL, OpenSSL, and basic authentication. This guide is intended to help developers |
certificate-based |
and administrators make the right decisions about how to use SSL for their particular application. |
infrastructure and configure the Pegasus CIM client. </p> |
It is not intended to be a primary source of education on SSL. If you are not familiar with these technologies, |
<p>This guide requires a basic understanding of SSL, OpenSSL, and basic |
consult the sources in the <A HREF="#RESOURCES">Resources</A> section at the bottom. |
authentication. This guide is intended to help developers and |
<P> |
administrators make the right decisions about how to use SSL for their |
|
particular application. It is not intended to be a primary source of |
<P>Note: |
education on SSL. If you are not familiar with these technologies, |
In this document, the term "trust" refers only to authentication. It does not imply full trust in the traditional sense, because |
consult the sources in the <a href="#RESOURCES">Resources</a> section |
it does not take into account authorization checks. It remains the responsibility of providers and clients to perform authorization, |
at the bottom. |
and therefore establish real trust. Likewise, the term "Trust Store" can be misleading since the "store" is only a source of |
</p> |
authentication credentials. Please bear this in mind when documenting recommended deployments or building clients or providers. |
<p></p> |
</P> |
<p>Note: In this document, the term "trust" refers only to |
|
authentication. It does not imply full trust in the traditional sense, |
<H3><A NAME="RELATED">Related Information</A></H3> |
because it does not take into account authorization checks. It remains |
A significant portion of the information in this document is taken from various PEP's. |
the responsibility of providers and clients to perform authorization, |
This document attempts to bring all of this information |
and therefore establish real trust. Likewise, the term "Trust Store" |
|
can be misleading since the "store" is only a source of authentication |
|
credentials. Please bear this in mind when documenting recommended |
|
deployments or building clients or providers. |
|
</p> |
|
<h3><a name="RELATED">Related Information</a></h3> |
|
A significant portion of the information in this document is taken from |
|
various PEP's. This document attempts to bring all of this information |
together in a cohesive and simplified format. | together in a cohesive and simplified format. |
<P> |
<p></p> |
<UL> |
<ul> |
<LI>PEP#035 - Add support for /dev/random in SSLContext</LI> |
<li>PEP#035 - Add support for /dev/random in SSLContext</li> |
<LI>PEP#060 - SSL support in CIM/XML indication delivery</LI> |
<li>PEP#060 - SSL support in CIM/XML indication delivery</li> |
<LI>PEP#074 - SSLContext and Certificate verification interface enhancement</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> |
enhancement</li> |
<LI>PEP#165 - SSL Client Verification</LI> |
<li>PEP#155 - Support for Client SSL Certificate Verification in CIM |
<LI>PEP#187 - SSL Certificate Management Enhancements</LI> |
Server for CIMExport requests</li> |
<LI>PEP#200 - Recommended OpenPegasus 2.5 Build and Configuration Options for Selected Platforms</LI> |
<li>PEP#165 - SSL Client Verification</li> |
</UL> |
<li>PEP#187 - SSL Certificate Management Enhancements</li> |
</P> |
<li>PEP#200 - Recommended OpenPegasus 2.5 Build and Configuration |
|
Options for Selected Platforms</li> |
<H3><A NAME="BUILDING">Building Pegasus with SSL</A></H3> |
</ul> |
|
<p></p> |
<P> To build Pegasus with HTTPS support, you will need to build against the <A HREF="http://www.openssl.org">OpenSSL |
<h3><a name="BUILDING">Building Pegasus with SSL</a></h3> |
package</A>. The SSL support outlined here has been tested against recent releases of the major verions 0.9.6X and 0.9.7X (most notably, 0.9.7d). |
<p> To build Pegasus with HTTPS support, you will need to build against |
It has not been tested against major version 0.9.8, which came out in July 2005. Some tests have found that versions of 0.9.6X prior to 0.9.6c |
the <a href="http://www.openssl.org">OpenSSL package</a>. <font |
do not contain the certificate revocation list (CRL) support that the OpenPegasus 2.5 utilizes. |
style="color: rgb(0, 0, 0);" color="MAGENTA">The SSL support outlined |
Because this is an open source project, the SSL support has been tested with many versions of OpenSSL, |
here has been tested against recent releases of the major versions |
but we cannot guarantee it has been tested with every version on every platform. |
0.9.7X and 0.9.8X (most notably, 0.9.7d). Because some versions of |
A list of recent OpenSSL releases, and important-to-review security advisories and fixes, can |
0.9.6X do not contain full support for the security functions that |
be found on the <A HREF="http://www.openssl.org/news">OpenSSL News page</A>. |
Pegasus utilizes (for example, certificate-based authentication is not |
</P> |
fully supported by some versions of 0.9.6X), Pegasus does not |
<P> |
officially support major version 0.9.6. |
After grabbing the OpenSSL source tarball, you need to set the following environment variables before building Pegasus: |
See Bugzilla 4048 for more information. </font> |
<UL> |
Because this is an open source project, the SSL support has been tested |
<LI>PEGASUS_HAS_SSL=1</LI> |
with many versions of OpenSSL, but we cannot guarantee it has been |
<LI>OPENSSL_HOME=<location of the SDK package> This directory must contain |
tested with every version on every platform. A list of recent OpenSSL |
the OpenSSL include directory, $(OPENSSL_HOME)/include, and the OpenSSL library |
releases, and important-to-review security advisories and fixes, can |
directory, $(OPENSSL_HOME)/lib.</LI> |
be found on the <a href="http://www.openssl.org/news">OpenSSL News page</a>. |
<LI>OPENSSL_BIN=<location of the binary package> This only needs to be |
</p> |
set if the OpenSSL binaries are not in $(OPENSSL_HOME)/bin.</LI> |
<p> |
</UL> |
After grabbing the OpenSSL source tarball, you need to set the |
|
following environment variables before building Pegasus: |
Note that Pegasus supports SSLv3 and TLSv1 by default. It does NOT support SSLv2. |
</p> |
To turn on SSLv2 support, enable the additional environment variable: |
<ul> |
<UL> |
<li>PEGASUS_HAS_SSL=1</li> |
<LI> PEGASUS_ENABLE_SSLV2=1 </LI> |
<li>OPENSSL_HOME=<location of the SDK package> This directory |
</UL> |
must contain the OpenSSL include directory, $(OPENSSL_HOME)/include, |
<P> |
and the OpenSSL library directory, $(OPENSSL_HOME)/lib.</li> |
It is not recommended to enable this protocol, as there have been many security weaknesses associated with it. Unless you are dealing |
<li>OPENSSL_BIN=<location of the binary package> This only |
with very outdated clients, you probably do not need to enable it. |
needs to be set if the OpenSSL binaries are not in $(OPENSSL_HOME)/bin.</li> |
</P> |
</ul> |
<P> |
Note that Pegasus supports SSLv3 and TLSv1 by default. It does NOT |
After setting these variables, proceed as normal with the build instructions in the readme file. |
support SSLv2. To turn on SSLv2 support, enable the additional |
</P> |
environment variable: |
|
<ul> |
<H3><A NAME="CERTS">Creating SSL Certificates</A></H3> |
<li> PEGASUS_ENABLE_SSLV2=1 </li> |
|
</ul> |
|
<p> |
|
It is not recommended to enable this protocol, as there have been many |
|
security weaknesses associated with it. Unless you are dealing |
|
with very outdated clients, you probably do not need to enable it. </p> |
|
<p> |
|
After setting these variables, proceed as normal with the build |
|
instructions in the readme file. |
|
</p> |
|
<h3><a name="CERTS">Creating SSL Certificates</a></h3> |
There are two options for creating the CIMOM's certificate: | There are two options for creating the CIMOM's certificate: |
<UL> |
<ul> |
<LI>Self-signed certificate</LI> |
<li>Self-signed certificate</li> |
<LI>Certificate issued by a third-party certificate authority</LI> |
<li>Certificate issued by a third-party certificate authority</li> |
</UL> |
</ul> |
<P> |
<p> |
To generate a self-signed certificate, you must create a private key, a certificate signing request (CSR), and finally the public x509 certificate. |
To generate a self-signed certificate, you must create a private key, a |
You also need an SSL configuration file that defines the parameters of the Distinguished Name (DN). You can use the one that comes with Pegasus, |
certificate signing request (CSR), and finally the public x509 |
ssl.cnf in the root directory, or generate your own. For a self-signed certificate, the subject |
certificate. |
is the same as the issuer. Execute the following commands to create a self-signed certificate. |
You also need an SSL configuration file that defines the parameters of |
The PEGASUS_ROOT and PEGASUS_HOME have to be set to your respective installation and source directory. You will also need an OpenSSL configuration |
the Distinguished Name (DN). You can use the one that comes with |
file. There is a sample configuration file that comes with the OpenSSL package. |
Pegasus, ssl.cnf in the root directory, or generate your own. For a |
|
self-signed certificate, the subject |
<P> |
is the same as the issuer. Execute the following commands to create a |
<UL> |
self-signed certificate. The PEGASUS_ROOT and PEGASUS_HOME have to be |
<LI>To generate a private key, execute the following:<BR> |
set to your respective installation and source directory. You will also |
<FONT FACE="courier" color="009900">openssl genrsa -out myserver.key 1024</FONT><BR> |
need an OpenSSL configuration |
Set the "sslKeyFilePath" configuration property to point to this key file. |
file. There is a sample configuration file that comes with the OpenSSL |
</LI> |
package. </p> |
<LI>To generate a certificate signing request, execute the following:<BR> |
<p></p> |
<FONT FACE="courier" color="009900">openssl req -config openssl.cnf -new -key myserver.key -out myserver.csr</font> |
<ul> |
</LI> |
<li>To generate a private key, execute the following:<br> |
<LI> At this point, the certificate sigining request can be sent out to a third-party certificate authority for signing, |
<font color="#009900" face="courier">openssl genrsa -out |
or a self-signed certificate can be generated. To generate a self-signed certificate, execute the following:<BR> |
myserver.key 1024</font><br> |
<FONT FACE="courier" color="009900">openssl x509 -in myserver.csr -out myserver.cert -req -signkey myserver.key -days 365</FONT><BR> |
Set the "sslKeyFilePath" configuration property to point to this key |
Set the "sslCertificateFilePath" configuration property to point to this certificate file. The above CSR file can be discarded |
file. </li> |
after the certificate is created. |
<li>To generate a certificate signing request, execute the following:<br> |
</LI> |
<font color="#009900" face="courier">openssl req -config |
</UL> |
openssl.cnf -new -key myserver.key -out myserver.csr</font> |
|
</li> |
<P> |
<li> At this point, the certificate signing request can be sent out |
After creating the keypair, make sure you protect the information sufficiently by changing permissions on the files and/or directories. |
to a third-party certificate authority for signing, or a self-signed |
|
certificate can be generated. To generate a self-signed certificate, |
|
execute the following:<br> |
|
<font color="#009900" face="courier">openssl x509 -in myserver.csr |
|
-out myserver.cert -req -signkey myserver.key -days 365</font><br> |
|
Set the "sslCertificateFilePath" configuration property to point to |
|
this certificate file. The above CSR file can be discarded after the |
|
certificate is created. |
|
</li> |
|
</ul> |
|
<p> |
|
After creating the keypair, make sure you protect the information |
|
sufficiently by changing permissions on the files and/or directories. |
The following table shows the recommended privileges: | The following table shows the recommended privileges: |
<P> |
</p> |
|
<p> |
<TABLE border="1" cellspacing="1" width="30%"> |
<table border="1" cellspacing="1" width="30%"> |
<TBODY> |
<tbody> |
<TR><TH><B>SSL file</B></TH><TH><B>Pegasus Config property</B></TH><TH><B>Permissions</B></TH></TR> |
<tr> |
<TR><TD>Private key</td><TD>sslKeyFilePath</TD><TD>rwx------</TD></TR> |
<th><b>SSL file</b></th> |
<TR><TD>Public certificate</td><TD>sslCertificateFilePath</TD> <TD>rwxr-xr-x</TD></TR> |
<th><b>Pegasus Config property</b></th> |
<TR><TD>Truststore</td><TD>sslTrustStore, exportSSLTruststore</TD> <TD>rwxr-xr-x</TD></TR> |
<th><b>Permissions</b></th> |
<TR><TD>CRL store </td><TD>crlStore</TD> <TD>rwxr-xr-x</TD></TR> |
</tr> |
</TBODY> |
<tr> |
</TABLE> |
<td>Private key</td> |
<P> |
<td>sslKeyFilePath</td> |
The administrator is responsible for ensuring that the above file permissions are set correctly. |
<td>rwx------</td> |
The administrator should also ensure that all containing directories all the way up to the base directory are not world-writeable. Pegasus only checks the following conditions when starting up: |
</tr> |
<UL> |
<tr> |
<LI>The sslKeyFilePath and the sslCertificateFilePath are readable by the CIMOM.</LI> |
<td>Public certificate</td> |
<LI>The sslTrustStore, exportSSLTrustStore, and crlStore are readable by the CIMOM if they are a single file.</LI> |
<td>sslCertificateFilePath</td> |
<LI>The sslTrustStore, exportSSLTrustStore, and crlStore are readable and writable by the CIMOM if they are a directory.</LI> |
<td>rwxr-xr-x</td> |
</UL> |
</tr> |
<P> |
<tr> |
These same file permissions should be used for protecting a client's private key, public key, truststore, and crl store as well. |
<td>Truststore</td> |
<p> |
<td>sslTrustStore, exportSSLTruststore</td> |
For more information on generating keys and certificates, consult the <A HRef="http://www.openssl.org/docs/HOWTO/">OpenSSL |
<td>rwxr-xr-x</td> |
HOW-TO documentation</A>. </p> |
</tr> |
<H3><A NAME="CONFIGURE">Configuring Pegasus for SSL</A></H3> |
<tr> |
|
<td>CRL store </td> |
There are many environment variable settings associated with SSL. Here is a brief discussion of the subtleties of these options and how they work together to |
<td>crlStore</td> |
create a more secure environment. More information on the default and recommended settings can be found in |
<td>rwxr-xr-x</td> |
PEP#200 Recommended OpenPegasus 2.5 Build and Configuration Options for Selected Platforms. Additionally, the section on |
</tr> |
<A HREF="#DESIGN">Design Question List</A> should help determine what these settings should be for a given application. |
</tbody> |
|
</table> |
<P> |
</p> |
<B>enableHttpsConnection</b><BR> |
<p>The administrator is responsible for ensuring that the above file |
|
permissions are set correctly. The administrator should also ensure |
|
that all containing directories all the way up to the base directory |
|
are not world-writable. Pegasus only checks the following conditions |
|
when starting up: |
|
</p> |
|
<ul> |
|
<li>The sslKeyFilePath and the sslCertificateFilePath are readable by |
|
the CIMOM.</li> |
|
<li>The sslTrustStore, exportSSLTrustStore, and crlStore are readable |
|
by the CIMOM if they are a single file.</li> |
|
<li>The sslTrustStore, exportSSLTrustStore, and crlStore are readable |
|
and writable by the CIMOM if they are a directory.</li> |
|
</ul> |
|
<p> |
|
These same file permissions should be used for protecting a client's |
|
private key, public key, truststore, and crl store as well. |
|
</p> |
|
<p> For more information on generating keys and certificates, consult |
|
the <a href="http://www.openssl.org/docs/HOWTO/">OpenSSL HOW-TO |
|
documentation</a>. </p> |
|
<h3><a name="CONFIGURE">Configuring Pegasus for SSL</a></h3> |
|
There are many environment variable settings associated with SSL. Here |
|
is a brief discussion of the subtleties of these options and how they |
|
work together to |
|
create a more secure environment. More information on the default and |
|
recommended settings can be found in PEP#200 Recommended OpenPegasus |
|
2.5 Build and Configuration Options for Selected Platforms. |
|
Additionally, the section on <a href="#DESIGN">Design Question List</a> |
|
should help determine what these settings should be for a given |
|
application. |
|
<p><b>enableHttpsConnection</b><br> |
This is disabled by default on most platforms. It is recommended that | This is disabled by default on most platforms. It is recommended that |
all remote communication be done over the HTTPS port. However, if you are sending cleartext |
all remote communication be done over the HTTPS port. However, if you |
passwords over the wire, it is imperative that you only use the secure port. |
are sending cleartext passwords over the wire, it is imperative that |
For added security, the HTTP port can be disabled to prevent clients from connecting |
you only use the secure port. For added security, the HTTP port can be |
to it. |
disabled to prevent clients from connecting to it. The HTTPS connection |
The HTTPS connection is enabled by default only on the following platforms: |
is enabled by default only on the following platforms: |
<P> |
</p> |
<UL> |
<p></p> |
<LI>LINUX</LI> |
<ul> |
<LI>OS-400</LI> |
<li>LINUX</li> |
<LI>HP_UX (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</LI> |
<li>OS-400</li> |
<LI>VMS (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</LI> |
<li>HP_UX (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</li> |
</UL> |
<li>VMS (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</li> |
</P> |
</ul> |
|
<p></p> |
<P> |
<p> |
<B>httpsPort</B><BR> |
<b>httpsPort</b><br> |
The default setting is 5989, the official WBEM secure port. |
The default setting is 5989, the official WBEM secure port. </p> |
<P> <B>sslCertificateFilePath</B> <BR> |
<p> <b>sslCertificateFilePath</b> <br> |
This is the path to the x509 server certificate. |
This is the path to the x509 server certificate. The server certificate |
The server certificate may be a chain in which case the file should contain PEM encoded certificates beginning with the server certificate |
may be a chain in which case the file should contain PEM encoded |
and followed by each signing certificate authority (CA) including the root CA. If the server certificate is a self signed certificate, |
certificates beginning with the server certificate and followed by each |
the file only contains the self-signed certificate in PEM format. |
signing certificate authority (CA) including the root CA. If the server |
The certificate cannot be encrypted because there is currently no mechanism for decrypting the certificate using a user-supplied password. |
certificate is a self signed certificate, the file only contains the |
This property must be defined if enableHttpsConnection is true. |
self-signed certificate in PEM format. |
Any failure in finding this file will result in the cimserver failing to start. |
The certificate cannot be encrypted because there is currently no |
See <A HREF="#CERTS">Creating SSL Certificates</A> for more information. |
mechanism for decrypting the certificate using a user-supplied |
<P> |
password. This property must be defined if enableHttpsConnection is |
<B>sslKeyFilePath</B><BR> |
true. Any failure in finding this file will result in the cimserver |
This is the path to the server's private key. All keys should be at least 1024 bytes long. This property must be defined if |
failing to start. See <a href="#CERTS">Creating SSL Certificates</a> |
enableHttpsConnection is true. Any failure in finding this file will result in the cimserver failing to start. |
for more information. |
See <A HREF="#CERTS">Creating SSL Certificate</A> for more information. |
</p> |
<P> |
<p><b>sslKeyFilePath</b><br> |
<B>sslClientVerificationMode</b><BR> |
This is the path to the server's private key. All keys should be at |
This setting controls how the cimserver (i.e. the HTTPS port) is configured. |
least 1024 bytes long. This property must be defined if |
It does not control the configuration of the export connection. There are three |
enableHttpsConnection is true. Any failure in finding this file will |
possible settings: disabled, required, optional. There is no "right" setting |
result in the cimserver failing to start. See <a href="#CERTS">Creating |
for this property. The default is disabled and it is fine to |
SSL Certificate</a> for more information. |
leave the setting as disabled if you are going to use basic authentication to |
</p> |
authenticate all client requests. In many applications where a physical person |
<p><b>sslClientVerificationMode</b><br> |
is there to supply a username and password, basic authentication is sufficient. |
This setting controls how the cimserver (i.e. the HTTPS port) is |
Other |
configured. It does not control the configuration of the export |
environments may be heterogeneous, in which case it makes sense to allow both |
connection. There are three possible settings: disabled, required, |
basic authentication and SSL certificate verification. The setting of this variable |
optional. There is no "right" setting for this property. The default is |
also impacts what happens during the OpenSSL handshake: |
disabled and it is fine to leave the setting as disabled if you are |
<UL> |
going to use basic authentication to authenticate all client requests. |
<LI><B>"required"</B> -- The server requires that the client certificate be trusted in order for the handshake to continue. |
In many applications where a physical person is there to supply a |
If the client fails to send a certificate or sends an untrusted certificate, the handshake is immediately terminated.</LI> |
username and password, basic authentication is sufficient. Other |
<LI><B>"optional"</B> -- The server will request that a client certificate be sent, but will continue the handshake even if no certificate is |
environments may be heterogeneous, in which case it makes sense to |
received. If authentication is enabled, the server will seek to authenticate the client via an alternative method of authentication.</LI> |
allow both basic authentication and SSL certificate verification. The |
<LI><B>"disabled"</B> -- The server will not prompt the client for a certificate. <I>This is the default.</I></LI> |
setting of this variable also impacts what happens during the OpenSSL |
</UL> |
handshake: </p> |
Pegasus currently ties a certificate to a valid OS user. Multiple certificates may be registered to the same user. When a certificate is |
<ul> |
authenticated, Pegasus views it in the same way as if a user was authenticated via basic authentication. The providers |
<li><b>"required"</b> -- The server requires that the client |
receive the username that the certificate was mapped to. See the SSL Authorization section |
certificate be trusted in order for the handshake to continue. If the |
|
client fails to send a certificate or sends an untrusted certificate, |
|
the handshake is immediately terminated.</li> |
|
<li><b>"optional"</b> -- The server will request that a client |
|
certificate be sent, but will continue the handshake even if no |
|
certificate is received. If authentication is enabled, the server will |
|
seek to authenticate the client via an alternative method of |
|
authentication. <font style="color: rgb(0, 0, 0);" color="MAGENTA">As |
|
of 2.5.1, if a certificate is sent but it is not validated, the |
|
handshake will fail. <i>Before 2.5.1,the handshake would have |
|
continued and basic authentication would have proceeded.</i></font> </li> |
|
<li><b>"disabled"</b> -- The server will not prompt the client for a |
|
certificate. <i>This is the default.</i></li> |
|
</ul> |
|
Pegasus currently ties a certificate to a valid OS user. Multiple |
|
certificates may be registered to the same user. When a certificate is |
|
authenticated, Pegasus views it in the same way as if a user was |
|
authenticated via basic authentication. The providers |
|
receive the username that the certificate was mapped to. See the SSL |
|
Authorization section |
for more information. | for more information. |
|
<p><b>sslTrustStore</b><br> |
<P> |
This setting controls the truststore for the cimserver's HTTPS |
<B>sslTrustStore</B><BR> |
connection. It can be |
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, |
either a directory or a single root CA file. When set to a directory, it is recommended that you use the ssltrustmgr CLI |
it is recommended that you use the ssltrustmgr CLI to populate the |
to populate the truststore as there are strict naming requirements for trusted certificate files. See the <A HREF="#CLI">ssltrustmgr CLI</A> |
truststore as there are strict naming requirements for trusted |
|
certificate files. See the <a href="#CLI">ssltrustmgr CLI</a> |
section for further information. | section for further information. |
<P> |
</p> |
<B>sslTrustStoreUserName</B><BR> |
<p><b>sslTrustStoreUserName</b><br> |
This setting is only utilized if the sslTrustStore is a single CA file. It is not used if the sslTrustStore setting is a directory, |
This setting is only utilized if the sslTrustStore is a single CA file. |
but it still must be set to a valid system user. This is because the validation of the property is done independently of the sslTrustStore |
It is not used if the sslTrustStore setting is a directory, but it |
setting. This property represents the valid OS user that corresponds to the root certificate. All requests authenticated with a certificate |
still must be set to a valid system user. This is because the |
under the root CA will be associated with this user and the username will be propagated to providers. If applications desire for there to |
validation of the property is done independently of the sslTrustStore |
be a one-to-one correspondence between users and certificates, it is recommended that each certificate be registered individually using the |
setting. This property represents the valid OS user that corresponds to |
<A HREF="#CLI">ssltrustmgr CLI</A>. |
the root certificate. All requests authenticated with a certificate |
<P> <B>crlStore</B><BR> |
under the root CA will be associated with this user and the username |
This is where the CRL (Certificate Revocation List) store resides. There is |
will be propagated to providers. If applications desire for there to be |
only one CRL store for all truststores. Currently, only two truststores are |
a one-to-one correspondence between users and certificates, it is |
supported (cimserver and export) and these both share the same CRL store. It |
recommended that each certificate be registered individually using the |
is important to note that certificates are checked first against the CRL (if |
<a href="#CLI">ssltrustmgr CLI</a>. </p> |
specified) and then against the truststore. The <A Href="#CLI">ssltrustmgr CLI</A> |
<p> <b>crlStore</b><br> |
should be used for CRL management. |
This is where the CRL (Certificate Revocation List) store resides. |
<P> |
There is only one CRL store for all truststores. Currently, only two |
<B>enableSSLExportClientVerification</B><BR> |
truststores are supported (cimserver and export) and these both share |
This setting controls whether an ADDITIONAL port is used to listen for incoming indications. This port is used only as a CIM indication listener |
the same CRL store. It is important to note that certificates are |
and only supports HTTPS. The port number of the export connection is currently not configurable; the port is determined by looking |
checked first against the CRL (if specified) and then against the |
|
truststore. The <a href="#CLI">ssltrustmgr CLI</a> should be used for |
|
CRL management. </p> |
|
<p><b>enableSSLExportClientVerification</b><br> |
|
This setting controls whether an ADDITIONAL port is used to listen for |
|
incoming indications. This port is used only as a CIM indication |
|
listener |
|
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. | 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 |
The export port is primarily used as a way to authenticate client |
and do not have a username/password associated with them, traditional basic authentication cannot be sent in the export request. To work |
indication requests. Because indications are generated by providers |
around this, a truststore can be configured to authenticate incoming requests. This truststore is configured like the "required" |
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. | setting of sslClientVerificationMode. |
<P> |
</p> |
<B>exportSSLTrustStore</B><BR> |
<p><b>exportSSLTrustStore</b><br> |
This setting controls the truststore for the export connection. It may be the same as the sslTrustStore. Additionally, it can be |
This setting controls the truststore for the export connection. It may |
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> |
be the same as the sslTrustStore. Additionally, it can be |
to populate the truststore as there are strict naming requirements for trusted certificate files. |
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> |
<H4>Configuration Limitations</H4> |
to populate the truststore as there are strict naming requirements for |
|
trusted certificate files. </p> |
|
<h4>Configuration Limitations</h4> |
The following are configuration limitations: | The following are configuration limitations: |
|
<ul> |
<UL> |
<li>The x509 server certificate file cannot be encrypted. The reason |
<LI>The x509 server certificate file cannot be encrypted. The reason for this is that there is currently no mechanism in Pegasus to grab the |
for this is that there is currently no mechanism in Pegasus to grab the |
password needed to unencrypt it. Therefore, the best way to secure the file is to follow the file permissions settings specified in <A HREF="#CERTS">Creating SSL Certificates.</A></LI> |
password needed to unencrypt it. Therefore, the best way to secure the |
<LI>There is no property to specify supported cipher lists at this time. Pegasus uses the default OpenSSL cipher list. The cipher lists can be found at |
file is to follow the file permissions settings specified in <a |
<A HREF="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</A> and |
href="#CERTS">Creating SSL Certificates.</a></li> |
<A HREF="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</A></LI> |
<li>There is no property to specify supported cipher lists at this |
<LI>The verification depth cannot be specified. Pegasus uses the default OpenSSL depth of 9. This means the OpenSSL will only accept client |
time. Pegasus uses the default OpenSSL cipher list. The cipher lists |
certificate chains up to 9 levels deep.</LI> |
can be found at <a |
<LI>No hostname checking is performed to ensure that the subject field of the distinguished name (DN) matches the hostname.</LI> |
href="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</a> |
</UL> |
and <a |
|
href="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</a></li> |
<H3><A NAME="DESIGN">SSL Design Question List</A></H3> |
<li>The verification depth cannot be specified. Pegasus uses the |
|
default OpenSSL depth of 9. This means the OpenSSL will only accept |
<P>The following questions may be helpful in determining how to configure Pegasus CIM Server.</P> |
client certificate chains up to 9 levels deep.</li> |
|
<li>No hostname checking is performed to ensure that the subject |
<B>Should I enable the HTTPS port?</B><BR> |
field of the distinguished name (DN) matches the hostname.</li> |
Yes, especially if you are sending passwords with requests. The HTTP port can be disabled for additional security if desired. |
</ul> |
<BR> |
<h3><a name="DESIGN">SSL Design Question List</a></h3> |
<B>Should I enable the export port?</B><BR> |
<p>The following questions may be helpful in determining how to |
Currently, the export connection provides the only way to authenticate incoming CIM indication requests. |
configure Pegasus CIM Server.</p> |
Because basic authentication cannot be used with these requests, the export connection should be enabled if |
<b>Should I enable the HTTPS port?</b><br> |
there is a concern over rogue client export requests. Otherwise, the export requests can still be sent over |
Yes, especially if you are sending passwords with requests. The HTTP |
HTTPS using the standard port; the information will be encrypted but the client's identity will not be validated. |
port can be disabled for additional security if desired. |
<BR> |
<br> |
<B>Should I configure the CIMOM to use a truststore?</B><BR> |
<b>Should I enable the export port?</b><br> |
This depends on the infrastructure of the application. If all clients are using basic authentication over the secure port |
Currently, the export connection provides the only way to authenticate |
(and the passwords are secured), then a truststore may not be needed. If an application does not want to store user/pw information, |
incoming CIM indication requests. Because basic authentication cannot |
then it is a good idea to use a certificate-based infrastructure. If a CIMOM certificate is compromised, the cimserver and the providers |
be used with these requests, the export connection should be enabled if |
of the system are compromised. The severity of this scenario is dependent on the resources the providers have access to. |
there is a concern over rogue client export requests. Otherwise, the |
If an OS password is compromised, the entire system may be compromised. |
export requests can still be sent over HTTPS using the standard port; |
If using peer verification, it is important to ensure that 1) the cimserver is properly configured to use a truststore, |
the information will be encrypted but the client's identity will not be |
2) the truststore is loaded properly and protected, and 3) authorization checks are performed after a certificate is verified. |
validated. |
These same conditions also apply to a client that is verifying a server.<BR> |
<br> |
|
<b>Should I configure the CIMOM to use a truststore?</b><br> |
<B>Should I use a self-signed certificate or one issued by a third-party certificate authority?</B><BR> |
This depends on the infrastructure of the application. If all clients |
Generally, scalability will determine whether it's appropriate to use a self-signed certificate or one issued by Verisign |
are using basic authentication over the secure port |
|
(and the passwords are secured), then a truststore may not be needed. |
|
If an application does not want to store user/pw information, |
|
then it is a good idea to use a certificate-based infrastructure. If a |
|
CIMOM certificate is compromised, the cimserver and the providers |
|
of the system are compromised. The severity of this scenario is |
|
dependent on the resources the providers have access to. If an OS |
|
password is compromised, the entire system may be compromised. |
|
If using peer verification, it is important to ensure that 1) the |
|
cimserver is properly configured to use a truststore, |
|
2) the truststore is loaded properly and protected, and 3) |
|
authorization checks are performed after a certificate is verified. |
|
These same conditions also apply to a client that is verifying a server.<br> |
|
<b>Should I use a self-signed certificate or one issued by a |
|
third-party certificate authority?</b><br> |
|
Generally, scalability will determine whether it's appropriate to use a |
|
self-signed certificate or one issued by Verisign |
or another third-party certificate authority. | or another third-party certificate authority. |
If an administrator administrates their self-signed certificates correctly, they are |
If an administrator administrates their self-signed certificates |
no less secure than one issued by a CA. What a CA buys you is scalability. An up front cost of |
correctly, they are no less secure than one issued by a CA. What a CA |
setting up a CA relationship will be offset by the convenience of having that |
buys you is scalability. An up front cost of setting up a CA |
CA "vouch" for certs it has signed, in large deployments. In small deployments |
relationship will be offset by the convenience of having that CA |
the incremental cost might never outweigh the initial CA-setup cost. <BR> |
"vouch" for certs it has signed, in large deployments. In small |
One important thing to remember is that |
deployments the incremental cost might never outweigh the initial |
you should not use the same certificate for multiple CIMOMs. If using a self-signed |
CA-setup cost. <br> |
certificate, a different one should be generated for each CIMOM, using some unique |
One important thing to remember is that you should not use the same |
piece of data to make them different. That way, if one of the certificates is |
certificate for multiple CIMOMs. If using a self-signed certificate, a |
compromised, the other ones remain secure. <BR> |
different one should be generated for each CIMOM, using some unique |
<B>Should the truststore be a single root CA file or a directory?</B><BR> |
piece of data to make them different. That way, if one of the |
If you only anticipate connections from a narrowly defined set of clients, then a single root CA certificate file should be sufficient. |
certificates is compromised, the other ones remain secure. <br> |
Alternatively, multiple trusted certificates may be stored in PEM format inside of a single CA file. |
<b>Should the truststore be a single root CA file or a directory?</b><br> |
If you anticipate getting requests from a heterogeneous set of clients, then it probably makes sense to use the directory option |
If you only anticipate connections from a narrowly defined set of |
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 to register it. |
clients, then a single root CA certificate file should be sufficient. |
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 principle of |
Alternatively, multiple trusted certificates may be stored in PEM |
least privilege, it is not a good idea to register a root CA to a privileged user if lesser privileged users will be connecting with it. |
format inside of a single CA file. |
<BR> |
If you anticipate getting requests from a heterogeneous set of clients, |
<B>How do I protect the keystore and the truststore?</B><BR> |
then it probably makes sense to use the directory option to allow |
The server's private key should always be protected; it is private for a reason. |
flexibility in the future. In the latter scenario, the same single root |
Only the system administrator should be able to see it. The public certificate |
CA file can still be used with the additional step of using ssltrustmgr |
can be viewed by anyone, however, it should be protected from alteration by system |
to register it. |
users. Similarly, any truststore or CRL file or directory should also be protected |
It's important to note that when registering a root CA, only one user |
from alteration. See <A HREF="#CERTS">Creating SSL Certificates</A> for the recommended |
can be associated with ALL certificates under that CA. Following the |
file privileges. <BR> |
principle of |
<B>When do I need to use a CRL?</B><BR> |
least privilege, it is not a good idea to register a root CA to a |
Certificate Revocation Lists are regularly issued by CA's. They contain a list |
privileged user if lesser privileged users will be connecting with it. |
of certificates that have been revoked. Any application using a CA certificate |
<br> |
in its truststore should also implement CRLs (if the CA supports them). Pegasus itself |
<b>How do I protect the keystore and the truststore?</b><br> |
does not check CRL validity dates during startup. Therefore, it is the responsibility of the administrator |
The server's private key should always be protected; it is private for |
to regularly download or acquire the CRL and import it into the CRL store using the <A Href="#CLI">ssltrustmgr CLI</A>. |
a reason. Only the system administrator should be able to see it. The |
<BR> |
public certificate can be viewed by anyone, however, it should be |
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 |
protected from alteration by system users. Similarly, any truststore or |
necessary). Because of this, the certificate deletion option available via ssltrusmgr is primarily intended for self-signed certificates. |
CRL file or directory should also be protected from alteration. See <a |
Technically, CRL's are the correct way to revoke compromised or invalid certificates. |
href="#CERTS">Creating SSL Certificates</a> for the recommended file |
<BR> |
privileges. <br> |
<B>What is the order of operations for certificate verification?</B><BR> |
<b>When do I need to use a CRL?</b><br> |
The certificate is checked against any CRLs first before going through the rest of the verification process. Verification starts with the |
Certificate Revocation Lists are regularly issued by CA's. They contain |
root certificate and continues down to the peer certificate. If verification fails at any of these points, the certificate is considered |
a list of certificates that have been revoked. Any application using a |
|
CA certificate in its truststore should also implement CRLs (if the CA |
|
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>. |
|
<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, |
|
Pegasus still accepts certificates from the issuer and uses the expired |
|
CRL as the latest. Again, it is the responsibility of the administrator |
|
to ensure the CRL is up to date. CRLs are not checked for critical |
|
extensions during CRL verification. If a CRL contains a critical |
|
extension it will be ignored. |
|
</font><br> |
|
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. |
|
Technically, CRL's are the correct way to revoke compromised or invalid |
|
certificates. |
|
<br> |
|
<b>What is the order of operations for certificate verification?</b><br> |
|
The certificate is checked against any CRLs first before going through |
|
the rest of the verification process. Verification starts with the |
|
root certificate and continues down to the peer certificate. If |
|
verification fails at any of these points, the certificate is |
|
considered |
untrusted and the verification process reports an error. | untrusted and the verification process reports an error. |
|
<h3><a name="TRUSTSTORE">Truststore Management</a></h3> |
|
There are two directions of trust in an SSL client-server handshake: |
<H3><A NAME="TRUSTSTORE">Truststore Management</A></H3> |
The client trusts the server. The server trusts the client. Pegasus |
There are two directions of trust in an SSL client-server handshake: The client trusts the server. The server trusts the client. Pegasus |
provides a way to implement one or both of these relationships. |
provides a way to implement one or both of these relationships. Ideally, an application should support both levels of trust for maximum |
Ideally, an application should support both levels of trust for maximum |
security and this is the implementation Pegasus recommends. However, in some scenarios it may make sense to only implement one of these; |
security and this is the implementation Pegasus recommends. However, in |
in that case, it is possible to override the client or the server to "trust all certificates." For example, if all clients will be using |
some scenarios it may make sense to only implement one of these; in |
basic authentication over HTTPS, then the server can be setup to "trust all client certificates." |
that case, it is possible to override the client or the server to |
<p> To tell the cimserver to require that all clients be trusted, simply set the |
"trust all certificates." For example, if all clients will be using |
sslClientVerification property to "required."<BR> |
basic authentication over HTTPS, then the server can be setup to "trust |
To tell the cimserver to trust all clients, set the sslClientVerification property |
all client certificates." |
to "disabled" or "optional". |
<p> To tell the cimserver to require that all clients be trusted, |
|
simply set the sslClientVerification<font style="color: rgb(0, 0, 0);" |
|
color="MAGENTA">Mode</font> property to "required."<br> |
<P> |
To tell the cimserver to trust all clients, set the |
The SSL verification in Pegasus is independent of any other authentication mechanism. It can still be utilized when authentication is disabled. |
sslClientVerification<font style="color: rgb(0, 0, 0);" color="MAGENTA">Mode</font> |
When authentication is enabled, the first line of defense is SSL client verification. |
property to "disabled" or "optional". |
In situations where a client is not authenticated by SSL and the setting is "optional", the server will attempt to authenticate the client |
</p> |
via another method of authentication. In this case, the authentication mechanism specified by the configuration property "httpAuthType" will be used |
<p>The SSL verification in Pegasus is independent of any other |
for remote connections and local authentication will be used for local connections. |
authentication mechanism. It can still be utilized when authentication |
|
is disabled. |
<P> |
When authentication is enabled, the first line of defense is SSL client |
See the <A HREF="#CLIENT">Configuring the Pegasus CIM Client for SSL</A> section below on how to setup the client's truststore. |
verification. <font style="color: rgb(0, 0, 0);" color="MAGENTA"> |
|
In situations where a client is not authenticated by SSL because the |
<H3><A NAME="CLI">ssltrustmgr CLI</A></H3> |
client sent no certificate and the setting is "optional", the server |
|
will attempt to authenticate the client via another method of |
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 store. |
authentication . In this case, the authentication mechanism specified |
The CLI interfaces with a certificate control provider that runs as part of Pegasus's core. It operates on the PG_SSLCertificate and PG_SSLCertificateRevocationList |
by the configuration property "httpAuthType" will be used for remote |
|
connections and local authentication will be used for local |
|
connections. |
|
In situations where a client is not authenticated by SSL because the |
|
client certificate was invalid, the handshake will be terminated. <br> |
|
<i>Note: Before 2.5.1, in the latter case, authentication would have |
|
proceeded in the same way as if the client had sent no certificate. To |
|
enable the legacy behavior, the compile-time flag |
|
PEGASUS_OVERRIDE_SSL_CERT_VERIFICATION_RESULT should be defined.</i> |
|
</font></p> |
|
<p>See the <a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a> |
|
section below on how to setup the client's truststore. |
|
</p> |
|
<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 |
|
store. |
|
The CLI interfaces with a certificate control provider that runs as |
|
part of Pegasus's core. It operates on the PG_SSLCertificate and |
|
PG_SSLCertificateRevocationList |
classes in root/pg_internal. | classes in root/pg_internal. |
It is recommended that this CLI be used in place of manual configuration for several reasons: |
It is recommended that this CLI be used in place of manual |
<UL> |
configuration for several reasons: |
<LI>OpenSSL places strict naming restrictions on certificates and CRLs in a directory (the files are looked up via a subject hash code)</LI> |
<ul> |
<LI>Certificate instances are stored in the repository along with the corresponding username. If the certificate is not properly registered, |
<li>OpenSSL places strict naming restrictions on certificates and |
the username mapping will fail.</LI> |
CRLs in a directory (the files are looked up via a subject hash code)</li> |
<LI>The CLI allows for dynamic deletion of certificates by resetting the SSL context. Normally, you would need to stop and start |
<li>Certificate instances are stored in the repository along with the |
the cimserver to accomplish this.</LI> |
corresponding username. If the certificate is not properly registered, |
<LI>The CLI, or more correctly the provider it operates on, performs a ton of error checking you would not get by manually configuring |
the username mapping will fail.<font color="MAGENTA"> <span |
the stores. This alerts the administrator to various error conditions (e.g. the certificate expired) associated with a certificate or CRL.</LI> |
style="color: rgb(0, 0, 0);">As of 2.5.1, ssltrustmgr supports the |
</UL> |
ability to register a certificate without a username for root |
|
certificates and intermediate certificates, since these certificates |
The CIMOM must be up and running while executing ssltrustmgr. The ssltrustmgr manpage provides more information on commands and syntax. |
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> |
<H3><A NAME="CLIENT">Configuring the Pegasus CIM Client for SSL</A></H3> |
</li> |
<P> A Pegasus CIM client can be configured to use SSL by using a constructor that |
<li><font color="MAGENTA"><span style="color: rgb(0, 0, 0);">The CLI, |
takes an SSLContext. The construction of the SSLContext is really what controls |
or more correctly the provider it operates on, supports dynamic |
the behavior of the client during the SSL handshake. Without going into minute |
deletion of certificates by resetting the cimserver's SSL context.</span> |
details about what happens under the covers, here is a description of the various |
</font> Normally, you would need to stop and start the cimserver to |
SSLContext constructor parameters. The descriptions are written from a client |
accomplish this.</li> |
perspective even though the same constructors are utilized by the cimserver |
<li>The CLI, or more correctly the provider it operates on, performs |
HTTPS port and export port. |
a ton of error checking you would not get by manually configuring the |
|
stores. This alerts the administrator to various error conditions (e.g. |
<P> |
the certificate expired) associated with a certificate or CRL.</li> |
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 |
</ul> |
the server requests it. In this scenario, the client also checks the server certificate against its truststore and specifies an additional |
The CIMOM must be up and running while executing ssltrustmgr. The |
callback in addition to the default one (the user-specified callback is optional and can be set to null). |
ssltrustmgr manpage provides more information on commands and syntax. |
<UL><FONT FACE="courier"> |
<h3><a name="CLIENT">Configuring the Pegasus CIM Client for SSL</a></h3> |
client.connect( |
<p> A Pegasus CIM client can be configured to use SSL by using a |
hostname, |
constructor that takes an SSLContext. The construction of the |
port, |
SSLContext is really what controls the behavior of the client during |
<B>SSLContext(trustStore, certPath, keyPath, verifyCert, randomFile),</B> |
the SSL handshake. Without going into minute details about what happens |
username, |
under the covers, here is a description of the various SSLContext |
password); |
constructor parameters. The descriptions are written from a client |
</FONT> |
perspective even though the same constructors are utilized by the |
</UL> |
cimserver HTTPS port and export port. </p> |
</P> |
<p> Here's a code snippet that shows how to call a client constructor |
<P> |
that connects to a server over SSL and can present its own trusted |
Here's a code snippet that shows how to call a client constructor that connects to a server over SSL and does not possess its own trusted certificate. |
certificate if the server requests it. In this scenario, the client |
In this scenario, the client also checks the server certificate against its truststore. |
also checks the server certificate against its truststore and specifies |
<UL> |
an additional callback in addition to the default one (the |
<FONT FACE="courier"> |
user-specified callback is optional and can be set to null). |
client.connect( |
</p> |
hostname, |
<ul> |
port, |
<font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore, |
<B>SSLContext(trustStore, NULL, randomFile),</B> |
certPath, keyPath, verifyCert, randomFile),</b> username, password); </font> |
username |
</ul> |
password); |
<p></p> |
</FONT> |
<p> Here's a code snippet that shows how to call a client constructor |
</UL> |
that connects to a server over SSL and does not possess its own trusted |
</P> |
certificate. In this scenario, the client also checks the server |
<UL> |
certificate against its truststore. |
<LI><B>trustStore</B> -- This specifies the truststore that the client uses to verify server certificates. It can be String::EMPTY if no truststore exists. </LI> |
</p> |
|
<ul> |
<LI><B>certPath</B> -- This specifies the x509 certificate of the client that will be sent during an SSL handshake. Note that this certificate will |
<font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore, |
only be sent if the server requests it. If this option is specified, the keyPath parameter must also be specified.</LI> |
NULL, randomFile),</b> username password); </font> |
|
</ul> |
<LI><B>keyPath</B> -- This specifies the private key of the client. If this option is specified, the certPath parameter must also be specified.</LI> |
<p></p> |
|
<ul> |
<LI><B>crlPath</B> -- This specifies an optional CRL store path. The client checks the CRL list first, before attempting any further authentication, |
<li><b>trustStore</b> -- This specifies the truststore that the |
including the user-specified callback.</LI> |
client uses to verify server certificates. It can be String::EMPTY if |
|
no truststore exists. </li> |
<LI><B>verifyCert</B> -- This is a user-specified verification callback. If this is set to null, the default OpenSSL verification callback will |
<li><b>certPath</b> -- This specifies the x509 certificate of the |
be executed. You can implement this method to "trust all servers" or to perform additional authentication checks that OpenSSL does not perform |
client that will be sent during an SSL handshake. Note that this |
by default.</LI> |
certificate will only be sent if the server requests it. If this option |
|
is specified, the keyPath parameter must also be specified.</li> |
<LI><B>randomFile</B> -- A file to seed the pseudo random number generator (PRNG).</LI> |
<li><b>keyPath</b> -- This specifies the private key of the client. |
|
If this option is specified, the certPath parameter must also be |
</UL> |
specified.</li> |
|
<li><b>crlPath</b> -- This specifies an optional CRL store path. The |
<P>Here are some general guidelines on implementing peer verification for the client: |
client checks the CRL list first, before attempting any further |
<UL> |
authentication, including the user-specified callback.</li> |
<LI>The client should enable peer verification by specifying a truststore and (optionally) a user-specified callback function.</LI> |
<li><b>verifyCert</b> -- This is a user-specified verification |
<LI>The client should employ a truststore in order to properly verify the server. The truststore should contain a file or directory of |
callback. If this is set to null, the default OpenSSL verification |
trusted CA certificates. The ssltrustmgr CLI cannot be used to configure client truststores. The trusted certificate(s) should be placed |
callback will be executed. You can implement this method to "trust all |
in a protected file or directory specified by the trustStore parameter. Keep in mind that the SSL context generally has to be reloaded |
servers" or to perform additional authentication checks that OpenSSL |
to pick up any truststore changes.</LI> |
does not perform by default.</li> |
<LI>The client could also use a user-specified callback in addition to the default verification callback, if additional verifications are desired over the normal checks that OpenSSL performs. |
<li><b>randomFile</b> -- A file to seed the pseudo random number |
In most cases, the default verification callback is sufficient for checking server certificates.</LI> |
generator (PRNG).</li> |
<LI>The client should ensure that adequate entropy is attained.</LI> |
</ul> |
<LI>The client should use a CRL store if the truststore contains CA certificates that support one.</LI> |
<p>Here are some general guidelines on implementing peer verification |
<LI>The client should only use the SSLv3 and TLSv1 protocols. By default, Pegasus is not built with SSLv2 support.</LI> |
for the client: |
|
</p> |
<li>The client should terform post-connection checks. </li> |
<ul> |
|
<li>The client should enable peer verification by specifying a |
|
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 |
|
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 |
|
reloaded to pick up any truststore changes.</li> |
|
<li>The client could also use a user-specified callback in addition |
|
to the default verification callback, if additional verifications are |
|
desired over the normal checks that OpenSSL performs. In most cases, |
|
the default verification callback is sufficient for checking server |
|
certificates.</li> |
|
<li>The client should ensure that adequate entropy is attained.</li> |
|
<li>The client should use a CRL store if the truststore contains CA |
|
certificates that support one.</li> |
|
<li>The client should only use the SSLv3 and TLSv1 protocols. By |
|
default, Pegasus is not built with SSLv2 support.</li> |
|
<li>The client should perform post-connection checks. </li> |
<ul> | <ul> |
<li>Ensure a certificate was received.</li> | <li>Ensure a certificate was received.</li> |
<ul> | <ul> |
<li>WARNING: In some implementations of SSL |
<li>WARNING: In some implementations of SSL a NULL server |
a NULL server certificate is perfectly valid and authenticates against |
certificate is perfectly valid and authenticates against all trust |
all trust stores. If the client does not ensure a certificate |
stores. If the client does not ensure a certificate exists then |
exists then the client is not providing server authentication and could |
the client is not providing server authentication and could have a |
have a security bulletin class defect.</li> |
security bulletin class defect.</li> |
</ul> |
</ul> |
<li>Validate that the certificate received was issued to the |
<li>Validate that the certificate received was issued to the host |
host for which the client was attempting to connect.</li> |
for which the client was attempting to connect.</li> |
<ul> |
<ul> |
<li>Ensure that the common name (CN) in the server’s |
<li>Ensure that the common name (CN) in the server’s certificate |
certificate subject matches the host name of the server. For X509v3 |
subject matches the host name of the server. For X509v3 |
certificates, the “<span class=SpellE>SubjectAltName</span>” |
certificates, the “<span class="SpellE">SubjectAltName</span>” fields |
fields in the certificate's extended attributes are also valid host names |
in the certificate's extended attributes are also valid host names for |
for the certificate. </li> |
the certificate. </li> |
<li>WARNING: If the client does not ensure |
<li>WARNING: If the client does not ensure the host name of |
the host name of the server is the same as one of the host names explicitly |
the server is the same as one of the host names explicitly described in |
described in the server’s certificate, you have not authenticated |
the server’s certificate, you have not authenticated the server’s |
the server’s identity. Any other server which was issued |
identity. Any other server which was issued a certificate from |
a certificate from the same trusted CA can masquerade as the server |
the same trusted CA can masquerade as the server unless the client |
unless the client performs the host name check.</li> |
performs the host name check.</li> |
</ul> |
</ul> |
<li>Ensure that certificate verification methods/routines |
<li>Ensure that certificate verification methods/routines return no |
return no errors.</li> |
errors.</li> |
</ul> |
</ul> |
|
</ul> |
|
<p> |
</UL> |
Because only the above arguments can be passed into the Pegasus |
|
SSLContext, there are some limitations in the client configuration: |
<P> |
</p> |
Because only the above arguments can be passed into the Pegasus SSLContext, there are some limitations in the client configuration: |
<ul> |
<UL> |
<li>The verification depth cannot be specified. Pegasus uses the |
<LI>The verification depth cannot be specified. Pegasus uses the default OpenSSL depth of 9.</LI> |
default OpenSSL depth of 9.</li> |
<LI>The cipher list cannot be specified. Pegasus uses the default OpenSSL cipher list. The cipher lists can be found at |
<li>The cipher list cannot be specified. Pegasus uses the default |
<A HREF="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</A> and |
OpenSSL cipher list. The cipher lists can be found at <a |
<A HREF="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</A></LI> |
href="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</a> |
<LI>No hostname checking is performed to ensure that the subject field of the distinguished name (DN) matches the hostname. If desired, a user-specified callback should be configured |
and <a |
to perform this check or any additional checks relevant to the application.</LI> |
href="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</a></li> |
</UL> |
<li>No hostname checking is performed to ensure that the subject |
|
field of the distinguished name (DN) matches the hostname. If desired, |
|
a user-specified callback should be configured to perform this check or |
<H3><A NAME="AUTH">SSL Authorization</A></H3> |
any additional checks relevant to the application.</li> |
<P>The following paragraphs concern authorization of users authenticated by certificate on the cimserver's HTTPS port. |
</ul> |
<P> It is important to note that SSL certificates are verified during the initial |
<h3><a name="AUTH">SSL Authorization</a></h3> |
handshake, BEFORE any further authentication takes place. If a certificate fails, |
<p>The following paragraphs concern authorization of users |
the connection can be terminated immediately, resulting in a connection exception. |
authenticated by certificate on the cimserver's HTTPS port. |
This scenario will occur if the sslClientVerification property is set to "required" |
</p> |
and no certificate or an untrusted certificate is sent. The export connection |
<p> It is important to note that SSL certificates are verified during |
will also terminate the connection if an untrusted certificate is presented. |
the initial handshake, BEFORE any further authentication takes place. |
Once a certificate is verified, no further <I><B>authentication</B></I> is attempted. |
If a certificate fails, the connection can be terminated immediately, |
This effectively results in any basic or local authentication headers being |
resulting in a connection exception. This scenario will occur if the |
ignored. |
sslClientVerification property is set to "required" and no certificate |
<P> |
or an untrusted certificate is sent. The export connection will also |
Further <I><B>authorization</B></I> checks must be performed when validating |
terminate the connection if an untrusted certificate is presented. Once |
the user that is mapped to the certificate. First, the user that is registered to the certificate |
a certificate is verified, no further <i><b>authentication</b></i> is |
is validated as a valid system user and a valid cimuser (if the cimuser function has been configured). |
attempted. This effectively results in any basic or local |
Additionally, if Pegasus was configured to use PAM, the pam_acct_mgmt function will be called with the |
authentication headers being ignored. </p> |
user that is mapped to the certificate. This ensures that any login conditions that would have been placed |
<p> Further <i><b>authorization</b></i> checks must be performed when |
on a user authenticated via basic authentication are still applied to a user authenticated via certificate. |
validating the user that is mapped to the certificate. First, the user |
The pam_authenticate method will NOT be called. Lastly, the providers must authorize the user. They receive the |
that is registered to the certificate is validated as a valid system |
username that was mapped to the certificate in the OperationContext. |
user and a valid cimuser (if the cimuser function has been configured). |
|
<font color="magenta"><span style="color: rgb(0, 0, 0);">In the case of |
<H3><A NAME="RESOURCES">Resources</A></H3> |
a certificate chain, the username authorization starts with the leaf |
|
certificate. If it successfully finds a mapping |
<P> |
for the leaf certificate, it continues; if there is no username for the |
For OpenSSL information pick up a copy of O'Reilly's Network Security with OpenSSL or go to the OpenSSL Site:<BR> |
leaf certificate, the validation proceeds up to the root certificate. |
<A HREF="http://www.openssl.org">http://www.openssl.org</A> |
If the root certificate is reached and there is still no mapped |
|
username, the authorization fails.</span> |
<P> |
</font> Additionally, if Pegasus was configured to use PAM, the |
A really fabulous guide on certificate management and installation with OpenSSL:<BR> |
pam_acct_mgmt function will be called with the user that is mapped to |
<A HREF="http://www.gagravarr.org/writing/openssl-certs/index.shtml">http://www.gagravarr.org/writing/openssl-certs/index.shtml</A> |
the certificate. This ensures that any login conditions that would have |
|
been placed on a user authenticated via basic authentication are still |
<P> |
applied to a user authenticated via certificate. The pam_authenticate |
x509 Certificate and CRL RFC:<BR> |
method will NOT be called. Lastly, the providers must authorize the |
<A HREF="http://www.ietf.org/rfc/rfc2459.txt?number=2459">http://www.ietf.org/rfc/rfc2459.txt?number=2459</A> |
user. They receive the username that was mapped to the certificate in |
|
the OperationContext. </p> |
<P> |
<h3><a name="EXT">Critical Extension Handling</a></h3> |
SSLv3 RFC:<BR> |
<p><font color="MAGENTA"><span style="color: rgb(0, 0, 0);"> |
<A HREF="http://wp.netscape.com/eng/ssl3/">http://wp.netscape.com/eng/ssl3</A> |
The extensions defined for X.509 v3 certificates provide methods for |
|
associating additional attributes with users or public keys and for |
<P> |
managing the certification hierarchy. Each extension in a certificate |
TLSv1 RFC:<BR> |
may be designated as critical or non-critical. Pegasus relies on the |
<A HREF="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</A> |
underlying OpenSSL implementation to handle critical extensions |
|
specified in a certificate. Please refer to the OpenSSL documentation |
<P> |
for more information on currently supported extensions in OpenSSL and |
Basic Authentication RFC:<BR> |
on the behavior of OpenSSL in the case of unhandled critical extensions.</span> |
<A HREF="http://www.faqs.org/rfcs/rfc2617.html">http://www.faqs.org/rfcs/rfc2617.html</A> |
</font></p> |
|
<h3><a name="RESOURCES">Resources</a></h3> |
|
<p> |
|
For OpenSSL information pick up a copy of O'Reilly's Network Security |
|
with OpenSSL or go to the OpenSSL Site:<br> |
|
<a href="http://www.openssl.org">http://www.openssl.org</a> </p> |
|
<p>A really fabulous guide on certificate management and installation |
|
with OpenSSL:<br> |
|
<a href="http://www.gagravarr.org/writing/openssl-certs/index.shtml">http://www.gagravarr.org/writing/openssl-certs/index.shtml</a> |
|
</p> |
|
<p>x509 Certificate and CRL RFC:<br> |
|
<a href="http://www.ietf.org/rfc/rfc2459.txt?number=2459">http://www.ietf.org/rfc/rfc2459.txt?number=2459</a> |
|
</p> |
|
<p>SSLv3 RFC:<br> |
|
<a href="http://wp.netscape.com/eng/ssl3/">http://wp.netscape.com/eng/ssl3</a> |
|
</p> |
|
<p>TLSv1 RFC:<br> |
|
<a href="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</a> |
|
</p> |
|
<p>Basic Authentication RFC:<br> |
|
<a href="http://www.faqs.org/rfcs/rfc2617.html">http://www.faqs.org/rfcs/rfc2617.html</a> |
|
</p> |
<hr> | <hr> |
|
<p><i><font size="2">Copyright (c) 2005 EMC Corporation; |
<p><i><font size="2">Copyright (c) 2005 EMC Corporation; Hewlett-Packard Development |
Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open Group; |
|
VERITAS Software Corporation</font><br> |
Company, L.P.; IBM Corp.; The Open Group; VERITAS Software Corporation</font><br> |
|
|
|
<br> | <br> |
|
<font size="1">Permission is hereby granted, free of charge, to any |
<font size="1">Permission is hereby granted, free of charge, to any person |
person obtaining a copy of this software and associated |
|
documentation files (the "Software"), to deal in the Software without |
obtaining a copy of this software and associated documentation files (the |
restriction, including without limitation the rights to use, copy, |
|
modify, merge, publish, distribute, sublicense, and/or sell copies of |
"Software"), to deal in the Software without restriction, including without |
the Software, and to permit persons to whom the Software is furnished |
|
to do so, subject to the following conditions:</font><br> |
limitation the rights to use, copy, modify, merge, publish, distribute, |
|
|
|
sublicense, and/or sell copies of the Software, and to permit persons to whom |
|
|
|
the Software is furnished to do so, subject to the following conditions:</font><br> |
|
|
|
<font size="2"><br> | <font size="2"><br> |
|
|
</font> | </font> |
|
<font size="1">THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE |
<font size="1">THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL |
SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE |
|
SOFTWARE. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF |
COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED |
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE |
"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT |
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND |
|
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE |
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE |
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION |
|
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION |
AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE |
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</font></i></p> |
|
|
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF |
|
|
|
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE |
|
|
|
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</font></i></p> |
|
|
|
<hr> | <hr> |
|
</body> |
</BODY> |
</html> |
</HTML> |
|
|
|
|
|
|
|
|
|
|
|
|
|