pegasus/doc/PegasusSSLGuidelines.htm - diff

Return to PegasusSSLGuidelines.htm CVS log

Up to [Pegasus] / pegasus / doc

Diff for /pegasus/doc/PegasusSSLGuidelines.htm between version 1.2 and 1.3

version 1.2, 2005/09/02 18:32:28

version 1.3, 2006/03/24 03:56:39

Line 1

<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>

Version: 1.0

<h2>OpenPegasus 2.5.1 SSL Guidelines</h2>

Created: July 20, 2005

Version: 1.1

<UL>

Created: July 20, 2005

<LI><A HREF="#OVERVIEW">Overview</A>

Updated: March 20, 2006

<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>

<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

infrastructure and configure the Pegasus CIM client.

The following document serves as a guide on how to build and configure

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.

It is not intended to be a primary source of education on SSL. If you are not familiar with these technologies,

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

administrators make the right decisions about how to use SSL for their

particular application. It is not intended to be a primary source of

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

authentication credentials. Please bear this in mind when documenting recommended deployments or building clients or providers.

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.

<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.

<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>

<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>

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).

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

fully supported by some versions of 0.9.6X), Pegasus does not

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.

<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

set if the OpenSSL binaries are not in $(OPENSSL_HOME)/bin.</LI>

</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.

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,

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>

</ul>

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

environment variable:

<ul>

<H3><A NAME="CERTS">Creating SSL Certificates</A></H3>

<li> PEGASUS_ENABLE_SSLV2=1 </li>

</ul>

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.

After setting these variables, proceed as normal with the build

instructions in the readme file.

<h3><a name="CERTS">Creating SSL Certificates</a></h3>

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>

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

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:

set to your respective installation and source directory. You will also

openssl genrsa -out myserver.key 1024

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.

<LI>To generate a certificate signing request, execute the following:

openssl req -config openssl.cnf -new -key myserver.key -out myserver.csr

<ul>

</LI>

<li>To generate a private key, execute the following:

<LI> At this point, the certificate sigining request can be sent out to a third-party certificate authority for signing,

openssl genrsa -out

or a self-signed certificate can be generated. To generate a self-signed certificate, execute the following:

myserver.key 1024

openssl x509 -in myserver.csr -out myserver.cert -req -signkey myserver.key -days 365

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:

</LI>

openssl req -config

</UL>

openssl.cnf -new -key myserver.key -out myserver.csr

</li>

<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:

openssl x509 -in myserver.csr

-out myserver.cert -req -signkey myserver.key -days 365

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>

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:

<TBODY>

<tbody>

<TR><TH>SSL file</TH><TH>Pegasus Config property</TH><TH>Permissions</TH></TR>

<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>

<th>Pegasus Config property</th>

<TR><TD>Truststore</td><TD>sslTrustStore, exportSSLTruststore</TD> <TD>rwxr-xr-x</TD></TR>

<th>Permissions</th>

<TR><TD>CRL store </td><TD>crlStore</TD> <TD>rwxr-xr-x</TD></TR>

</tr>

</TBODY>

<tr>

</TABLE>

<td>Private key</td>

<td>sslKeyFilePath</td>

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-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>

</UL>

</tr>

<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>

<td>sslTrustStore, exportSSLTruststore</td>

For more information on generating keys and certificates, consult the <A HRef="http://www.openssl.org/docs/HOWTO/">OpenSSL

HOW-TO documentation</A>.

</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

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>

enableHttpsConnection

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:

<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>

These same file permissions should be used for protecting a client's

private key, public key, truststore, and crl store as well.

For more information on generating keys and certificates, consult

the <a href="http://www.openssl.org/docs/HOWTO/">OpenSSL HOW-TO

documentation</a>.

<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.

enableHttpsConnection

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:

<UL>

<LI>LINUX</LI>

<ul>

<li>LINUX</li>

