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 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. For more information on these technologies, consult the sources in the Resources section at the bottom.
To build Pegasus with HTTPS support, you will need to build against the OpenSSL package. 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. 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 OpenSSL News page.
After grabbing the OpenSSL source tarball, you need to set the following environment variables before building Pegasus:
It is not recommended to enable this protocol, as there have been many security holes associated with it. Unless you are dealing with very outdated clients, you probably do not need to enable it.
After setting these variables, proceed as normal with the build instructions in the readme file.
To generate a self-signed certificate, you must create a private key, a certificate signing request (CSR), and finally the public x509 certificate. You also need an SSL configuration file that defines the parameters of the Distinguished Name (DN). You can use the one that comes with Pegasus, ssl.cnf in the root directory, or generate your own. For a self-signed certificate, the subject is the same as the issuer. Execute the following commands to create a self-signed certificate. The PEGASUS_ROOT and PEGASUS_HOME have to be set to your respective installation and source directory.
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.pemWith 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 send you the signed certificate.
>openssl req -newkey rsa:1024 -nodes -config $PEGASUS_HOME/ssl.cnf -keyout key.pem -out req.pem
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:
SSL file | Pegasus Config property | Permissions |
---|---|---|
Private key | sslKeyFilePath | rwx------ |
Public certificate | sslCertificateFilePath | rwxr-xr-x |
Truststore | sslTrustStore, exportSSLTruststore | rwxr-xr-x |
CRL store | crlStore | rwxr-xr-x |
Pegasus only checks the following conditions when starting up. The administrator is responsible for ensuring that the above file permissions are set correctly. The administrator should also ensure that all containing directories all the way up to the base directory are not world-writeable.
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 OpenSSL HOW-TO documentation.
enableHttpsConnection
This is enabled by default on most platforms. It is recommended that
all remote communication be done over the HTTPS port. 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.
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
and followed by each signing certificate authority (CA) including the root CA. If the server certificate is a self signed certificate,
the file only contains the self-signed certificate in PEM format.
The certificate cannot be encrypted because there is currently no mechanism for decrypting the certificate using a user-supplied password.
This property must be defined if enableHttpsConnection is true.
Any failure in finding this file will result in the cimserver failing to start.
See Creating SSL Certificates for more information.
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 Creating SSL Certificate 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
possible settings: disabled, required, optional. There is no "right" setting
for this property. The default is disabled and it is fine to
leave the setting as disabled if you are going to use basic authentication to
authenticate all client requests. In many applications where a physical person
is there to supply a username and password, basic authentication is sufficient.
Other
environments may be heterogeneous, in which case it makes sense to allow both
basic authentication and SSL certificate verification. The setting of this variable
also impacts what happens during the OpenSSL handshake:
sslTrustStore
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 truststore as there are strict naming requirements for trusted certificate files. See the ssltrustmgr CLI
section for further information.
sslTrustStoreUserName
This setting is only utilized if the sslTrustStore is a single CA file. It is not used if the sslTrustStore setting is a directory,
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
ssltrustmgr CLI.
crlStore
This is where the CRL (Certificate Revocation List) store resides. There is
only one CRL store for all truststores. Currently, only two 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 ssltrustmgr CLI
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 default value of this port is 5990.
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 ssltrustmgr CLI
to populate the truststore as there are strict naming requirements for trusted certificate files.
The following questions may be helpful in determining how to configure Pegasus CIM Server.
Should I enable the HTTPS port? To tell the cimserver to require that all clients be trusted, simply set the
sslClientVerification property to "required."
To tell the cimserver to trust all clients, set the sslClientVerification property
to "disabled" or "optional".
The SSL verification in Pegasus is independent of any other authentication mechanism. It can still be utilized when authentication is disabled. When authentication is enabled, the first line of defense is SSL client verification. In situations where a client is not authenticated by SSL and the setting is "optional", the server will attempt to authenticate the client via another method of authentication. In this case, the authentication mechanism specified by the configuration property "httpAuthType" will be used for remote connections and local authentication will be used for local connections.
See the Configuring the Pegasus CIM Client for SSL section below on how to setup the client's truststore.
The Pegasus CIM client can be configured for 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 are some general guidelines on implementing peer verification for the client:
Because only the above arguments can be passed into the Pegasus SSLContext, there are some limitations in the client configuration:
The following paragraphs concern authorization of users authenticated by certificate on the cimserver's HTTPS port.
It is important to note that SSL certificates are verified during the initial handshake, BEFORE any further authentication takes place. If a certificate fails, the connection can be terminated immediately, resulting in a connection exception. This scenario will occur if the sslClientVerification property is set to "required" and no certificate or an untrusted certificate is sent. The export connection will also 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 may 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 user that is mapped to the certificate. This ensures that any login conditions that would have been placed on a user authenticated via basic authentication are still applied to a user authenticated via certificate. The pam_authenticate method will NOT be called. Lastly, the providers must authorize the user. They receive the username that was mapped to the certificate in the OperationContext.
For OpenSSL information pick up a copy of O'Reilly's Network Security with OpenSSL or go to the OpenSSL Site:
http://www.openssl.org
A really fabulous guide on certificate management and installation with OpenSSL:
http://www.gagravarr.org/writing/openssl-certs/index.shtml
x509 Certificate and CRL RFC:
http://www.ietf.org/rfc/rfc2459.txt?number=2459
SSLv3 RFC:
http://wp.netscape.com/eng/ssl3
TLSv1 RFC:
http://www.ietf.org/rfc/rfc2246.txt
Basic Authentication RFC:
http://www.faqs.org/rfcs/rfc2617.html
Copyright (c) 2005 EMC Corporation; Hewlett-Packard Development
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, INCLUDING BUT NOT
LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.