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

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

version 1.4.4.1, 2006/11/23 06:22:36

Line 1

<HTML>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

<TITLE>OpenPegasus SSL Guidelines</TITLE>

<head>

<BODY>

<title>OpenPegasus SSL Guidelines</title>

<H2>OpenPegasus 2.5 SSL Guidelines</H2>

</head>

<body>

Version: 1.0

<h2>OpenPegasus 2.6 SSL Guidelines</h2>

Created: July 20, 2005

Version: 1.1

<UL>

Created: July 20, 2005

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

Updated: November 23, 2006

<LI><A HREF="#RELATED">Related Information</A>

<ul>

<LI><A HREF="#BUILDING">Building Pegasus with SSL</A>

<li>

<LI><A HREF="#CERTS">Creating SSL Certificates</A>

<a href="#OVERVIEW">Overview</a>

<LI><A HREF="#CONFIGURE">Configuring Pegasus for SSL</A>

<li>

<LI><A HREF="#DESIGN">SSL Design Question List</A>

<a href="#RELATED">Related Information</a>

<LI><A HREF="#TRUSTSTORE">Truststore Management</A>

<li>

<LI><A HREF="#CLI">ssltrustmgr CLI</A>

<a href="#BUILDING">Building Pegasus with SSL</a>

<LI><A HREF="#CLIENT">Configuring the Pegasus CIM Client for SSL</A>

<li>

<LI><A HREF="#AUTH">SSL Authorization</A>

<a href="#CERTS">Creating SSL Certificates</a>

<LI><A HREF="#RESOURCES">Resources</A>

<li>

</UL>

<a href="#CONFIGURE">Configuring Pegasus for SSL</a>

<li>

<a href="#DESIGN">SSL Design Question List</a>

<H3><A NAME="OVERVIEW">Overview</A></H3>

<li>

<a href="#TRUSTSTORE">Truststore Management</a>

<li>

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

<a href="#CLI">cimtrust & cimcrl CLI</a>

<li>

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

<li>

<a href="#AUTH">SSL Authorization</a>

<li>

<a href="#EXT">Critical Extension Handling</a>

<li>

<a href="#RESOURCES">Resources</a>

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

This guide requires a basic understanding of SSL, OpenSSL, and basic authentication. This guide is intended to help developers

This guide requires a basic understanding of SSL, OpenSSL, and basic

and administrators make the right decisions about how to use SSL for their particular application.

authentication. This guide is intended to help developers and administrators

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

make the right decisions about how to use SSL for their particular application.

consult the sources in the <A HREF="#RESOURCES">Resources</A> section at the bottom.

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.

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,

Note: In this document, the term "trust" refers only to authentication. It does

and therefore establish real trust. Likewise, the term "Trust Store" can be misleading since the "store" is only a source of

not imply full trust in the traditional sense, because it does not take into

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

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

<H3><A NAME="RELATED">Related Information</A></H3>

authentication credentials. Please bear this in mind when documenting

A significant portion of the information in this document is taken from various PEP's.

recommended deployments or building clients or providers.

This document attempts to bring all of this information

together in a cohesive and simplified format.

<h3><a name="RELATED">Related Information</a></h3>

A significant portion of the information in this document is taken from various

<UL>

PEP's. This document attempts to bring all of this information together in a

<LI>PEP#035 - Add support for /dev/random in SSLContext</LI>

cohesive and simplified format.

<LI>PEP#060 - SSL support in CIM/XML indication delivery</LI>

<LI>PEP#074 - SSLContext and Certificate verification interface enhancement</LI>

<ul>

<LI>PEP#155 - Support for Client SSL Certificate Verification in CIM Server for CIMExport requests</LI>

<li>

<LI>PEP#165 - SSL Client Verification</LI>

PEP#035 - Add support for /dev/random in SSLContext

<LI>PEP#187 - SSL Certificate Management Enhancements</LI>

<li>

<LI>PEP#200 - Recommended OpenPegasus 2.5 Build and Configuration Options for Selected Platforms</LI>

PEP#060 - SSL support in CIM/XML indication delivery

</UL>

<li>

PEP#074 - SSLContext and Certificate verification interface enhancement

<li>

<H3><A NAME="BUILDING">Building Pegasus with SSL</A></H3>

PEP#165 - SSL Client Verification

<li>

To build Pegasus with HTTPS support, you will need to build against the <A HREF="http://www.openssl.org">OpenSSL

PEP#187 - SSL Certificate Management Enhancements

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

<li>

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

PEP#200 - Recommended OpenPegasus 2.5 Build and Configuration Options for