<LI>HP_UX (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</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>

</ul>

httpsPort

httpsPort

The default setting is 5989, the official WBEM secure port.

The default setting is 5989, the official WBEM secure port.

sslCertificateFilePath

sslCertificateFilePath

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

password. This property must be defined if enableHttpsConnection is

sslKeyFilePath

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.

sslKeyFilePath

sslClientVerificationMode

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

authenticate all client requests. In many applications where a physical person

sslClientVerificationMode

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>"required" -- 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>"optional" -- 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>"disabled" -- The server will not prompt the client for a certificate. This is the default.</LI>

setting of this variable also impacts what happens during the OpenSSL

</UL>

handshake:

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>"required" -- 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>"optional" -- 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. As

of 2.5.1, if a certificate is sent but it is not validated, the

handshake will fail. Before 2.5.1,the handshake would have

continued and basic authentication would have proceeded. </li>

<li>"disabled" -- The server will not prompt the client for a

certificate. This is the default.</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.

sslTrustStore

This setting controls the truststore for the cimserver's HTTPS

sslTrustStore

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.

sslTrustStoreUserName

sslTrustStoreUserName

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

crlStore

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>.

specified) and then against the truststore. The <A Href="#CLI">ssltrustmgr CLI</A>

crlStore

should be used for CRL management.

This is where the CRL (Certificate Revocation List) store resides.

There is only one CRL store for all truststores. Currently, only two

enableSSLExportClientVerification

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.

enableSSLExportClientVerification

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.

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.

exportSSLTrustStore

exportSSLTrustStore

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.

<h4>Configuration Limitations</h4>

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

The following questions may be helpful in determining how to configure Pegasus CIM Server.

client certificate chains up to 9 levels deep.</li>

<li>No hostname checking is performed to ensure that the subject

Should I enable the HTTPS port?

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>

<h3><a name="DESIGN">SSL Design Question List</a></h3>

Should I enable the export port?

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.

Because basic authentication cannot be used with these requests, the export connection should be enabled if

Should I enable the HTTPS port?

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.

Should I configure the CIMOM to use a truststore?

Should I enable the export port?

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.

Should I configure the CIMOM to use a truststore?

Should I use a self-signed certificate or one issued by a third-party certificate authority?

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.

Should I use a self-signed certificate or one issued by a

third-party certificate authority?

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

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.

"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.

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.

different one should be generated for each CIMOM, using some unique

Should the truststore be a single root CA file or a directory?

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.

Alternatively, multiple trusted certificates may be stored in PEM format inside of a single CA file.

Should the truststore be a single root CA file or a directory?

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.

If you anticipate getting requests from a heterogeneous set of clients,

How do I protect the keystore and the truststore?

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.

principle of

When do I need to use a CRL?

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

in its truststore should also implement CRLs (if the CA supports them). Pegasus itself

How do I protect the keystore and the truststore?

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

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

privileges.

What is the order of operations for certificate verification?

When do I need to use a CRL?

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>.

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.

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.

What is the order of operations for certificate verification?

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:

<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

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."

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".

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 property to "required."

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.

sslClientVerificationMode

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

via another method of authentication. In this case, the authentication mechanism specified by the configuration property "httpAuthType" will be used

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.

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.

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.

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.

See the <a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a>

section below on how to setup the client's truststore.

<h3><a name="CLI">ssltrustmgr CLI</a></h3>

Pegasus 2.5 comes with a new CLI, ssltrustmgr, that should be used to

manage the cimserver's truststore, the export truststore, and the CRL

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.

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. <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.

<H3><A NAME="CLIENT">Configuring the Pegasus CIM Client for SSL</A></H3>

</li>

A Pegasus CIM client can be configured to use SSL by using a constructor that

<li>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.

details about what happens under the covers, here is a description of the various

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.

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>

<h3><a name="CLIENT">Configuring the Pegasus CIM Client for SSL</a></h3>

client.connect(

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

SSLContext(trustStore, certPath, keyPath, verifyCert, randomFile),

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

perspective even though the same constructors are utilized by the

</UL>

cimserver HTTPS port and export port.

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

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

user-specified callback is optional and can be set to null).

