Return to PegasusSSLGuidelines.htm CVS log

Up to [Pegasus] / pegasus / doc

BUG#: 5634
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.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <title>OpenPegasus SSL Guidelines</title>
</head>
<body>
<h2>OpenPegasus 2.5.1 SSL Guidelines</h2>
<p><b>Version:&nbsp;</b>1.1<br>
<b>Created:&nbsp;</b>July 20, 2005</p>
<b>Updated:&nbsp;</b>March 20, 2006
<p></p>
<ul>
  <li><a href="#OVERVIEW">Overview</a> </li>
  <li><a href="#RELATED">Related Information</a> </li>
  <li><a href="#BUILDING">Building Pegasus with SSL</a> </li>
  <li><a href="#CERTS">Creating SSL Certificates</a> </li>
  <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">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>
  <li><a href="#RESOURCES">Resources</a>
  </li>
</ul>
<h3><a name="OVERVIEW">Overview</a></h3>
<p>
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
infrastructure and configure the Pegasus CIM client. </p>
<p>This guide requires a basic understanding of SSL, OpenSSL, and basic
authentication. This guide is intended to help developers and
administrators make the right decisions about how to use SSL for their
particular application. It is not intended to be a primary source of
education on SSL. If you are not familiar with these technologies,
consult the sources in the <a href="#RESOURCES">Resources</a> section
at the bottom.
</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,
because it does not take into account authorization checks. It remains
the responsibility of providers and clients to perform authorization,
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.
<p></p>
<ul>
  <li>PEP#035 - Add support for /dev/random in SSLContext</li>
  <li>PEP#060 - SSL support in CIM/XML indication delivery</li>
  <li>PEP#074 - SSLContext and Certificate verification interface
enhancement</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
Options for Selected Platforms</li>
</ul>
<p></p>
<h3><a name="BUILDING">Building Pegasus with SSL</a></h3>
<p> To build Pegasus with HTTPS support, you will need to build against
the <a href="http://www.openssl.org">OpenSSL package</a>. <font
 style="color: rgb(0, 0, 0);" color="MAGENTA">The SSL support outlined
here has been tested against recent releases of the major versions
0.9.7X and 0.9.8X (most notably, 0.9.7d). Because some versions of
0.9.6X do not contain full support for the security functions that
Pegasus utilizes (for example, certificate-based authentication is not
fully supported by some versions of 0.9.6X), Pegasus does not
officially support major version 0.9.6.
See Bugzilla 4048 for more information. </font>
Because this is an open source project, the SSL support has been tested
with many versions of OpenSSL, but we cannot guarantee it has been
tested with every version on every platform. A list of recent OpenSSL
releases, and important-to-review security advisories and fixes, can
be found on the <a href="http://www.openssl.org/news">OpenSSL News page</a>.
</p>
<p>
After grabbing the OpenSSL source tarball, you need to set the
following environment variables before building Pegasus:
</p>
<ul>
  <li>PEGASUS_HAS_SSL=1</li>
  <li>OPENSSL_HOME=&lt;location of the SDK package&gt; This directory
must contain the OpenSSL include directory, $(OPENSSL_HOME)/include,
and the OpenSSL library directory, $(OPENSSL_HOME)/lib.</li>
  <li>OPENSSL_BIN=&lt;location of the binary package&gt; This only
needs to be set if the OpenSSL binaries are not in $(OPENSSL_HOME)/bin.</li>
</ul>
Note that Pegasus supports SSLv3 and TLSv1 by default. It does NOT
support SSLv2. To turn on SSLv2 support, enable the additional
environment variable:
<ul>
  <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:
<ul>
  <li>Self-signed certificate</li>
  <li>Certificate issued by a third-party certificate authority</li>
</ul>
<p>
To generate a self-signed certificate, you must create a private key, a
certificate signing request (CSR), and finally the public x509
certificate.
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, ssl.cnf in the root directory, or generate your own. For a
self-signed certificate, the subject
is the same as the issuer. Execute the following commands to create a
self-signed certificate. The PEGASUS_ROOT and PEGASUS_HOME have to be
set to your respective installation and source directory. You will also
need an OpenSSL configuration
file. There is a sample configuration file that comes with the OpenSSL
package. </p>
<p></p>
<ul>
  <li>To generate a private key, execute the following:<br>
    <font color="#009900" face="courier">openssl genrsa -out