do not contain the certificate revocation list (CRL) support that the OpenPegasus 2.5 utilizes.

Selected Platforms</li>

Because this is an open source project, the SSL support has been tested with many versions of OpenSSL,

</ul>

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

<h3><a name="BUILDING">Building Pegasus with SSL</a></h3>

be found on the <A HREF="http://www.openssl.org/news">OpenSSL News page</A>.

To build Pegasus with HTTPS support, you will need to build against the <a href="http://www.openssl.org">

OpenSSL package</a>. The SSL

After grabbing the OpenSSL source tarball, you need to set the following environment variables before building Pegasus:

support outlined here has been tested against recent releases of the major

<UL>

versions 0.9.7X and 0.9.8X (most notably, 0.9.7d). Because some versions of

<LI>PEGASUS_HAS_SSL=1</LI>

0.9.6X do not contain full support for the security functions that Pegasus

<LI>OPENSSL_HOME=<location of the SDK package> This directory must contain

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

After grabbing the OpenSSL source tarball, you need to set the following

environment variables before building Pegasus:

<ul>

<li>

PEGASUS_HAS_SSL=1

<li>

OPENSSL_HOME=<location of the SDK package> This directory must contain

the OpenSSL include directory, $(OPENSSL_HOME)/include, and the OpenSSL library

directory, $(OPENSSL_HOME)/lib.</LI>

directory, $(OPENSSL_HOME)/lib.

<LI>OPENSSL_BIN=<location of the binary package> This only needs to be

<li>

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

OPENSSL_BIN=<location of the binary package> This only needs to be set if

</UL>

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.

Note that Pegasus supports SSLv3 and TLSv1 by default. It does NOT support

To turn on SSLv2 support, enable the additional environment variable:

SSLv2. To turn on SSLv2 support, enable the additional environment variable:

<UL>

<ul>

<LI> PEGASUS_ENABLE_SSLV2=1 </LI>

<li>

</UL>

PEGASUS_ENABLE_SSLV2=1

</li>

It is not recommended to enable this protocol, as there have been many security weaknesses associated with it. Unless you are dealing

</ul>

with very outdated clients, you probably do not need to enable it.

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

After setting these variables, proceed as normal with the build instructions in the readme file.

clients, you probably do not need to enable it.

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

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>

<LI>Certificate issued by a third-party certificate authority</LI>

Self-signed certificate

</UL>

<li>

Certificate issued by a third-party certificate authority</li>

To generate a self-signed certificate, you must create a private key, a certificate signing request (CSR), and finally the public x509 certificate.

</ul>

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

To generate a self-signed certificate, you must create a private key, a

is the same as the issuer. Execute the following commands to create a self-signed certificate.

certificate signing request (CSR), and finally the public x509 certificate. You

The PEGASUS_ROOT and PEGASUS_HOME have to be set to your respective installation and source directory. You will also need an OpenSSL configuration

also need an SSL configuration file that defines the parameters of the

file. There is a sample configuration file that comes with the OpenSSL package.

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

<UL>

self-signed certificate. The PEGASUS_ROOT and PEGASUS_HOME have to be set to

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

your respective installation and source directory. You will also need an

openssl genrsa -out myserver.key 1024

OpenSSL configuration file. There is a sample configuration file that comes

with the OpenSSL package.

<ul>

<li>

To generate a private key, execute the following:

openssl genrsa -out myserver.key 1024

Set the "sslKeyFilePath" configuration property to point to this key file.

</LI>

<li>

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

To generate a certificate signing request, execute the following:

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

openssl req -config openssl.cnf -new -key

</LI>

myserver.key -out myserver.csr

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

<li>

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

At this point, the certificate signing request can be sent out to a third-party

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

certificate authority for signing, or a self-signed certificate can be

Set the "sslCertificateFilePath" configuration property to point to this certificate file. The above CSR file can be discarded

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

after the certificate is created.

openssl x509 -in myserver.csr -out

</LI>

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

</UL>

Set the "sslCertificateFilePath" configuration property to point to this

certificate file. The above CSR file can be discarded after the certificate is

created.

After creating the keypair, make sure you protect the information sufficiently by changing permissions on the files and/or directories.

</li>

The following table shows the recommended privileges:

</ul>

After creating the keypair, make sure you protect the information sufficiently

by changing permissions on the files and/or directories. The following table

<TBODY>

shows the recommended privileges:

<TR><TH>SSL file</TH><TH>Pegasus Config property</TH><TH>Permissions</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, exportSSLTruststore</TD> <TD>rwxr-xr-x</TD></TR>

