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.3 and 1.4

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

version 1.4, 2006/09/29 17:38:11

Line 17

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

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

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

<li><a href="#CLI">ssltrustmgr CLI</a> </li>

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

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

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

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

Line 58

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

<li>PEP#074 - SSLContext and Certificate verification interface

enhancement</li>

<li>PEP#155 - Support for Client SSL Certificate Verification in CIM

Server for CIMExport requests</li>

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

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

<li>PEP#200 - Recommended OpenPegasus 2.5 Build and Configuration

Line 176

Line 174

</tr>

<tr>

<td>Truststore</td>

<td>sslTrustStore, exportSSLTruststore</td>

<td>sslTrustStore</td>

</tr>

<tr>

Line 196

Line 194

<ul>

<li>The sslKeyFilePath and the sslCertificateFilePath are readable by

the CIMOM.</li>

<li>The sslTrustStore, exportSSLTrustStore, and crlStore are readable

<li>The sslTrustStore and crlStore are readable

by the CIMOM if they are a single file.</li>

<li>The sslTrustStore, exportSSLTrustStore, and crlStore are readable

<li>The sslTrustStore and crlStore are readable

and writable by the CIMOM if they are a directory.</li>

</ul>

Line 260

Line 258

sslClientVerificationMode

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

configured. It does not control the configuration of the export

configured. There are three possible settings: disabled, required,

connection. There are three possible settings: disabled, required,

optional. There is no "right" setting for this property. The default is

disabled and it is fine to leave the setting as disabled if you are

going to use basic authentication to authenticate all client requests.

Line 298

Line 295

This setting controls the truststore for the cimserver's HTTPS

connection. It can be

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

it is recommended that you use the ssltrustmgr CLI to populate the

it is recommended that you use the cimtrust CLI to populate the

truststore as there are strict naming requirements for trusted

certificate files. See the <a href="#CLI">ssltrustmgr CLI</a>

certificate files. See the <a href="#CLI">cimtrust & cimcrl CLI</a>

section for further information.

sslTrustStoreUserName

Line 314

Line 311

will be propagated to providers. If applications desire for there to be

a one-to-one correspondence between users and certificates, it is

recommended that each certificate be registered individually using the

<a href="#CLI">ssltrustmgr CLI</a>.

<a href="#CLI">cimtrust CLI</a>.

crlStore

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

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

It is important to note that certificates are

truststores are 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 specified) and then against the

truststore. The <a href="#CLI">ssltrustmgr CLI</a> should be used for

server truststore. The <a href="#CLI">cimcrl CLI</a> should be used for

CRL management.

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

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>

Line 372

Line 345

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

port can be disabled for additional security if desired.

Should I enable the export port?

Currently, the export connection provides the only way to authenticate

incoming CIM indication requests. Because basic authentication cannot

be used with these requests, the export connection should be enabled if

there is a concern over rogue client export requests. Otherwise, the

export requests can still be sent over HTTPS using the standard port;

the information will be encrypted but the client's identity will not be

validated.

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

Line 421

Line 385

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

then it probably makes sense to use the directory option to allow

flexibility in the future. In the latter scenario, the same single root

CA file can still be used with the additional step of using ssltrustmgr

CA file can still be used with the additional step of using cimtrust

to register it.

It's important to note that when registering a root CA, only one user

can be associated with ALL certificates under that CA. Following the

Line 445

Line 409

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

responsibility of the administrator

to regularly download or acquire the CRL and import it into the CRL

store using the <a href="#CLI">ssltrustmgr CLI</a>.

store using the <a href="#CLI">cimcrl CLI</a>.

CRLs are not checked

for expiration during the SSL callback. This means that if a CRL for a

particular issuer has expired,

Line 458

Line 422

If using self-signed certificates, however, a CRL is most likely not

needed (You can create a self-signed CRL but it is not really

necessary). Because of this, the certificate deletion option available

via ssltrustmgr is primarily intended for self-signed certificates.

via cimtrust is primarily intended for self-signed certificates.

Technically, CRL's are the correct way to revoke compromised or invalid

certificates.

Line 509

Line 473

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>

<h3><a name="CLI">cimtrust & cimcrl CLI</a></h3>

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

cimtrust CLI may be used to add, remove or list X509 certificates in a

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

PEM format truststore. cimcrl CLI may be used to add, remove or list

store.

X509 Certificate Revocation Lists in a PEM format CRL store.

The CLI interfaces with a certificate control provider that runs as

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

PG_SSLCertificateRevocationList classes in root/PG_Internal.

classes in root/pg_internal.

It is recommended that the CLIs be used in place of manual

It is recommended that this CLI be used in place of manual

configuration for several reasons:

<ul>

<li>OpenSSL places strict naming restrictions on certificates and

Line 525

Line 489

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

style="color: rgb(0, 0, 0);">As of 2.5.1, ssltrustmgr supports the

style="color: rgb(0, 0, 0);">cimtrust CLI supports the

ability to register a certificate without a username for root

certificates and intermediate certificates, since these certificates

represent a collection of users. In this scenario, each leaf

certificate must be registered to an individual user. See the

Authorization section for more information on username validation.

</li>

<li>The CLI,

<li>The CLIs,

or more correctly the provider it operates on, supports dynamic

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>

<li>The CLI, or more correctly the provider it operates on, performs

<li>The CLIs, or more correctly the provider they operate on, performs

a ton of error checking you would not get by manually configuring the

stores. This alerts the administrator to various error conditions (e.g.

the certificate expired) associated with a certificate or CRL.</li>

</ul>

The CIMOM must be up and running while executing ssltrustmgr. The

The CIMOM must be up and running while executing cimtrust/cimcrl CLI. The

ssltrustmgr manpage provides more information on commands and syntax.

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 SSLContext

constructor parameters. The descriptions are written from a client

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 requests it. In this scenario, the client

Line 605

Line 567

truststore and (optionally) a user-specified callback function.</li>

<li>The client should employ a truststore in order to properly verify

the server. The truststore should contain a file or directory of

trusted CA certificates. The ssltrustmgr CLI cannot be used to

trusted CA certificates. The cimtrust CLI cannot be used to

configure client truststores. The trusted certificate(s) should be

placed in a protected file or directory specified by the trustStore

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

Line 675

Line 637

If a certificate fails, the connection can be terminated immediately,

resulting in a connection exception. This scenario will occur if the

sslClientVerification property is set to "required" and no certificate

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

or an untrusted certificate is sent.

terminate the connection if an untrusted certificate is presented. Once

a certificate is verified, no further authentication is

attempted. This effectively results in any basic or local

authentication headers being ignored.

Further authorization checks must be performed when

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

that is registered to the certificate is validated as a valid system

Legend:

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

No CVS admin address has been configured