myserver.key 1024</font><br>
Set the "sslKeyFilePath" configuration property to point to this key
file. </li>
  <li>To generate a certificate signing request, execute the following:<br>
    <font color="#009900" face="courier">openssl req -config
openssl.cnf -new -key myserver.key -out myserver.csr</font>
  </li>
  <li> At this point, the certificate signing request can be sent out
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:
</p>
<p>
<table border="1" cellspacing="1" width="30%">
  <tbody>
    <tr>
      <th><b>SSL file</b></th>
      <th><b>Pegasus Config property</b></th>
      <th><b>Permissions</b></th>
    </tr>
    <tr>
      <td>Private key</td>
      <td>sslKeyFilePath</td>
      <td>rwx------</td>
    </tr>
    <tr>
      <td>Public certificate</td>
      <td>sslCertificateFilePath</td>
      <td>rwxr-xr-x</td>
    </tr>
    <tr>
      <td>Truststore</td>
      <td>sslTrustStore</td>
      <td>rwxr-xr-x</td>
    </tr>
    <tr>
      <td>CRL store </td>
      <td>crlStore</td>
      <td>rwxr-xr-x</td>
    </tr>
  </tbody>
</table>
</p>
<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 and crlStore are readable
by the CIMOM if they are a single file.</li>
  <li>The sslTrustStore 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