<tbody>

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

<tr>

</TBODY>

<th>

</TABLE>

SSL file</th>

<th>

The administrator is responsible for ensuring that the above file permissions are set correctly.

Pegasus Config property</th>

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:

<th>

<UL>

Permissions</th>

<LI>The sslKeyFilePath and the sslCertificateFilePath are readable by the CIMOM.</LI>

</tr>

<LI>The sslTrustStore, exportSSLTrustStore, and crlStore are readable by the CIMOM if they are a single file.</LI>

<tr>

<LI>The sslTrustStore, exportSSLTrustStore, and crlStore are readable and writable by the CIMOM if they are a directory.</LI>

<td>Private key</td>

</UL>

<td>sslKeyFilePath</td>

These same file permissions should be used for protecting a client's private key, public key, truststore, and crl store as well.

</tr>

<tr>

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

<td>Public certificate</td>

HOW-TO documentation</A>.

<td>sslCertificateFilePath</td>

<H3><A NAME="CONFIGURE">Configuring Pegasus for SSL</A></H3>

</tr>

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

<tr>

create a more secure environment. More information on the default and recommended settings can be found in

<td>Truststore</td>

PEP#200 Recommended OpenPegasus 2.5 Build and Configuration Options for Selected Platforms. Additionally, the section on

<td>sslTrustStore</td>

<A HREF="#DESIGN">Design Question List</A> should help determine what these settings should be for a given application.

</tr>

<tr>

enableHttpsConnection

<td>CRL store

This is disabled by default on most platforms. It is recommended that

</td>

all remote communication be done over the HTTPS port. However, if you are sending cleartext

<td>crlStore</td>

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

</tr>

to it.

</tbody>

The HTTPS connection is enabled by default only on the following platforms:

</table>

<UL>

The administrator is responsible for ensuring that the above file permissions

<LI>LINUX</LI>

are set correctly. The administrator should also ensure that all containing

directories all the way up to the base directory are not world-writable.

