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.1 and 1.2

version 1.1, 2005/08/14 14:12:09

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

Line 4

<BODY>

<H2>OpenPegasus 2.5 SSL Guidelines</H2>

Version: 1.0

Created: July 20, 2005

<UL>

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

Line 24

Line 26

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 is intended to help developers and

infrastructure and configure the Pegasus CIM client.

administrators make the right decisions about how to use SSL for their particular application. It is important to keep in mind

that these are recommendations and may not be applicable to all scenarios. This guide assumes a basic understanding of SSL and basic authentication.

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

For more information on these technologies, consult the sources in the <A HREF="#RESOURCES">Resources</A> section at the bottom.

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

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

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

Note:

In this document, the term "trust" refers only to authentication. It does not imply full trust in the traditional sense, because

it does not take into account authorization checks. It remains the responsibility of providers and clients to perform authorization,

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

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

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

Line 50

Line 61

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

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

It has not been tested against major version 0.9.8, which came out in July 2005.

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

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

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 can be found on the <A HREF="http://www.openssl.org/news">OpenSSL News page</A>.

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:

Line 72

Line 85

<LI> PEGASUS_ENABLE_SSLV2=1 </LI>

</UL>

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

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.

Line 91

Line 104

You also need an SSL configuration file that defines the parameters of the Distinguished Name (DN). You can use the one that comes with Pegasus,

ssl.cnf in the root directory, or generate your own. For a self-signed certificate, the subject

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

The PEGASUS_ROOT and PEGASUS_HOME have to be set to your respective installation and source directory.

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

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

<pre

style="font-style: italic; font-family: courier new,courier,monospace; margin-left: 40px;">CN="Common Name"

EMAIL="test@email.address"

HOSTNAME=`uname -n`

sed -e "s/$CN/$HOSTNAME/" \

-e "s/$EMAIL/root@$HOSTNAME/" $PEGASUS_ROOT/ssl.cnf \

> $PEGASUS_HOME/ssl.cnf

chmod 644 $PEGASUS_HOME/ssl.cnf

chown bin $PEGASUS_HOME/ssl.cnf

chgrp bin $PEGASUS_HOME/ssl.cnf

/usr/bin/openssl req -x509 -days 365 -newkey rsa:1024 \

-nodes -config $PEGASUS_HOME/ssl.cnf \

-keyout $PEGASUS_HOME/key.pem -out $PEGASUS_HOME/cert.pem

cp $PEGASUS_HOME/cert.pem $PEGASUS_HOME/client.pem</pre>

With the above command, key.pem is sslKeyFilePath. cert.pem is sslCertificateFilePath, and client.pem is the client's truststore file.

To generate a CSR, execute the following command. This CSR is generally what a third-party CA requires. You submit the CSR to them and then they

<UL>

send you the signed certificate.

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

<pre

openssl genrsa -out myserver.key 1024

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

</LI>

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

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

</LI>

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

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

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>

style="font-style: italic; font-family: courier new,courier,monospace; margin-left: 40px;">

>openssl req -newkey rsa:1024 -nodes -config $PEGASUS_HOME/ssl.cnf -keyout key.pem -out req.pem

</PRE>

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>

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

Line 158

Line 139

</TBODY>

</TABLE>

Pegasus only checks the following conditions when starting up. The administrator is responsible for ensuring that the above file permissions

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

are set correctly. The administrator should also ensure that all containing directories all the way up to the base directory are not world-writeable.

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:

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

Line 179

Line 160

enableHttpsConnection

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

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

all remote communication be done over the HTTPS port. If you are sending cleartext

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>

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

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

</UL>

httpsPort

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

Line 251

Line 242

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 default value of this port is 5990.

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"

Line 275

Line 265

<A HREF="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</A></LI>

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

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

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

</UL>

<H3><A NAME="DESIGN">SSL Design Question List</A></H3>

Line 303

Line 294

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-singed certificates correctly, they are

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

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

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

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

Line 387

Line 378

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

The Pegasus CIM client can be configured for SSL by using a constructor that

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

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 also checks the server certificate against its truststore and specifies an additional

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

<UL>

client.connect(

hostname,

port,

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

username,

password);

</UL>

Here's a code snippet that shows how to call a client constructor that connects to a server over SSL and does not possess its own trusted certificate.

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

<UL>

client.connect(

hostname,

port,

SSLContext(trustStore, NULL, randomFile),

username

password);

</UL>

<UL>

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

Line 420

Line 440

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 should use a user-specified callback in addition to the default if there are additional error conditions the client wants to check.

<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 untrusted certificates.</LI>

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>

Line 465

Line 485

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

<A HREF="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</A> and

<A HREF="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</A></LI>

<LI>No hostname checking is performed to ensure that the subject field of the distinguished name (DN) matches the hostname. If desired, a user-specified callback should be configured

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

</UL>

Line 480

Line 502

This effectively results in any basic or local authentication headers being

ignored.

Further authorization checks may be performed when validating

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 user and a valid cimuser (if the cimuser function has been configured).

Additionally, if Pegasus was configured to use PAM, the pam_acct_mgmt function will be called with the

Legend:

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

No CVS admin address has been configured