all remote communication be done over the HTTPS port. However, if you
are sending cleartext passwords over the wire, it is imperative that
you only use the secure port. For added security, the HTTP port can be
disabled to prevent clients from connecting to it. The HTTPS connection
is enabled by default only on the following platforms:
</p>
<p></p>
<ul>
  <li>LINUX</li>
  <li>OS-400</li>
  <li>HP_UX (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</li>
  <li>VMS (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</li>
</ul>
<p></p>
<p>
<b>httpsPort</b><br>
The default setting is 5989, the official WBEM secure port. </p>
<p> <b>sslCertificateFilePath</b> <br>
This is the path to the x509 server certificate. The server certificate
may be a chain in which case the file should contain PEM encoded
certificates beginning with the server certificate and followed by each
signing certificate authority (CA) including the root CA. If the server
certificate is a self signed certificate, the file only contains the
self-signed certificate in PEM format.
The certificate cannot be encrypted because there is currently no
mechanism for decrypting the certificate using a user-supplied
password. This property must be defined if enableHttpsConnection is
true. Any failure in finding this file will result in the cimserver
failing to start. See <a href="#CERTS">Creating SSL Certificates</a>
for more information.
</p>
<p><b>sslKeyFilePath</b><br>
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
enableHttpsConnection is true. Any failure in finding this file will
result in the cimserver failing to start. See <a href="#CERTS">Creating
SSL Certificate</a> for more information.
</p>
<p><b>sslClientVerificationMode</b><br>
This setting controls how the cimserver (i.e. the HTTPS port) is
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.
In many applications where a physical person is there to supply a
username and password, basic authentication is sufficient. Other
environments may be heterogeneous, in which case it makes sense to
allow both basic authentication and SSL certificate verification. The
setting of this variable also impacts what happens during the OpenSSL
handshake: </p>
<ul>
  <li><b>"required"</b> -- The server requires that the client
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.
<p><b>sslTrustStore</b><br>
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 cimtrust CLI to populate the
truststore as there are strict naming requirements for trusted
certificate files. See the <a href="#CLI">cimtrust & cimcrl CLI</a>
section for further information.
</p>
<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, 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
setting. This property represents the valid OS user that corresponds to
the root certificate. All requests authenticated with a certificate
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">cimtrust CLI</a>. </p>
<p> <b>crlStore</b><br>
This is where the CRL (Certificate Revocation List) store resides.
It is important to note that certificates are
checked first against the CRL (if specified) and then against the
server truststore. The <a href="#CLI">cimcrl CLI</a> should be used for
CRL management. </p>
<h4>Configuration Limitations</h4>
The following are configuration limitations:
<ul>
  <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
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>
  <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 <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 <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>The verification depth cannot be specified. Pegasus uses the
default OpenSSL depth of 9. This means the OpenSSL will only accept
client certificate chains up to 9 levels deep.</li>
  <li>No hostname checking is performed to ensure that the subject
field of the distinguished name (DN) matches the hostname.</li>
</ul>
<h3><a name="DESIGN">SSL Design Question List</a></h3>
<p>The following questions may be helpful in determining how to
configure Pegasus CIM Server.</p>
<b>Should I enable the HTTPS port?</b><br>
Yes, especially if you are sending passwords with requests. The HTTP
port can be disabled for additional security if desired.
<br>
<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
(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.
If an administrator administrates their self-signed certificates
correctly, they are no less secure than one issued by a CA. What a CA
buys you is scalability. An up front cost of setting up a CA
relationship will be offset by the convenience of having that CA
"vouch" for certs it has signed, in large deployments. In small
deployments the incremental cost might never outweigh the initial
CA-setup cost. <br>
One important thing to remember is that you should not use the same
certificate for multiple CIMOMs. If using a self-signed certificate, a
different one should be generated for each CIMOM, using some unique
piece of data to make them different. That way, if one of the
certificates is compromised, the other ones remain secure. <br>
<b>Should the truststore be a single root CA file or a directory?</b><br>
If you only anticipate connections from a narrowly defined set of
clients, then a single root CA certificate file should be sufficient.
Alternatively, multiple trusted certificates may be stored in PEM
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 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
principle of
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.
<br>
<b>How do I protect the keystore and the truststore?</b><br>
The server's private key should always be protected; it is private for
a reason. Only the system administrator should be able to see it. The
public certificate can be viewed by anyone, however, it should be
protected from alteration by system users. Similarly, any truststore or
CRL file or directory should also be protected from alteration. See <a
 href="#CERTS">Creating SSL Certificates</a> for the recommended file
privileges. <br>
<b>When do I need to use a CRL?</b><br>
Certificate Revocation Lists are regularly issued by CA's. They contain
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">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,
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 cimtrust 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.
<h3><a name="TRUSTSTORE">Truststore Management</a></h3>
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.
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; 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
basic authentication over HTTPS, then the server can be setup to "trust
all client certificates."
<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>
To tell the cimserver to trust all clients, set the
sslClientVerification<font style="color: rgb(0, 0, 0);" color="MAGENTA">Mode</font>
property to "disabled" or "optional".
</p>
<p>The SSL verification in Pegasus is independent of any other
authentication mechanism. It can still be utilized when authentication
is disabled.
When authentication is enabled, the first line of defense is SSL client
verification. <font style="color: rgb(0, 0, 0);" color="MAGENTA">
In situations where a client is not authenticated by SSL because the
client sent no certificate and the setting is "optional", the server
will attempt to authenticate the client via another method of
authentication . In this case, the authentication mechanism specified
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">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
PG_SSLCertificateRevocationList classes in root/PG_Internal.
It is recommended that the CLIs be used in place of manual
configuration for several reasons:
<ul>
  <li>OpenSSL places strict naming restrictions on certificates and
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);">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>
  <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
accomplish this.</li>
  <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>
</ul>
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. </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
also checks the server certificate against its truststore and specifies
an additional callback in addition to the default one (the
user-specified callback is optional and can be set to null).
</p>
<ul>
  <font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore,
certPath, keyPath, verifyCert, randomFile),</b> username, password); </font>
</ul>
<p></p>
<p> 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. In this scenario, the client also checks the server
certificate against its truststore.
</p>
<ul>
  <font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore,
NULL, randomFile),</b> username password); </font>
</ul>
<p></p>
<ul>
  <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>
  <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 only be sent if the server requests it. If this option
is specified, the keyPath parameter must also be specified.</li>
  <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>
  <li><b>crlPath</b> -- This specifies an optional CRL store path. The