<LI>HP_UX (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</LI>

Pegasus only checks the following conditions when starting up:

<LI>VMS (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</LI>

</UL>

<ul>

<li>

The sslKeyFilePath and the sslCertificateFilePath are readable by the CIMOM.

<li>

httpsPort

The sslTrustStore and crlStore are readable by the CIMOM if they are a single

file.

<li>

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

<ul>

<li>

LINUX

<li>

OS-400

<li>

HP_UX (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)

<li>

VMS (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</li>

</ul>

httpsPort

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

sslCertificateFilePath

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

sslCertificateFilePath

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.

This is the path to the x509 server certificate. The server certificate may be

The certificate cannot be encrypted because there is currently no mechanism for decrypting the certificate using a user-supplied password.

a chain in which case the file should contain PEM encoded certificates

This property must be defined if enableHttpsConnection is true.

beginning with the server certificate and followed by each signing certificate

Any failure in finding this file will result in the cimserver failing to start.

authority (CA) including the root CA. If the server certificate is a self

See <A HREF="#CERTS">Creating SSL Certificates</A> for more information.

signed certificate, the file only contains the self-signed certificate in PEM

format. The certificate cannot be encrypted because there is currently no

sslKeyFilePath

mechanism for decrypting the certificate using a user-supplied password. This

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

property must be defined if enableHttpsConnection is true. Any failure in

enableHttpsConnection is true. Any failure in finding this file will result in the cimserver failing to start.

finding this file will result in the cimserver failing to start. See <a href="#CERTS">

See <A HREF="#CERTS">Creating SSL Certificate</A> for more information.

Creating SSL Certificates</a> for more information.

sslClientVerificationMode

sslKeyFilePath

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.

sslClientVerificationMode

This setting controls how the cimserver (i.e. the HTTPS port) is configured.

It does not control the configuration of the export connection. There are three

There are three possible settings: disabled, required, optional. There is no

possible settings: disabled, required, optional. There is no "right" setting

"right" setting for this property. The default is disabled and it is fine to

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

Other environments may be heterogeneous, in which case it makes sense to allow

environments may be heterogeneous, in which case it makes sense to allow both

both basic authentication and SSL certificate verification. The setting of this

basic authentication and SSL certificate verification. The setting of this variable

variable also impacts what happens during the OpenSSL handshake:

also impacts what happens during the OpenSSL handshake:

<UL>

<ul>

<LI>"required" -- The server requires that the client certificate be trusted in order for the handshake to continue.

<li>

If the client fails to send a certificate or sends an untrusted certificate, the handshake is immediately terminated.</LI>

"required"

<LI>"optional" -- The server will request that a client certificate be sent, but will continue the handshake even if no certificate is

-- The server requires that the client certificate be trusted in order for the

received. If authentication is enabled, the server will seek to authenticate the client via an alternative method of authentication.</LI>

handshake to continue. If the client fails to send a certificate or sends an

<LI>"disabled" -- The server will not prompt the client for a certificate. This is the default.</LI>

untrusted certificate, the handshake is immediately terminated.

</UL>

<li>

Pegasus currently ties a certificate to a valid OS user. Multiple certificates may be registered to the same user. When a certificate is

"optional" -- The server will request that a client certificate be sent,

authenticated, Pegasus views it in the same way as if a user was authenticated via basic authentication. The providers

but will continue the handshake even if no certificate is received. If

receive the username that the certificate was mapped to. See the SSL Authorization section

authentication is enabled, the server will seek to authenticate the client via

for more information.

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

sslTrustStore

authentication would have proceeded.

This setting controls the truststore for the cimserver's HTTPS connection. It can be

<li>

either a directory or a single root CA file. When set to a directory, it is recommended that you use the ssltrustmgr CLI

"disabled" -- The server will not prompt the client for a certificate. This

to populate the truststore as there are strict naming requirements for trusted certificate files. See the <A HREF="#CLI">ssltrustmgr CLI</A>

is the default.</li>

section for further information.

</ul>

Pegasus currently ties a certificate to a valid OS user. Multiple certificates

sslTrustStoreUserName

may be registered to the same user. When a certificate is authenticated,

This setting is only utilized if the sslTrustStore is a single CA file. It is not used if the sslTrustStore setting is a directory,

Pegasus views it in the same way as if a user was authenticated via basic

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

authentication. The providers receive the username that the certificate was

setting. This property represents the valid OS user that corresponds to the root certificate. All requests authenticated with a certificate

mapped to. See the SSL Authorization section for more information.

under the root CA will be associated with this user and the username will be propagated to providers. If applications desire for there to

sslTrustStore

be a one-to-one correspondence between users and certificates, it is recommended that each certificate be registered individually using the

This setting controls the truststore for the cimserver's HTTPS connection. It

<A HREF="#CLI">ssltrustmgr CLI</A>.

can be either a directory or a single root CA file. When set to a directory, it

crlStore

is recommended that you use the cimtrust CLI to populate the truststore as

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

there are strict naming requirements for trusted certificate files. See the <a href="#CLI">

only one CRL store for all truststores. Currently, only two truststores are

cimtrust & cimcrl CLI</a> section for further information.

supported (cimserver and export) and these both share the same CRL store. It

is important to note that certificates are checked first against the CRL (if

sslTrustStoreUserName

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

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

crlStore

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.

enableSSLExportClientVerification

<h4>Configuration Limitations</h4>

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

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

This setting controls the truststore for the export connection. It may be the same as the sslTrustStore. Additionally, it can be

either a directory or a single root CA file. When set to a directory, it is recommended that you use the <A HREF="#CLI">ssltrustmgr CLI</A>

to populate the truststore as there are strict naming requirements for trusted certificate files.

<H4>Configuration Limitations</H4>

The following are configuration limitations:

<ul>

<UL>

<li>

<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

The x509 server certificate file cannot be encrypted. The reason for this is

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>

that there is currently no mechanism in Pegasus to grab the password needed to

<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

unencrypt it. Therefore, the best way to secure the file is to follow the file

<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

permissions settings specified in <a href="#CERTS">Creating SSL Certificates.</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>

<li>

<LI>The verification depth cannot be specified. Pegasus uses the default OpenSSL depth of 9. This means the OpenSSL will only accept client

There is no property to specify supported cipher lists at this time. Pegasus

certificate chains up to 9 levels deep.</LI>

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

<LI>No hostname checking is performed to ensure that the subject field of the distinguished name (DN) matches the hostname.</LI>

http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</a> and

</UL>

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

The verification depth cannot be specified. Pegasus uses the default OpenSSL

depth of 9. This means the OpenSSL will only accept client certificate chains

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

up to 9 levels deep.

<li>

Should I enable the HTTPS port?

No hostname checking is performed to ensure that the subject field of the

Yes, especially if you are sending passwords with requests. The HTTP port can be disabled for additional security if desired.

distinguished name (DN) matches the hostname.</li>

</ul>

Should I enable the export port?

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

Currently, the export connection provides the only way to authenticate incoming CIM indication requests.

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

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

CIM Server.

there is a concern over rogue client export requests. Otherwise, the export requests can still be sent over

Should I enable the HTTPS port?

HTTPS using the standard port; the information will be encrypted but the client's identity will not be validated.

Yes, especially if you are sending passwords with requests. The HTTP port can

be disabled for additional security if desired.

Should I configure the CIMOM to use a truststore?

This depends on the infrastructure of the application. If all clients are using basic authentication over the secure port

Should I configure the CIMOM to use a truststore?

(and the passwords are secured), then a truststore may not be needed. If an application does not want to store user/pw information,

This depends on the infrastructure of the application. If all clients are using

then it is a good idea to use a certificate-based infrastructure. If a CIMOM certificate is compromised, the cimserver and the providers

basic authentication over the secure port (and the passwords are secured), then

of the system are compromised. The severity of this scenario is dependent on the resources the providers have access to.

a truststore may not be needed. If an application does not want to store

If an OS password is compromised, the entire system may be compromised.

user/pw information, then it is a good idea to use a certificate-based

If using peer verification, it is important to ensure that 1) the cimserver is properly configured to use a truststore,

infrastructure. If a CIMOM certificate is compromised, the cimserver and the

2) the truststore is loaded properly and protected, and 3) authorization checks are performed after a certificate is verified.

providers of the system are compromised. The severity of this scenario is

These same conditions also apply to a client that is verifying a server.

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,

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

it is important to ensure that 1) the cimserver is properly configured to use a

