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.12.1 and 1.4.4.2

version 1.2.12.1, 2006/03/24 18:52:12

version 1.4.4.2, 2006/12/19 10:49:51

Line 1

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

<html>

<html xmlns:v="urn:schemas-microsoft-com:vml"

xmlns:o="urn:schemas-microsoft-com:office:office"

xmlns:w="urn:schemas-microsoft-com:office:word"

xmlns:st1="urn:schemas-microsoft-com:office:smarttags"

xmlns="http://www.w3.org/TR/REC-html40" xmlns:o>

<head>

<!--[if !mso]>

<style>

v\:* {behavior:url(#default#VML);}

o\:* {behavior:url(#default#VML);}

w\:* {behavior:url(#default#VML);}

.shape {behavior:url(#default#VML);}

</style>

<![endif]-->

<title>OpenPegasus SSL Guidelines</title>

<o:SmartTagType namespaceuri="urn:schemas-microsoft-com:office:smarttags"

name="date"/>

<!--[if gte mso 9]><xml>

<o:DocumentProperties>

<o:Author>IBM_USER</o:Author>

<o:LastAuthor>IBM_USER</o:LastAuthor>

<o:Revision>2</o:Revision>

<o:TotalTime>6</o:TotalTime>

<o:Created>2006-12-19T07:20:00Z</o:Created>

<o:LastSaved>2006-12-19T07:26:00Z</o:LastSaved>

<o:Pages>1</o:Pages>

<o:Words>5126</o:Words>

<o:Characters>29220</o:Characters>

<o:Company>IBM</o:Company>

<o:Lines>243</o:Lines>

<o:Paragraphs>68</o:Paragraphs>

<o:CharactersWithSpaces>34278</o:CharactersWithSpaces>

<o:Version>10.3501</o:Version>

</o:DocumentProperties>

</xml><![endif]--><!--[if gte mso 9]><xml>

<w:WordDocument>

<w:SpellingState>Clean</w:SpellingState>

<w:GrammarState>Clean</w:GrammarState>

<w:BrowserLevel>MicrosoftInternetExplorer4</w:BrowserLevel>

</w:WordDocument>

</xml><![endif]--><!--[if !mso]><object

classid="clsid:38481807-CA0E-42D2-BF39-B33AF135CC4D" id=ieooui></object>

<style>

st1\:*{behavior:url(#ieooui) }

</style>

<![endif]-->

<style>

<!--

/* Font Definitions */

@font-face

{font-family:Courier;

panose-1:2 7 4 9 2 2 5 2 4 4;

mso-font-charset:0;

mso-generic-font-family:modern;

mso-font-format:other;

mso-font-pitch:fixed;

mso-font-signature:3 0 0 0 1 0;}

@font-face

{font-family:Wingdings;

panose-1:5 0 0 0 0 0 0 0 0 0;

mso-font-charset:2;

mso-generic-font-family:auto;

mso-font-pitch:variable;

mso-font-signature:0 268435456 0 0 -2147483648 0;}

@font-face

{font-family:Times;

panose-1:2 2 6 3 5 4 5 2 3 4;

mso-font-charset:0;

mso-generic-font-family:roman;

mso-font-pitch:variable;

mso-font-signature:536902279 -2147483648 8 0 511 0;}

/* Style Definitions */

p.MsoNormal, li.MsoNormal, div.MsoNormal

{mso-style-parent:"";

margin:0in;

margin-bottom:.0001pt;

mso-pagination:widow-orphan;

font-size:12.0pt;

font-family:"Times New Roman";

mso-fareast-font-family:"Times New Roman";}

{mso-margin-top-alt:auto;

margin-right:0in;

mso-margin-bottom-alt:auto;

margin-left:0in;

mso-pagination:widow-orphan;

mso-outline-level:2;

font-size:18.0pt;

font-family:"Times New Roman";

font-weight:bold;}

{mso-margin-top-alt:auto;

margin-right:0in;

mso-margin-bottom-alt:auto;

margin-left:0in;

mso-pagination:widow-orphan;

mso-outline-level:3;

font-size:13.5pt;

font-family:"Times New Roman";

font-weight:bold;}

{mso-margin-top-alt:auto;

margin-right:0in;

mso-margin-bottom-alt:auto;

margin-left:0in;

mso-pagination:widow-orphan;

mso-outline-level:4;

font-size:12.0pt;

font-family:"Times New Roman";

font-weight:bold;}

a:link, span.MsoHyperlink

{color:blue;

text-decoration:underline;

text-underline:single;}

a:visited, span.MsoHyperlinkFollowed

{color:blue;

text-decoration:underline;

text-underline:single;}

{mso-margin-top-alt:auto;

margin-right:0in;

mso-margin-bottom-alt:auto;

margin-left:0in;

mso-pagination:widow-orphan;

font-size:12.0pt;

font-family:"Times New Roman";

mso-fareast-font-family:"Times New Roman";}

span.spelle

{mso-style-name:spelle;}

span.SpellE

{mso-style-name:"";

mso-spl-e:yes;}

span.GramE

{mso-style-name:"";

mso-gram-e:yes;}

@page Section1

{size:8.5in 11.0in;

margin:1.0in 1.25in 1.0in 1.25in;

mso-header-margin:.5in;

mso-footer-margin:.5in;

mso-paper-source:0;}

div.Section1

{page:Section1;}

/* List Definitions */

@list l0

{mso-list-id:51972189;

mso-list-template-ids:81668992;}

@list l0:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l1

{mso-list-id:257178838;

mso-list-template-ids:1636469146;}

@list l1:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l2

{mso-list-id:335961387;

mso-list-template-ids:303987346;}

@list l2:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l3

{mso-list-id:432287186;

mso-list-template-ids:401260786;}

@list l3:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l4

{mso-list-id:448670368;

mso-list-template-ids:342922132;}

@list l4:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l5

{mso-list-id:605886313;

mso-list-template-ids:2101529026;}

@list l5:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l6

{mso-list-id:610279438;

mso-list-template-ids:-795200846;}

@list l6:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l7

{mso-list-id:620840603;

mso-list-template-ids:-1801667564;}

@list l7:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l8

{mso-list-id:633027112;

mso-list-template-ids:-1360881254;}

@list l8:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l9

{mso-list-id:902104985;

mso-list-template-ids:750025012;}

@list l9:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l10

{mso-list-id:958562085;

mso-list-template-ids:-55920690;}

@list l10:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l11

{mso-list-id:1106390704;

mso-list-template-ids:-953544102;}

@list l11:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l11:level2

{mso-level-number-format:bullet;

mso-level-text:o;

mso-level-tab-stop:1.0in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:"Courier New";

mso-bidi-font-family:"Times New Roman";}

@list l11:level3

{mso-level-number-format:bullet;

mso-level-text:\F0A7;

mso-level-tab-stop:1.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Wingdings;}

@list l12

{mso-list-id:1409960379;

mso-list-template-ids:-1094543752;}

@list l12:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l13

{mso-list-id:1721326241;

mso-list-template-ids:644010464;}

@list l13:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l14

{mso-list-id:1731073149;

mso-list-template-ids:-2060307636;}

@list l14:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

@list l15

{mso-list-id:1950238906;

mso-list-template-ids:-1705468504;}

@list l15:level1

{mso-level-number-format:bullet;

mso-level-text:\F0B7;

mso-level-tab-stop:.5in;

mso-level-number-position:left;

text-indent:-.25in;

mso-ansi-font-size:10.0pt;

font-family:Symbol;}

{margin-bottom:0in;}

-->

</style>

<!--[if gte mso 10]>

<style>

/* Style Definitions */

table.MsoNormalTable

{mso-style-name:"Table Normal";

mso-tstyle-rowband-size:0;

mso-tstyle-colband-size:0;

mso-style-noshow:yes;

mso-style-parent:"";

mso-padding-alt:0in 5.4pt 0in 5.4pt;

mso-para-margin:0in;

mso-para-margin-bottom:.0001pt;

mso-pagination:widow-orphan;

font-size:10.0pt;

font-family:"Times New Roman";}

</style>

<![endif]-->

</head>

<body>

<h2>OpenPegasus 2.5.1 SSL Guidelines</h2>

Version: 1.1

Created: July 20, 2005

Updated: March 20, 2006

<ul>

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

<h2>OpenPegasus 2.6 SSL Guidelines</h2>

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

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

Version: 1.2

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

Created: <st1:date Year="2005" Day="20" Month="7">July 20, 2005</st1:date>

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

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

Updated: <st1:date Year="2006" Day="19"

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

Month="12">December 19, 2006</st1:date>

<li><a href="#CLI">ssltrustmgr 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 class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#OVERVIEW">Overview</a>

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

</li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#RELATED">Related

Information</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#BUILDING">Building

Pegasus with SSL</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#CERTS">Creating SSL

Certificates</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#CONFIGURE">Configuring

Pegasus for SSL</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#DESIGN">SSL Design

Question List</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#TRUSTSTORE"><span

class=SpellE>Truststore Management</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#CLI"><span

class=SpellE>cimtrust & cimcrl CLI</a>

</li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#CLIENT">Configuring

the Pegasus CIM Client for SSL</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#AUTH">SSL

Authorization</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#EXT">Critical

Extension Handling</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l7 level1 lfo1;tab-stops:list .5in'><a href="#RESOURCES">Resources</a>

</li>

</ul>

<h3><a name="OVERVIEW">Overview</a></h3>

<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

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

certificate-based

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 and

This guide requires a basic understanding of SSL, OpenSSL,

and basic authentication. This guide is intended to help developers and

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

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

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

education on SSL. If you are not familiar with these technologies,

on SSL. If you are not familiar with these technologies,

consult the sources in the <a href="#RESOURCES">Resources</a> section

consult the sources in the <a href="#RESOURCES">Resources</a> section at the

at the bottom.

bottom.

Note: In this document, the term "trust" refers only to

authentication. It does not imply full trust in the traditional sense, because

authentication. It does not imply full trust in the traditional sense,

it does not take into account authorization checks. It remains the

because it does not take into account authorization checks. It remains

responsibility of providers and clients to perform authorization, and therefore

the responsibility of providers and clients to perform authorization,

establish real trust. Likewise, the term "Trust Store" can be

and therefore establish real trust. Likewise, the term "Trust Store"

misleading since the "store" is only a source of authentication

can be misleading since the "store" is only a source of authentication

credentials. Please bear this in mind when documenting recommended deployments

credentials. Please bear this in mind when documenting recommended

or building clients or providers.

deployments or building clients or providers.

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

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

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

A significant portion of the information in this document is

various PEP's. This document attempts to bring all of this information

taken from various PEP's.

together in a cohesive and simplified format.

This document attempts to bring all of this information together in a cohesive

and simplified format.

<ul>

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

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l15 level1 lfo2;tab-stops:list .5in'>PEP#035 - Add support for

/dev/random in SSLContext </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l15 level1 lfo2;tab-stops:list .5in'>PEP#060 - SSL support in

CIM/XML indication delivery </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l15 level1 lfo2;tab-stops:list .5in'>PEP#074 - <span

class=SpellE>SSLContext and Certificate verification interface

enhancement</li>

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

Server for CIMExport requests</li>

mso-list:l15 level1 lfo2;tab-stops:list .5in'>PEP#165 - SSL Client

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

Verification </li>

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l15 level1 lfo2;tab-stops:list .5in'>PEP#187 - SSL Certificate

Options for Selected Platforms</li>

Management Enhancements </li>

</ul>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l15 level1 lfo2;tab-stops:list .5in'>PEP#200 - Recommended <span

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

class=SpellE>OpenPegasus 2.5 Build and Configuration Options for

To build Pegasus with HTTPS support, you will need to build against

Selected Platforms</li>

the <a href="http://www.openssl.org">OpenSSL package</a>. <font

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

style="color: rgb(0, 0, 0);" color="MAGENTA">The SSL support outlined

mso-list:l15 level1 lfo2;tab-stops:list .5in'>PEP#268 � SSL Client Certificate

here has been tested against recent releases of the major versions

Propagation</li>

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

</ul>

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

Pegasus utilizes (for example, certificate-based authentication is not

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

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

officially support major version 0.9.6.

To build Pegasus with HTTPS support, you will need to build against the <a

See Bugzilla 4048 for more information.

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

Because this is an open source project, the SSL support has been tested

style='color:black'>The SSL support outlined here has been tested against

with many versions of OpenSSL, but we cannot guarantee it has been

recent releases of the major versions 0.9.7X and 0.9.8X (most notably, 0.9.7d).

tested with every version on every platform. A list of recent OpenSSL

Because some versions of 0.9.6X do not contain full support for the security

releases, and important-to-review security advisories and fixes, can

functions that Pegasus utilizes (for example, certificate-based authentication

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

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

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

support has been tested with many versions of OpenSSL,

following environment variables before building Pegasus:

but we cannot guarantee it has been tested with every version on every

platform. A list of recent OpenSSL releases, and

<ul>

important-to-review security advisories and fixes, can be found on the <a

<li>PEGASUS_HAS_SSL=1</li>

href="http://www.openssl.org/news">OpenSSL News page</a>.

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

After grabbing the OpenSSL source <span

<li>OPENSSL_BIN=<location of the binary package> This only

class=SpellE>tarball, you need to set the following environment

needs to be set if the OpenSSL binaries are not in $(OPENSSL_HOME)/bin.</li>

variables before building Pegasus:

</ul>

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

support SSLv2. To turn on SSLv2 support, enable the additional

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

environment variable:

mso-list:l14 level1 lfo3;tab-stops:list .5in'>PEGASUS_HAS_SSL=1 </li>

<ul>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

<li> PEGASUS_ENABLE_SSLV2=1 </li>

mso-list:l14 level1 lfo3;tab-stops:list .5in'>OPENSSL_HOME=<location of

</ul>

the SDK package> This directory must contain

the OpenSSL include directory,

It is not recommended to enable this protocol, as there have been many

$(OPENSSL_HOME)/include, and the OpenSSL library

security weaknesses associated with it. Unless you are dealing

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

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l14 level1 lfo3;tab-stops:list .5in'>OPENSSL_BIN=<location of

After setting these variables, proceed as normal with the build

the binary package> This only needs to be set

instructions in the readme file.

if the OpenSSL binaries are not in

$(OPENSSL_HOME)/bin.</li>

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

</ul>

There are two options for creating the CIMOM's certificate:

<ul>

Note that Pegasus supports SSLv3 and TLSv1 by default. It

<li>Self-signed certificate</li>

does NOT support SSLv2. To turn on SSLv2 support, enable the additional

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

environment variable:

</ul>

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l9 level1 lfo4;tab-stops:list .5in'>PEGASUS_ENABLE_SSLV2=1 </li>

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

It is not recommended to enable this protocol, as there have been many

Pegasus, ssl.cnf in the root directory, or generate your own. For a

security weaknesses associated with it. Unless you are dealing with very

self-signed certificate, the subject

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

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

After setting these variables, proceed as normal with the build instructions

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

in the readme file.

need an OpenSSL configuration

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

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

package.

There are two options for creating the CIMOM's

<ul>

certificate:

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

openssl genrsa -out

myserver.key 1024

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l5 level1 lfo5;tab-stops:list .5in'>Self-signed certificate </li>

file. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l5 level1 lfo5;tab-stops:list .5in'>Certificate issued by a

openssl req -config

third-party certificate authority</li>

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

</ul>

</li>

<li> At this point, the certificate signing request can be sent out

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

to a third-party certificate authority for signing, or a self-signed

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

certificate can be generated. To generate a self-signed certificate,

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

execute the following:

Distinguished Name (DN). You can use the one that comes with Pegasus, <span

openssl x509 -in myserver.csr

class=SpellE>ssl.cnf in the root directory, or generate your own. For a

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

self-signed certificate, the subject is the same as the issuer. Execute the

Set the "sslCertificateFilePath" configuration property to point to

following commands to create a self-signed certificate. The PEGASUS_ROOT and

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

PEGASUS_HOME have to be set to your respective installation and source

certificate is created.

directory. You will also need an OpenSSL

configuration file. There is a sample configuration file that comes with the <span

class=SpellE>OpenSSL package.

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l12 level1 lfo6;tab-stops:list .5in'>To generate a private key,

execute the following:

openssl<span

style='font-family:Courier;color:#009900'> genrsa

-out myserver.key 1024

Set the "sslKeyFilePath" configuration

property to point to this key file. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l12 level1 lfo6;tab-stops:list .5in'>To generate a certificate

signing request, execute the following:

openssl<span

style='font-family:Courier;color:#009900'> req -<span

class=SpellE>config openssl.cnf -new -key

myserver.key -out myserver.csr

</li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l12 level1 lfo6;tab-stops:list .5in'>At this point, the

certificate signing 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<span

class=GramE>:

openssl<span

style='font-family:Courier;color:#009900'> x509 -in myserver.csr

-out myserver.cert -req

-signkey myserver.key

-days 365

Set the "sslCertificateFilePath"

configuration property to point to this certificate file. The above CSR

file can be discarded after the certificate is created. </li>

</ul>

After creating the keypair, make sure you protect the information

After creating the keypair, make sure you protect

sufficiently by changing permissions on the files and/or directories.

the information sufficiently by changing permissions on the files and/or

The following table shows the recommended privileges:

directories. The following table shows the recommended privileges:

<table class=MsoNormalTable border=1 cellspacing=1 cellpadding=0 width="30%"

style='width:30.0%;mso-cellspacing:.7pt'>

<tbody>

<tr>

SSL file<o:p></o:p>

<th>Pegasus Config property</th>

</td>

<th>Permissions</th>

Pegasus <span

class=SpellE>Config property<o:p></o:p>

</td>

Permissions<o:p></o:p>

</td>

</tr>

<tr>

<td>Private key</td>

<td>sslKeyFilePath</td>

Private key

</td>

sslKeyFilePath

</td>

rwx------

</td>

</tr>

<tr>

<td>Public certificate</td>

<td>sslCertificateFilePath</td>

Public certificate

</td>

sslCertificateFilePath

</td>

rwxr-xr-x

</td>

</tr>

<tr>

<td>Truststore</td>

<td>sslTrustStore, exportSSLTruststore</td>

Truststore

</td>

sslTrustStore

</td>

rwxr-xr-x

</td>

</tr>

<tr>

<td>CRL store </td>

<td>crlStore</td>

CRL store

</td>

crlStore

</td>

rwxr-xr-x

</td>

</tr>

</tbody>

</table>

The administrator is responsible for ensuring that the above file

permissions are set correctly. The administrator should also ensure

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

that all containing directories all the way up to the base directory

containing directories all the way up to the base directory are not

are not world-writable. Pegasus only checks the following conditions

world-writable. Pegasus only checks the following conditions when starting up:

when starting up:

<ul>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

<li>The sslKeyFilePath and the sslCertificateFilePath are readable by

mso-list:l1 level1 lfo7;tab-stops:list .5in'>The sslKeyFilePath

and the sslCertificateFilePath are readable by

the CIMOM.</li>

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l1 level1 lfo7;tab-stops:list .5in'>The sslTrustStore

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

and crlStore are readable by the CIMOM if they

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

are a single file. </li>

</ul>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l1 level1 lfo7;tab-stops:list .5in'>The sslTrustStore

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

and crlStore are readable and writable by the

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

CIMOM if they are a directory.</li>

</ul>

For more information on generating keys and certificates, consult

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

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

documentation</a>.

key, public key, truststore, and crl

<h3><a name="CONFIGURE">Configuring Pegasus for SSL</a></h3>

store as well.

There are many environment variable settings associated with SSL. Here

is a brief discussion of the subtleties of these options and how they

For more information on generating keys and certificates, consult the <a

work together to

href="http://www.openssl.org/docs/HOWTO/">OpenSSL

create a more secure environment. More information on the default and

HOW-TO documentation</a>.

recommended settings can be found in PEP#200 Recommended OpenPegasus

2.5 Build and Configuration Options for Selected Platforms.

<h3><a name=CONFIGURE>Configuring Pegasus for SSL</a></h3>

Additionally, the section on <a href="#DESIGN">Design Question List</a>

should help determine what these settings should be for a given

There are many environment variable settings associated with

application.

SSL. Here is a brief discussion of the subtleties of these options and how they

enableHttpsConnection

work together to create a more secure environment. More information on the

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

default and recommended settings can be found in PEP#200 Recommended <span

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

class=SpellE>OpenPegasus 2.5 Build and Configuration Options for

are sending cleartext passwords over the wire, it is imperative that

Selected Platforms. Additionally, the section on <a href="#DESIGN">Design

you only use the secure port. For added security, the HTTP port can be

Question List</a> should help determine what these settings should be for a

disabled to prevent clients from connecting to it. The HTTPS connection

given application.

is enabled by default only on the following platforms:

enableHttpsConnection

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

<ul>

remote communication be done over the HTTPS port. However, if you are sending <span

<li>LINUX</li>

class=SpellE>cleartext passwords over the wire, it is imperative that

you only use the secure port. For added security, the HTTP port can be disabled

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

to prevent clients from connecting to it. The HTTPS connection is enabled by

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

default only on the following platforms:

</ul>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

httpsPort

mso-list:l6 level1 lfo8;tab-stops:list .5in'>LINUX </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l6 level1 lfo8;tab-stops:list .5in'>OS-400 </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l6 level1 lfo8;tab-stops:list .5in'>HP_UX (if

PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true) </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l6 level1 lfo8;tab-stops:list .5in'>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

sslCertificateFilePath

may be a chain in which case the file should contain PEM encoded

certificates beginning with the server certificate and followed by each

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

signing certificate authority (CA) including the root CA. If the server

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

certificate is a self signed certificate, the file only contains the

beginning with the server certificate and followed by each signing certificate

self-signed certificate in PEM format.

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

The certificate cannot be encrypted because there is currently no

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

mechanism for decrypting the certificate using a user-supplied

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

password. This property must be defined if enableHttpsConnection is

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

true. Any failure in finding this file will result in the cimserver

property must be defined if enableHttpsConnection is

failing to start. See <a href="#CERTS">Creating SSL Certificates</a>

true. Any failure in finding this file will result in the cimserver

for more information.

failing to start. See <a href="#CERTS">Creating SSL Certificates</a> for more

information.

sslKeyFilePath

This is the path to the server's private key. All keys should be at

sslKeyFilePath

least 1024 bytes long. This property must be defined if

This is the path to the server's private key. All keys should be at least 1024

enableHttpsConnection is true. Any failure in finding this file will

bytes long. This property must be defined if enableHttpsConnection

result in the cimserver failing to start. See <a href="#CERTS">Creating

is true. Any failure in finding this file will result in the <span

SSL Certificate</a> for more information.

class=SpellE>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

sslClientVerificationMode

configured. It does not control the configuration of the export

This setting controls how the cimserver (i.e. the

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

HTTPS port) is configured. There are three possible settings: disabled,

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

required, optional. There is no "right" setting for this property.

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

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

going to use basic authentication to authenticate all client requests.

are going to use basic authentication to authenticate all client requests. In

In many applications where a physical person is there to supply a

many applications where a physical person is there to supply a username and

username and password, basic authentication is sufficient. Other

password, basic authentication is sufficient. Other environments may be

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

heterogeneous, in which case it makes sense to allow both basic authentication

allow both basic authentication and SSL certificate verification. The

and SSL certificate verification. The setting of this variable also impacts

setting of this variable also impacts what happens during the OpenSSL

what happens during the OpenSSL handshake:

handshake:

<ul>

<li>"required" -- The server requires that the client

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

certificate be trusted in order for the handshake to continue. If the

mso-list:l4 level1 lfo9;tab-stops:list .5in'>"required"

client fails to send a certificate or sends an untrusted certificate,

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

the handshake is immediately terminated.</li>

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

<li>"optional" -- The server will request that a client

sends an untrusted certificate, the handshake is

certificate be sent, but will continue the handshake even if no

immediately terminated. </li>

certificate is received. If authentication is enabled, the server will

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

seek to authenticate the client via an alternative method of

mso-list:l4 level1 lfo9;tab-stops:list .5in'>"optional"

authentication. As

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

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

continue the handshake even if no certificate is received. If

handshake will fail. Before 2.5.1,the handshake would have

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

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

via an alternative method of authentication. As

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

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

certificate. This is the default.</li>

will fail. Before 2.5.1,the handshake would

</ul>

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

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l4 level1 lfo9;tab-stops:list .5in'>"disabled"

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

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

authenticated via basic authentication. The providers

default.</li>

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

</ul>

Authorization section

for more information.

Pegasus currently ties a certificate to a valid OS user.

sslTrustStore

Multiple certificates may be registered to the same user. When a certificate is

This setting controls the truststore for the cimserver's HTTPS

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

connection. It can be

via basic authentication. The providers receive the username that the

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

certificate was mapped to. See the SSL Authorization section for more

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

information.

truststore as there are strict naming requirements for trusted

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

sslTrustStore

section for further information.

This setting controls the truststore for the <span

class=SpellE>cimserver's HTTPS connection. It can be either a directory

sslTrustStoreUserName

or a single root CA file. When set to a directory, it is recommended that you

This setting is only utilized if the sslTrustStore is a single CA file.

use the cimtrust CLI to populate the <span

It is not used if the sslTrustStore setting is a directory, but it

class=SpellE>truststore as there are strict naming requirements for

still must be set to a valid system user. This is because the

trusted certificate files. See the <a href="#CLI">cimtrust

validation of the property is done independently of the sslTrustStore

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

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

sslTrustStoreUserName

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

This setting is only utilized if the sslTrustStore is

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

a single CA file. It is not used if the sslTrustStore

recommended that each certificate be registered individually using the

setting is a directory, but it still must be set to a valid system user. This

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

is because the validation of the property is done independently of the <span

crlStore

class=SpellE>sslTrustStore setting. This property represents the valid

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

OS user that corresponds to the root certificate. All requests authenticated

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

with a certificate under the root CA will be associated with this user and the

truststores are supported (cimserver and export) and these both share

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

the same CRL store. It is important to note that certificates are

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

checked first against the CRL (if specified) and then against the

recommended that each certificate be registered individually using the <a

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

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

CRL management.

enableSSLExportClientVerification

crlStore

This setting controls whether an ADDITIONAL port is used to listen for

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

incoming indications. This port is used only as a CIM indication

to note that certificates are checked first against the CRL (if specified) and

listener

then against the server truststore. The <a href="#CLI"><span

and only supports HTTPS. The port number of the export connection is

class=SpellE>cimcrl CLI</a> should be used for CRL management.

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>

The following are configuration limitations:

<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

password needed to unencrypt it. Therefore, the best way to secure the

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

file is to follow the file permissions settings specified in <a

mso-list:l2 level1 lfo10;tab-stops:list .5in'>The x509 server certificate

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

file cannot be encrypted. The reason for this is that there is currently

<li>There is no property to specify supported cipher lists at this

no mechanism in Pegasus to grab the password needed to unencrypt

time. Pegasus uses the default OpenSSL cipher list. The cipher lists

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

can be found at <a

permissions settings specified in <a href="#CERTS">Creating SSL

Certificates.</a> </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l2 level1 lfo10;tab-stops:list .5in'>There is no property to

specify supported cipher lists at this time. Pegasus uses the default <span

class=SpellE>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>

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>The verification depth cannot be specified. Pegasus uses the

</li>

default OpenSSL depth of 9. This means the OpenSSL will only accept

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l2 level1 lfo10;tab-stops:list .5in'>The verification depth

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

cannot be specified. Pegasus uses the default OpenSSL

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

depth of 9. This means the OpenSSL will only

</ul>

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

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

The following questions may be helpful in determining how to

mso-list:l2 level1 lfo10;tab-stops:list .5in'>No hostname checking is

configure Pegasus CIM Server.

performed to ensure that the subject field of the distinguished name (DN)

Should I enable the HTTPS port?

matches the hostname.</li>

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

</ul>

port can be disabled for additional security if desired.

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

Should I enable the export port?

Currently, the export connection provides the only way to authenticate

The following questions may be helpful in determining how to configure

incoming CIM indication requests. Because basic authentication cannot

Pegasus CIM Server.

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

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

Should I enable the HTTPS port?

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

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

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

be disabled for additional security if desired.

validated.

Should I configure the CIMOM to use a truststore?

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

Should I configure the CIMOM to use a truststore?

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

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

a truststore may not be needed. If an application

are using basic authentication over the secure port

does not want to store user/pw information, then it

(and the passwords are secured), then a truststore may not be needed.

is a good idea to use a certificate-based infrastructure. If a CIMOM

If an application does not want to store user/pw information,

certificate is compromised, the cimserver and the

then it is a good idea to use a certificate-based infrastructure. If a

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

CIMOM certificate is compromised, the cimserver and the providers

dependent on the resources the providers have access to. If an OS password is

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

compromised, the entire system may be compromised. If using peer verification,

dependent on the resources the providers have access to. If an OS

it is important to ensure that 1) the cimserver is

password is compromised, the entire system may be compromised.

properly configured to use a truststore, 2) the <span

If using peer verification, it is important to ensure that 1) the

class=SpellE>truststore is loaded properly and protected, and 3)

cimserver is properly configured to use a truststore,

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

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

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

authorization checks are performed after a certificate is verified.

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

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

certificate authority?

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

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

third-party certificate authority?

certificate or one issued by Verisign or another

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

third-party certificate authority. If an administrator administrates their

self-signed certificate or one issued by Verisign

self-signed certificates correctly, they are no less secure than one issued by

or another third-party certificate authority.

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

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

"vouch" for certs it has signed, in large

deployments the incremental cost might never outweigh the initial

deployments. In small deployments the incremental cost might never outweigh the

CA-setup cost.

initial CA-setup cost.

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

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

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

for multiple CIMOMs. If using a self-signed

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

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

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

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

certificates is compromised, the other ones remain secure.

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

Should the truststore be a single root CA file or

If you only anticipate connections from a narrowly defined set of

a directory?

clients, then a single root CA certificate file should be sufficient.

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

Alternatively, multiple trusted certificates may be stored in PEM

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

format inside of a single CA file.

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

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

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

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

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

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

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

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

with the additional step of using cimtrust to

to register it.

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

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

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

principle of

privileged user if lesser privileged users will be connecting with it.

least privilege, it is not a good idea to register a root CA to a

How do I protect the keystore and the <span

privileged user if lesser privileged users will be connecting with it.

class=SpellE>truststore?

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

How do I protect the keystore and the truststore?

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

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

certificate can be viewed by anyone, however, it

a reason. Only the system administrator should be able to see it. The

should be protected from alteration by system users. Similarly, any <span

public certificate can be viewed by anyone, however, it should be

class=SpellE>truststore or CRL file or directory should also be

protected from alteration by system users. Similarly, any truststore or

protected from alteration. See <a href="#CERTS">Creating SSL Certificates</a>

CRL file or directory should also be protected from alteration. See <a

for the recommended file privileges.

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

Certificate Revocation Lists are regularly issued by CA's. They contain a list

a list of certificates that have been revoked. Any application using a

of certificates that have been revoked. Any application using a CA certificate

CA certificate in its truststore should also implement CRLs (if the CA

in its truststore should also implement <span

supports them). Pegasus itself

class=SpellE>CRLs (if the CA supports them). Pegasus itself does not

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

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

responsibility of the administrator

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

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

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

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

CRLs<span

CRLs are not checked

style='color:black'> are not checked for expiration during the SSL callback.

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

This means that if a CRL for a particular issuer has expired, Pegasus still

particular issuer has expired,

accepts certificates from the issuer and uses the expired CRL as the latest.

Pegasus still accepts certificates from the issuer and uses the expired

Again, it is the responsibility of the administrator to ensure the CRL is up to

CRL as the latest. Again, it is the responsibility of the administrator

date. CRLs are not checked for critical extensions

to ensure the CRL is up to date. CRLs are not checked for critical

during CRL verification. If a CRL contains a critical extension it will be

extensions during CRL verification. If a CRL contains a critical

ignored.

extension it will be ignored.

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

(You can create a self-signed CRL but it is not really necessary). Because of

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

this, the certificate deletion option available via cimtrust

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

is primarily intended for self-signed certificates. Technically, <span

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

class=SpellE>CRL's are the correct way to revoke compromised or invalid

via ssltrustmgr is primarily intended for self-signed certificates.

certificates.

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

certificates.

What is the order of operations for certificate verification?

The certificate is checked against any CRLs first before going through

The certificate is checked against any CRLs first

the rest of the verification process. Verification starts with the

before going through the rest of the verification process. Verification starts

root certificate and continues down to the peer certificate. If

with the root certificate and continues down to the peer certificate. If

verification fails at any of these points, the certificate is

verification fails at any of these points, the certificate is considered <span

considered

class=SpellE>untrusted and the verification process reports an error.

untrusted and the verification process reports an error.

<h3><a name="TRUSTSTORE">Truststore Management</a></h3>

<h3><a name=TRUSTSTORE></a>Truststore<span

There are two directions of trust in an SSL client-server handshake:

style='mso-bookmark:TRUSTSTORE'> Management</h3>

The client trusts the server. The server trusts the client. Pegasus

provides a way to implement one or both of these relationships.

There are two directions of trust in an SSL client-server

Ideally, an application should support both levels of trust for maximum

handshake: The client trusts the server. The server trusts the client. Pegasus

security and this is the implementation Pegasus recommends. However, in

provides a way to implement one or both of these relationships. Ideally, an

some scenarios it may make sense to only implement one of these; in

application should support both levels of trust for maximum security and this

that case, it is possible to override the client or the server to

is the implementation Pegasus recommends. However, in some scenarios it may

"trust all certificates." For example, if all clients will be using

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

basic authentication over HTTPS, then the server can be setup to "trust

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

all client certificates."

all clients will be using basic authentication over HTTPS, then the server can

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

be setup to "trust all client certificates."

simply set the sslClientVerification<font style="color: rgb(0, 0, 0);"

color="MAGENTA">Mode property to "required."

To tell the cimserver to require that all clients

To tell the cimserver to trust all clients, set the

be trusted, simply set the sslClientVerification<span

sslClientVerificationMode

style='color:black'>Mode property to "required."

property to "disabled" or "optional".

To tell the cimserver to trust all clients, set the <span

class=SpellE>sslClientVerificationMode

The SSL verification in Pegasus is independent of any other

property to "disabled" or "optional".

authentication mechanism. It can still be utilized when authentication

is disabled.

The SSL verification in Pegasus is independent of any other authentication

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

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

verification.

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

In situations where a client is not authenticated by SSL because the

verification. In situations where a client is not

client sent no certificate and the setting is "optional", the server

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

will attempt to authenticate the client via another method of

"optional", the server will attempt to authenticate the client via

authentication . In this case, the authentication mechanism specified

another method of authentication . In this case, the

by the configuration property "httpAuthType" will be used for remote

authentication mechanism specified by the configuration property "<span

connections and local authentication will be used for local

class=SpellE>httpAuthType" will be used for remote connections and

connections.

local authentication will be used for local connections. In situations where a

In situations where a client is not authenticated by SSL because the

client is not authenticated by SSL because the client certificate was invalid,

client certificate was invalid, the handshake will be terminated.

the handshake will be terminated.

Note: Before 2.5.1, in the latter case, authentication would have

Note: Before 2.5.1, in the latter case, authentication would have proceeded

proceeded in the same way as if the client had sent no certificate. To

in the same way as if the client had sent no certificate. To enable the legacy

enable the legacy behavior, the compile-time flag

behavior, the compile-time flag PEGASUS_OVERRIDE_SSL_CERT_VERIFICATION_RESULT

PEGASUS_OVERRIDE_SSL_CERT_VERIFICATION_RESULT should be defined.

should be defined.

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

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

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

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

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

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

store.

The CLI interfaces with a certificate control provider that runs as

part of Pegasus's core. It operates on the PG_SSLCertificate and

PG_SSLCertificateRevocationList

classes in root/pg_internal.

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

configuration for several reasons:

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

<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

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,

or more correctly the provider it operates 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

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

ssltrustmgr manpage provides 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

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,

<h3><a name=CLI></a><span

NULL, randomFile), username password);

style='mso-bookmark:CLI'>cimtrust<span style='mso-bookmark:

</ul>

CLI'> & cimcrl CLI</h3>

<ul>

cimtrust

<li>trustStore -- This specifies the truststore that the

CLI may be used to add, remove or list X509 certificates in a PEM format <span

client uses to verify server certificates. It can be String::EMPTY if

class=SpellE>truststore. cimcrl

no truststore exists. </li>

CLI may be used to add, remove or list X509 Certificate Revocation Lists in a

<li>certPath -- This specifies the x509 certificate of the

PEM format CRL store. The CLIs interface with a

client that will be sent during an SSL handshake. Note that this

Certificate control provider that runs as part of Pegasus's core. It operates

certificate will only be sent if the server requests it. If this option

on the PG_SSLCertificate and PG_SSLCertificateRevocationList

is specified, the keyPath parameter must also be specified.</li>

classes in root/PG_Internal. It is recommended that

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

the CLIs be used in place of manual configuration for

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

several reasons:

specified.</li>

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

client checks the CRL list first, before attempting any further

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

authentication, including the user-specified callback.</li>

mso-list:l13 level1 lfo11;tab-stops:list .5in'>OpenSSL

<li>verifyCert -- This is a user-specified verification

places strict naming restrictions on certificates and CRLs

callback. If this is set to null, the default OpenSSL verification

in a directory (the files are looked up via a subject hash code) </li>

callback will be executed. You can implement this method to "trust all

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

servers" or to perform additional authentication checks that OpenSSL

mso-list:l13 level1 lfo11;tab-stops:list .5in'>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:fuchsia'> <span

style='color:black'>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 class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l13 level1 lfo11;tab-stops:list .5in'>The

CLIs, or more correctly the provider they

operate on, supports dynamic deletion of certificates by resetting the <span

class=SpellE>cimserver's SSL context.<span style='color:

fuchsia'> Normally, you would need to stop and start the <span

class=SpellE>cimserver to accomplish this. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l13 level1 lfo11;tab-stops:list .5in'>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 <span

class=SpellE>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 <span

class=SpellE>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 <span

class=SpellE>SSLContext constructor parameters.

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

<span

class=GramE>client.connect<span

class=GramE>(<span

style='font-family:Courier'> hostname, port, SSLContext(<span

class=SpellE>trustStore, certPath, <span

class=SpellE>keyPath, verifyCert, <span

class=SpellE>randomFile), username, password);

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

class=SpellE>truststore.

<span

class=GramE>client.connect<span

class=GramE>(<span

style='font-family:Courier'> hostname, port, SSLContext(<span

class=SpellE>trustStore, NULL, randomFile),

username password);

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l3 level1 lfo14;tab-stops:list .5in'><span

class=GramE>trustStore -- This specifies the <span

class=SpellE>truststore that the client uses to verify server

certificates. It can be String::EMPTY if no <span

class=SpellE>truststore exists. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l3 level1 lfo14;tab-stops:list .5in'><span

class=GramE>certPath -- This specifies the x509

certificate of the client that will be sent during an SSL handshake. Note

that this certificate will only be sent if the server requests it. If this

option is specified, the keyPath parameter must

also be specified. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l3 level1 lfo14;tab-stops:list .5in'><span

class=GramE>keyPath -- This specifies the private key

of the client. If this option is specified, the certPath

parameter must also be specified. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l3 level1 lfo14;tab-stops:list .5in'><span

class=GramE>crlPath -- This specifies an optional CRL

store path. The client checks the CRL list first, before attempting any

further authentication, including the user-specified callback. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l3 level1 lfo14;tab-stops:list .5in'><span

class=GramE>verifyCert -- This is a user-specified

verification callback. If this is set to null, the default <span

class=SpellE>OpenSSL verification callback will be executed. You

can implement this method to "trust all servers" or to perform

additional authentication checks that OpenSSL

does not perform by default.</li>

<li>randomFile -- A file to seed the pseudo random number

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

generator (PRNG).</li>

mso-list:l3 level1 lfo14;tab-stops:list .5in'><span

class=GramE>randomFile -- A file to seed the pseudo

random number generator (PRNG).</li>

</ul>

Here are some general guidelines on implementing peer verification

for the client:

Here are some general guidelines on implementing peer verification for the

client:

<ul>

<li>The client should enable peer verification by specifying a

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should enable

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

peer verification by specifying a truststore and

trusted CA certificates. The ssltrustmgr CLI cannot be used to

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

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

placed in a protected file or directory specified by the trustStore

mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should employ a <span

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

class=SpellE>truststore in order to properly verify the server. The

reloaded to pick up any truststore changes.</li>

truststore should contain a file or directory of

<li>The client could also use a user-specified callback in addition

trusted CA certificates. The cimtrust CLI cannot

to the default verification callback, if additional verifications are

be used to configure client truststores. The

desired over the normal checks that OpenSSL performs. In most cases,

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

the default verification callback is sufficient for checking server

specified by the trustStore parameter. Keep in

certificates.</li>

mind that the SSL context generally has to be reloaded to pick up any <span

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

class=SpellE>truststore changes. </li>

<li>The client should use a CRL store if the truststore contains CA

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

certificates that support one.</li>

mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client could also use a

<li>The client should only use the SSLv3 and TLSv1 protocols. By

user-specified callback in addition to the default verification callback,

default, Pegasus is not built with SSLv2 support.</li>

if additional verifications are desired over the normal checks that <span

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

class=SpellE>OpenSSL performs. In most cases, the default

<ul>

verification callback is sufficient for checking server certificates. </li>

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

<ul>

mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should ensure

<li>WARNING:  In some implementations of SSL a NULL server

that adequate entropy is attained. </li>

certificate is perfectly valid and authenticates against all trust

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

stores.  If the client does not ensure a certificate exists then

mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should use a CRL

the client is not providing server authentication and could have a

store if the truststore contains CA certificates

security bulletin class defect.</li>

that support one. </li>

</ul>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

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

mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should only use

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

the SSLv3 and TLSv1 protocols. By default, Pegasus is not built with SSLv2

<ul>

support. </li>

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

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

subject matches the host name of the server.  For X509v3

mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should perform

certificates, the “SubjectAltName” fields

post-connection checks. </li>

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

the certificate. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:

<li>WARNING:  If the client does not ensure the host name of

auto;mso-list:l11 level2 lfo15;tab-stops:list 1.0in'>Ensure a certificate

the server is the same as one of the host names explicitly described in

was received. </li>

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

identity.  Any other server which was issued a certificate from

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:

the same trusted CA can masquerade as the server unless the client

auto;mso-list:l11 level3 lfo15;tab-stops:list 1.5in'>WARNING:  In

performs the host name check.</li>

some implementations of SSL a NULL server certificate is perfectly valid

</ul>

and authenticates against all trust stores.  If the client does not

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

ensure a certificate exists then the client is not providing server

errors.</li>

authentication and could have a security bulletin class defect.</li>

</ul>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:

auto;mso-list:l11 level2 lfo15;tab-stops:list 1.0in'>Validate that the

Because only the above arguments can be passed into the Pegasus

certificate received was issued to the host for which the client was attempting

SSLContext, there are some limitations in the client configuration:

to connect. </li>

<ul>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:

<li>The verification depth cannot be specified. Pegasus uses the

auto;mso-list:l11 level3 lfo15;tab-stops:list 1.5in'>Ensure that the

default OpenSSL depth of 9.</li>

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

<li>The cipher list cannot be specified. Pegasus uses the default

name of the server.  For X509v3 certificates, the �<span

OpenSSL cipher list. The cipher lists can be found at <a

class=SpellE>SubjectAltName� fields in

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

certificate. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:

auto;mso-list:l11 level3 lfo15;tab-stops:list 1.5in'>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 class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:

auto;mso-list:l11 level2 lfo15;tab-stops:list 1.0in'>Ensure that

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

</ul>

Because only the above arguments can be passed into the Pegasus <span

class=SpellE>SSLContext, there are some limitations in the client

configuration:

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l10 level1 lfo16;tab-stops:list .5in'>The verification depth

cannot be specified. Pegasus uses the default OpenSSL

depth of 9. </li>

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

mso-list:l10 level1 lfo16;tab-stops:list .5in'>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>

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>No hostname checking is performed to ensure that the subject

</li>

field of the distinguished name (DN) matches the hostname. If desired,

<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;

a user-specified callback should be configured to perform this check or

mso-list:l10 level1 lfo16;tab-stops:list .5in'>No hostname checking is

any additional checks relevant to the application.</li>

performed to ensure that the subject field of the distinguished name (DN)

</ul>

matches the hostname. If desired, a user-specified callback should be

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

configured to perform this check or any additional checks relevant to the

The following paragraphs concern authorization of users

application.</li>

authenticated by certificate on the cimserver's HTTPS port.

</ul>

It is important to note that SSL certificates are verified during

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

the initial handshake, BEFORE any further authentication takes place.

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

The following paragraphs concern authorization of users authenticated by

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

certificate on the cimserver's HTTPS port.

sslClientVerification property is set to "required" and no certificate

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

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

terminate the connection if an untrusted certificate is presented. Once

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

a certificate is verified, no further authentication is

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

attempted. This effectively results in any basic or local

connection exception. This scenario will occur if the sslClientVerification

authentication headers being ignored.

property is set to "required" and no certificate or an <span

Further authorization checks must be performed when

class=SpellE>untrusted certificate is sent.

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

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

Further authorization checks must be performed when validating

user and a valid cimuser (if the cimuser function has been configured).

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

In the case of

to the certificate is validated as a valid system user and a valid <span

a certificate chain, the username authorization starts with the leaf

class=SpellE>cimuser (if the cimuser function

certificate. If it successfully finds a mapping

has been configured). In the case of a certificate

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

chain, the username authorization starts with the leaf certificate. If it

leaf certificate, the validation proceeds up to the root certificate.

successfully finds a mapping for the leaf certificate, it continues; if there

If the root certificate is reached and there is still no mapped

is no username for the leaf certificate, the validation proceeds up to the root

username, the authorization fails.

certificate. If the root certificate is reached and there is still no mapped

Additionally, if Pegasus was configured to use PAM, the

username, the authorization fails. Additionally,

pam_acct_mgmt function will be called with the user that is mapped to

if Pegasus was configured to use PAM, the pam_acct_mgmt

the certificate. This ensures that any login conditions that would have

function will be called with the user that is mapped to the certificate. This

been placed on a user authenticated via basic authentication are still

ensures that any login conditions that would have been placed on a user

applied to a user authenticated via certificate. The pam_authenticate

authenticated via basic authentication are still applied to a user

method will NOT be called. Lastly, the providers must authorize the

authenticated via certificate. The pam_authenticate

user. They receive the username that was mapped to the certificate in

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

the OperationContext.

receive the username that was mapped to the certificate in the <span

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

class=SpellE>OperationContext.

The extensions defined for X.509 v3 certificates provide methods for

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

associating additional attributes with users or public keys and for

its provider registration MOF. The "RequestedOperationContextContainers"

managing the certification hierarchy. Each extension in a certificate

property of PG_Provider should be set to include the

may be designated as critical or non-critical. Pegasus relies on the

"SSLCertificateChain" by setting the value �0�.

underlying OpenSSL implementation to handle critical extensions

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

specified in a certificate. Please refer to the OpenSSL documentation

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

for more information on currently supported extensions in OpenSSL and

maximum depth of seven.

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

The behavior of this property is dependent

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

on the overall CIMOM settings. The "enableHttpsConnection"

configuration property must be set to true for the property to have any effect.

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

Additionally, the "sslClientVerificationMode"

with OpenSSL or go to the OpenSSL Site:

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. <u1:p></u1: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 <span

class=SpellE>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 really fabulous guide on certificate management and installation with <span

class=SpellE>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:

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>

SSLv3 RFC:

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

TLSv1 RFC:

TLSv1 RFC:

Basic Authentication RFC:

Basic Authentication RFC:

<hr>

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

VERITAS Software Corporation

</div>

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

Software Corporation

Permission is hereby granted, free of charge, to any

Permission is hereby granted, free of

person obtaining a copy  of this software and associated

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,

restriction, including without limitation the rights to use, copy, modify,

modify, merge, publish, distribute, sublicense, and/or sell copies of

merge, publish, distribute, sublicense, and/or sell copies of the Software, and

the Software, and to permit persons to whom the Software is furnished

to permit persons to whom the Software is furnished to do so, subject to the

to do so, subject to the following conditions:

following conditions:

THE ABOVE COPYRIGHT NOTICE AND THIS

THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE

PERMISSION NOTICE SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF

SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE

THE SOFTWARE. THE SOFTWARE IS PROVIDED  "AS

SOFTWARE. THE SOFTWARE IS PROVIDED  "AS IS", WITHOUT WARRANTY OF

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

ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE

LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE

WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND

AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE

NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE

LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF

LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION

CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE

OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION

SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

<hr>

</div>

</body>

</html>

Legend:

Removed from v.1.2.12.1
changed lines
	Added in v.1.4.4.2

No CVS admin address has been configured