client.connect(

hostname,

<ul>

port,

client.connect( hostname, port, SSLContext(trustStore,

SSLContext(trustStore, NULL, randomFile),

certPath, keyPath, verifyCert, randomFile), username, password);

username

</ul>

password);

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

certificate. In this scenario, the client also checks the server

<UL>

certificate against its truststore.

<LI>trustStore -- This specifies the truststore that the client uses to verify server certificates. It can be String::EMPTY if no truststore exists. </LI>

<ul>

<LI>certPath -- This specifies the x509 certificate of the client that will be sent during an SSL handshake. Note that this certificate will

client.connect( hostname, port, 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), username password);

</ul>

<LI>keyPath -- This specifies the private key of the client. If this option is specified, the certPath parameter must also be specified.</LI>

<ul>

<LI>crlPath -- This specifies an optional CRL store path. The client checks the CRL list first, before attempting any further authentication,

<li>trustStore -- 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>verifyCert -- This is a user-specified verification callback. If this is set to null, the default OpenSSL verification callback will

<li>certPath -- 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>randomFile -- A file to seed the pseudo random number generator (PRNG).</LI>

<li>keyPath -- This specifies the private key of the client.

If this option is specified, the certPath parameter must also be

</UL>

specified.</li>

<li>crlPath -- This specifies an optional CRL store path. The

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>verifyCert -- 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>randomFile -- 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>

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:

<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>

<li>Ensure a certificate was received.</li>

<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>

<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>

<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 “SubjectAltName”

certificates, the “SubjectAltName” 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>

<li>Ensure that certificate verification methods/routines

<li>Ensure that certificate verification methods/routines return no

return no errors.</li>

errors.</li>

</ul>

</UL>

Because only the above arguments can be passed into the Pegasus

SSLContext, there are some limitations in the client configuration:

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>

The following paragraphs concern authorization of users authenticated by certificate on the cimserver's HTTPS port.

</ul>

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,

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"

and no certificate or an untrusted certificate is sent. The export connection

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 authentication 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

or an untrusted certificate is sent. The export connection will also

Further authorization 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 authentication 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.

user that is mapped to the certificate. This ensures that any login conditions that would have been placed

Further authorization 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).

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

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:

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.

Additionally, if Pegasus was configured to use PAM, the

A really fabulous guide on certificate management and installation with OpenSSL:

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

applied to a user authenticated via certificate. The pam_authenticate

x509 Certificate and CRL RFC:

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.

<h3><a name="EXT">Critical Extension Handling</a></h3>

SSLv3 RFC:

<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

managing the certification hierarchy. Each extension in a certificate

TLSv1 RFC:

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

Basic Authentication RFC:

on the behavior of OpenSSL in the case of unhandled critical extensions.

<h3><a name="RESOURCES">Resources</a></h3>

For OpenSSL information pick up a copy of O'Reilly's Network Security

with OpenSSL or go to the OpenSSL Site:

<a href="http://www.openssl.org">http://www.openssl.org</a>

A really fabulous guide on certificate management and installation

with OpenSSL:

<a href="http://www.gagravarr.org/writing/openssl-certs/index.shtml">http://www.gagravarr.org/writing/openssl-certs/index.shtml</a>

x509 Certificate and CRL RFC:

<a href="http://www.ietf.org/rfc/rfc2459.txt?number=2459">http://www.ietf.org/rfc/rfc2459.txt?number=2459</a>

SSLv3 RFC:

<a href="http://wp.netscape.com/eng/ssl3/">http://wp.netscape.com/eng/ssl3</a>

TLSv1 RFC:

Basic Authentication RFC:

<hr>

Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open Group;

VERITAS Software Corporation

Company, L.P.; IBM Corp.; The Open Group; VERITAS Software Corporation

Permission is hereby granted, free of charge, to any

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:

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:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE

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.

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.

<hr>

</body>

</BODY>

</html>

</HTML>

Legend:

Removed from v.1.2
changed lines
	Added in v.1.3

No CVS admin address has been configured