Generally, scalability will determine whether it's appropriate to use a self-signed certificate or one issued by Verisign

truststore, 2) the truststore is loaded properly and protected, and 3)

or another third-party certificate authority.

authorization checks are performed after a certificate is verified. These same

If an administrator administrates their self-signed certificates correctly, they are

conditions also apply to a client that is verifying a server.

no less secure than one issued by a CA. What a CA buys you is scalability. An up front cost of

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

setting up a CA relationship will be offset by the convenience of having that

certificate authority?

CA "vouch" for certs it has signed, in large deployments. In small deployments

Generally, scalability will determine whether it's appropriate to use a

the incremental cost might never outweigh the initial CA-setup cost.

self-signed certificate or one issued by Verisign or another third-party

One important thing to remember is that

certificate authority. If an administrator administrates their self-signed

you should not use the same certificate for multiple CIMOMs. If using a self-signed

certificates correctly, they are no less secure than one issued by a CA. What a

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

CA buys you is scalability. An up front cost of setting up a CA relationship

piece of data to make them different. That way, if one of the certificates is

will be offset by the convenience of having that CA "vouch" for certs it has

compromised, the other ones remain secure.

signed, in large deployments. In small deployments the incremental cost might

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

never outweigh the initial CA-setup cost.

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.

One important thing to remember is that you should not use the same certificate

If you anticipate getting requests from a heterogeneous set of clients, then it probably makes sense to use the directory option

for multiple CIMOMs. If using a self-signed certificate, a different one should

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.

be generated for each CIMOM, using some unique piece of data to make them

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

different. That way, if one of the certificates is compromised, the other ones

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.

remain secure.

How do I protect the keystore and the truststore?

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

The server's private key should always be protected; it is private for a reason.

If you only anticipate connections from a narrowly defined set of clients, then

Only the system administrator should be able to see it. The public certificate

a single root CA certificate file should be sufficient. Alternatively, multiple

can be viewed by anyone, however, it should be protected from alteration by system

trusted certificates may be stored in PEM format inside of a single CA file. If

users. Similarly, any truststore or CRL file or directory should also be protected

you anticipate getting requests from a heterogeneous set of clients, then it

from alteration. See <A HREF="#CERTS">Creating SSL Certificates</A> for the recommended

probably makes sense to use the directory option to allow flexibility in the

file privileges.

future. In the latter scenario, the same single root CA file can still be used

When do I need to use a CRL?

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.

How do I protect the keystore and the truststore?

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.

When do I need to use a CRL?

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

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

does not check CRL validity dates during startup. Therefore, it is the responsibility of the administrator

itself does not check CRL validity dates during startup. Therefore, it is the

to regularly download or acquire the CRL and import it into the CRL store using the <A Href="#CLI">ssltrustmgr CLI</A>.

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

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

CRLs are not checked for expiration during the SSL callback. This means that if

necessary). Because of this, the certificate deletion option available via ssltrusmgr is primarily intended for self-signed certificates.

a CRL for a particular issuer has expired, Pegasus still accepts certificates

Technically, CRL's are the correct way to revoke compromised or invalid 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

What is the order of operations for certificate verification?

not checked for critical extensions during CRL verification. If a CRL contains