client checks the CRL list first, before attempting any further
authentication, including the user-specified callback.</li>
  <li><b>verifyCert</b> -- This is a user-specified verification
callback. If this is set to null, the default OpenSSL verification
callback will be executed. You can implement this method to "trust all
servers" or to perform additional authentication checks that OpenSSL
does not perform by default.</li>
  <li><b>randomFile</b> -- A file to seed the pseudo random number
generator (PRNG).</li>
</ul>
<p>Here are some general guidelines on implementing peer verification
for the client:
</p>
<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 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
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>
    <li>Ensure a certificate was received.</li>
    <ul>
      <li>WARNING:&nbsp; In some implementations of SSL a NULL server
certificate is perfectly valid and authenticates against all trust
stores.&nbsp; If the client does not ensure a certificate exists then
the client is not providing server authentication and could have a
security bulletin class defect.</li>
    </ul>
    <li>Validate that the certificate received was issued to the host
for which the client was attempting to connect.</li>
    <ul>
      <li>Ensure that the common name (CN) in the server&#8217;s certificate
subject matches the host name of the server.&nbsp; For X509v3
certificates, the &#8220;<span class="SpellE">SubjectAltName</span>&#8221; fields
in the certificate's extended attributes are also valid host names for
the certificate. </li>
      <li>WARNING:&nbsp; If the client does not ensure the host name of
the server is the same as one of the host names explicitly described in
the server&#8217;s certificate, you have not authenticated the server&#8217;s
identity.&nbsp; Any other server which was issued a certificate from
the same trusted CA can masquerade as the server unless the client
performs the host name check.</li>
    </ul>
    <li>Ensure that certificate verification methods/routines return no
errors.</li>
  </ul>
</ul>
<p>
Because only the above arguments can be passed into the Pegasus
SSLContext, there are some limitations in the client configuration:
</p>
<ul>
  <li>The verification depth cannot be specified. Pegasus uses the
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 <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 <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>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
any additional checks relevant to the application.</li>
</ul>
<h3><a name="AUTH">SSL Authorization</a></h3>
<p>The following paragraphs concern authorization of users
authenticated by certificate on the cimserver's HTTPS port.
</p>
<p> It is important to note that SSL certificates are verified during
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. </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
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
a certificate chain, the username authorization starts with the leaf
certificate. If it successfully finds a mapping
for the leaf certificate, it continues; if there is no username for the
leaf certificate, the validation proceeds up to the root certificate.
If the root certificate is reached and there is still no mapped
username, the authorization fails.</span>
</font> Additionally, if Pegasus was configured to use PAM, the
pam_acct_mgmt function will be called with the user that is mapped to
the certificate. This ensures that any login conditions that would have
been placed on a user authenticated via basic authentication are still
applied to a user authenticated via certificate. The pam_authenticate
method will NOT be called. Lastly, the providers must authorize the
user. They receive the username that was mapped to the certificate in
the OperationContext. </p>
<h3><a name="EXT">Critical Extension Handling</a></h3>
<p><font color="MAGENTA"><span style="color: rgb(0, 0, 0);">
The extensions defined for X.509 v3 certificates provide methods for
associating additional attributes with users or public keys and for
managing the certification hierarchy. Each extension in a certificate
may be designated as critical or non-critical. Pegasus relies on the
underlying OpenSSL implementation to handle critical extensions
specified in a certificate. Please refer to the OpenSSL documentation
for more information on currently supported extensions in OpenSSL and
on the behavior of OpenSSL in the case of unhandled critical extensions.</span>
</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>
<p><i><font size="2">Copyright (c) 2005 EMC Corporation;
Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open Group;
VERITAS Software Corporation</font><br>
<br>
<font size="1">Permission is hereby granted, free of charge, to any
person obtaining a copy&nbsp; of this software and associated
documentation files (the "Software"), to deal in the Software without
restriction, including without 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>
<font size="1">THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE
SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE
SOFTWARE. THE SOFTWARE IS PROVIDED&nbsp; "AS IS", WITHOUT WARRANTY OF
ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
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>
</body>
</html>