The certificate is checked against any CRLs first before going through the rest of the verification process. Verification starts with the

a critical extension it will be ignored.

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.

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

<H3><A NAME="TRUSTSTORE">Truststore Management</A></H3>

intended for self-signed certificates. Technically, CRL's are the correct way

There are two directions of trust in an SSL client-server handshake: The client trusts the server. The server trusts the client. Pegasus

to revoke compromised or invalid certificates.

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;

What is the order of operations for certificate verification?

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

The certificate is checked against any CRLs first before going through the rest

basic authentication over HTTPS, then the server can be setup to "trust all client certificates."

of the verification process. Verification starts with the root certificate and

To tell the cimserver to require that all clients be trusted, simply set the

continues down to the peer certificate. If verification fails at any of these

sslClientVerification property to "required."

points, the certificate is considered untrusted and the verification process

To tell the cimserver to trust all clients, set the sslClientVerification property

reports an error.

to "disabled" or "optional".

<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

The SSL verification in Pegasus is independent of any other authentication mechanism. It can still be utilized when authentication is disabled.

support both levels of trust for maximum security and this is the

When authentication is enabled, the first line of defense is SSL client verification.

implementation Pegasus recommends. However, in some scenarios it may make sense

In situations where a client is not authenticated by SSL and the setting is "optional", the server will attempt to authenticate the client

to only implement one of these; in that case, it is possible to override the

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

client or the server to "trust all certificates." For example, if all clients

for remote connections and local authentication will be used for local connections.

will be using basic authentication over HTTPS, then the server can be setup to

"trust all client certificates."

See the <A HREF="#CLIENT">Configuring the Pegasus CIM Client for SSL</A> section below on how to setup the client's truststore.

To tell the cimserver to require that all clients be trusted, simply set the

sslClientVerificationMode

<H3><A NAME="CLI">ssltrustmgr CLI</A></H3>

property to "required."

To tell the cimserver to trust all clients, set the sslClientVerificationMode

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.

property to "disabled" or "optional".

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.

The SSL verification in Pegasus is independent of any other authentication

It is recommended that this CLI be used in place of manual configuration for several reasons:

mechanism. It can still be utilized when authentication is disabled. When

<UL>

authentication is enabled, the first line of defense is SSL client

<LI>OpenSSL places strict naming restrictions on certificates and CRLs in a directory (the files are looked up via a subject hash code)</LI>

verification. In situations where a

<LI>Certificate instances are stored in the repository along with the corresponding username. If the certificate is not properly registered,

client is not authenticated by SSL because the client sent no certificate and

the username mapping will fail.</LI>

the setting is "optional", the server will attempt to authenticate the client

<LI>The CLI allows for dynamic deletion of certificates by resetting the SSL context. Normally, you would need to stop and start

via another method of authentication . In this case, the authentication

the cimserver to accomplish this.</LI>

mechanism specified by the configuration property "httpAuthType" will be used

<LI>The CLI, or more correctly the provider it operates on, performs a ton of error checking you would not get by manually configuring

for remote connections and local authentication will be used for local

the stores. This alerts the administrator to various error conditions (e.g. the certificate expired) associated with a certificate or CRL.</LI>

connections. In situations where a client is not authenticated by SSL because

</UL>

the client certificate was invalid, the handshake will be terminated.

The CIMOM must be up and running while executing ssltrustmgr. The ssltrustmgr manpage provides more information on commands and syntax.

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

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

should be defined.

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

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

Certificate instances are stored in the repository along with the corresponding

username. If the certificate is not properly registered, the username mapping

will fail.

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.

<li>

The CLIs,

or more correctly the provider they operate on, supports dynamic

deletion of certificates by resetting the cimserver's SSL context.

Normally, you would need to stop and start the cimserver to accomplish this.

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

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

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

SSLContext constructor parameters. The descriptions are written from a client

various SSLContext constructor parameters.

perspective even though the same constructors are utilized by the 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 certificate if the server

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

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

the server requests it. In this scenario, the client also checks the server certificate against its truststore and specifies an additional

against its truststore and specifies an additional callback in addition to the

callback in addition to the default one (the user-specified callback is optional and can be set to null).

default one (the user-specified callback is optional and can be set to null).

<UL>

client.connect(

<ul>

hostname,

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

port,

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

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

</ul>

username,

password);

Here's a code snippet that shows how to call a client constructor that connects

</UL>

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.

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.

<ul>

In this scenario, the client also checks the server certificate against its truststore.

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

<UL>

randomFile), username password);

</ul>

client.connect(

hostname,

<ul>

port,

<li>

SSLContext(trustStore, NULL, randomFile),

trustStore

username

-- This specifies the truststore that the client uses to verify server

password);

certificates. It can be String::EMPTY if no truststore exists.

<li>

</UL>

certPath

-- This specifies the x509 certificate of the client that will be sent during

<UL>

an SSL handshake. Note that this certificate will only be sent if the server

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

requests it. If this option is specified, the keyPath parameter must also be

specified.

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

<li>

only be sent if the server requests it. If this option is specified, the keyPath parameter must also be specified.</LI>

keyPath

-- This specifies the private key of the client. If this option is specified,

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

the certPath parameter must also be specified.

<li>

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

crlPath

including the user-specified callback.</LI>

-- This specifies an optional CRL store path. The client checks the CRL list

first, before attempting any further authentication, including the

<LI>verifyCert -- This is a user-specified verification callback. If this is set to null, the default OpenSSL verification callback will

user-specified callback.

be executed. You can implement this method to "trust all servers" or to perform additional authentication checks that OpenSSL does not perform

<li>

by default.</LI>

verifyCert

-- This is a user-specified verification callback. If this is set to null, the

<LI>randomFile -- A file to seed the pseudo random number generator (PRNG).</LI>

default OpenSSL verification callback will be executed. You can implement this

method to "trust all servers" or to perform additional authentication checks

</UL>

that OpenSSL does not perform by default.

<li>

Here are some general guidelines on implementing peer verification for the client:

randomFile -- A file to seed the pseudo random number generator (PRNG).</li>

<UL>

</ul>

<LI>The client should enable peer verification by specifying a truststore and (optionally) a user-specified callback function.</LI>

Here are some general guidelines on implementing peer verification for the

<LI>The client should employ a truststore in order to properly verify the server. The truststore should contain a file or directory of

client:

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

<ul>

to pick up any truststore changes.</LI>

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

The client should enable peer verification by specifying a truststore and

In most cases, the default verification callback is sufficient for checking server certificates.</LI>

(optionally) a user-specified callback function.

<LI>The client should ensure that adequate entropy is attained.</LI>

<li>

<LI>The client should use a CRL store if the truststore contains CA certificates that support one.</LI>

The client should employ a truststore in order to properly verify the server.

<LI>The client should only use the SSLv3 and TLSv1 protocols. By default, Pegasus is not built with SSLv2 support.</LI>

The truststore should contain a file or directory of trusted CA certificates.

The cimtrust CLI cannot be used to configure client truststores. The trusted

<li>The client should terform post-connection checks. </li>

certificate(s) should be placed in a protected file or directory specified by

<ul>

the trustStore parameter. Keep in mind that the SSL context generally has to be

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

reloaded to pick up any truststore changes.

<ul>

<li>

<li>WARNING:  In some implementations of SSL

The client could also use a user-specified callback in addition to the default

a NULL server certificate is perfectly valid and authenticates against

verification callback, if additional verifications are desired over the normal

all trust stores.  If the client does not ensure a certificate

checks that OpenSSL performs. In most cases, the default verification callback

exists then the client is not providing server authentication and could

is sufficient for checking server certificates.

have a security bulletin class defect.</li>

<li>

</ul>

The client should ensure that adequate entropy is attained.

<li>Validate that the certificate received was issued to the

<li>

host for which the client was attempting to connect.</li>

The client should use a CRL store if the truststore contains CA certificates

<ul>

that support one.

<li>Ensure that the common name (CN) in the server’s

<li>

certificate subject matches the host name of the server.  For X509v3

The client should only use the SSLv3 and TLSv1 protocols. By default, Pegasus

certificates, the “SubjectAltName”

is not built with SSLv2 support.

fields in the certificate's extended attributes are also valid host names

<li>

for the certificate. </li>

The client should perform post-connection checks.

<li>WARNING:  If the client does not ensure

<ul>

the host name of the server is the same as one of the host names explicitly

<li>

described in the server’s certificate, you have not authenticated

Ensure a certificate was received.

the server’s identity.  Any other server which was issued

<ul>

a certificate from the same trusted CA can masquerade as the server

<li>

WARNING:  In some implementations of SSL a NULL server certificate is

perfectly valid and authenticates against all trust stores.  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.

<ul>

<li>

Ensure that the common name (CN) in the server�s certificate subject matches

the host name of the server.  For X509v3 certificates, the �SubjectAltName�

fields in the certificate's extended attributes are also valid host names for

the certificate.

<li>

WARNING:  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�s certificate,

you have not authenticated the server�s identity.  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

<li>

return no errors.</li>

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

</ul>

</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 default OpenSSL depth of 9.</LI>

<li>

<LI>The cipher list cannot be specified. Pegasus uses the default OpenSSL cipher list. The cipher lists can be found at

The verification depth cannot be specified. Pegasus uses the default OpenSSL

<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

depth of 9.

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

<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

The cipher list cannot be specified. Pegasus uses the default OpenSSL cipher

to perform this check or any additional checks relevant to the application.</LI>

list. The cipher lists can be found at <a href="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">

</UL>

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>

<H3><A NAME="AUTH">SSL Authorization</A></H3>

No hostname checking is performed to ensure that the subject field of the

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

distinguished name (DN) matches the hostname. If desired, a user-specified

It is important to note that SSL certificates are verified during the initial

callback should be configured to perform this check or any additional checks

handshake, BEFORE any further authentication takes place. If a certificate fails,

relevant to the application.</li>

the connection can be terminated immediately, resulting in a connection exception.

</ul>

This scenario will occur if the sslClientVerification property is set to "required"

<h3><a name="AUTH">SSL Authorization</a></h3>

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

The following paragraphs concern authorization of users authenticated by

will also terminate the connection if an untrusted certificate is presented.

certificate on the cimserver's HTTPS port.

Once a certificate is verified, no further authentication is attempted.

This effectively results in any basic or local authentication headers being

ignored.

It is important to note that SSL certificates are verified during the initial

handshake, BEFORE any further authentication takes place. If a certificate

Further authorization checks must be performed when validating

fails, the connection can be terminated immediately, resulting in a connection

the user that is mapped to the certificate. First, the user that is registered to the certificate

exception. This scenario will occur if the sslClientVerification property is

is validated as a valid system user and a valid cimuser (if the cimuser function has been configured).

set to "required" and no certificate or an untrusted certificate is sent.

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.

Further authorization checks must be performed when validating

The pam_authenticate method will NOT be called. Lastly, the providers must authorize the user. They receive the

the user that is mapped to the certificate. First, the user that is registered

username that was mapped to the certificate in the OperationContext.

to the certificate is validated as a valid system user and a valid cimuser (if

the cimuser function has been configured).

<H3><A NAME="RESOURCES">Resources</A></H3>

In the case of

a certificate chain, the username authorization starts with the leaf

certificate. If it successfully finds a mapping

For OpenSSL information pick up a copy of O'Reilly's Network Security with OpenSSL or go to the OpenSSL Site:

for the leaf certificate, it continues; if there is no username for the

<A HREF="http://www.openssl.org">http://www.openssl.org</A>

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.

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

Additionally, if Pegasus was configured to use PAM, the pam_acct_mgmt

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

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

x509 Certificate and CRL RFC:

authenticated via certificate. The pam_authenticate method will NOT be called.

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

Lastly, the providers must authorize the user. They receive the username that

was mapped to the certificate in the OperationContext.

SSLv3 RFC:

A provider may request the client's certificate chain information through its

<A HREF="http://wp.netscape.com/eng/ssl3/">http://wp.netscape.com/eng/ssl3</A>

provider registration MOF. The "RequestedOperationContextContainers" property

of PG_Provider should be set to include the "SSLCertificateChainContainer"

value. If a client is authenticated via trusted certificate, then the container

TLSv1 RFC:

will include a certificate for each level in the client's certificate chain, up

to a maximum depth of seven.

The behavior of this property is dependent on the overall

CIMOM settings. The "enableHttpsConnection" configuration property must be set

Basic Authentication RFC:

to true for the property to have any effect. Additionally, the

"sslClientVerificationMode" configuration property must be set to either

"required" or "optional". If "required" is specified, then the container will

always be populated. If "optional" is specified, the container will be populated

only if the client is authenticated via trusted certificate, as opposed to

another mechanism such as basic authentication. Because the container may not

always be included in the OperationContext, providers should always check for

its existence before performing operations on it. See the SSLCertificateInfo

class in Pegasus/Common/SSLContext.h for a full list of certificate parameters

that the SSLCertificateChainContainer supports.

<o:p></o:p>

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

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.

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

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

Permission is hereby granted, free of charge, to any person

obtaining a copy  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:

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL

BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE

IS PROVIDED  "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE SHALL BE INCLUDED IN ALL

INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A

PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR

COPIES OR SUBSTANTIAL PORTIONS OF THE SOFTWARE. THE SOFTWARE IS PROVIDED 

"AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT

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.

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.

<hr>

</body>

</BODY>

</html>

</HTML>

Legend:

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

No CVS admin address has been configured