Return to
PegasusSSLGuidelines.htm
CVS log
Up to [Pegasus] / pegasus / doc
|
Return to
PegasusSSLGuidelines.htm
CVS log
|
Up to [Pegasus] / pegasus / doc
|
|
File: [Pegasus] / pegasus / doc / PegasusSSLGuidelines.htm
(download)
/
(as text)
Revision: 1.4.4.2, Tue Dec 19 10:49:51 2006 UTC (17 years, 4 months ago) by ms.aruran Branch: TASK-PEP268_SSLClientCertificatePropagation-branch Changes since 1.4.4.1: +1331 -765 lines PEP#: 268 TITLE: PEP#268 SSLClientCertificate Propagation Description: Code change |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<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>
<meta http-equiv=Content-Type content="text/html; charset=windows-1252">
<meta name=ProgId content=Word.Document>
<meta name=Generator content="Microsoft Word 10">
<meta name=Originator content="Microsoft Word 10">
<link rel=File-List href="PegasusSSLGuidelines_files/filelist.xml">
<link rel=Edit-Time-Data href="PegasusSSLGuidelines_files/editdata.mso">
<!--[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";}
h2
{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;}
h3
{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;}
h4
{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;}
p
{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;}
ol
{margin-bottom:0in;}
ul
{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 lang=EN-US link=blue vlink=blue style='tab-interval:.5in'>
<div class=Section1>
<h2><span class=SpellE>OpenPegasus</span> 2.6 SSL Guidelines</h2>
<p><b>Version: </b>1.2<br>
<b>Created: </b><st1:date Year="2005" Day="20" Month="7">July 20, 2005</st1:date></p>
<p class=MsoNormal><b>Updated: </b><st1:date Year="2006" Day="19"
Month="12"><b>December</b> 19, 2006</st1:date> </p>
<ul type=disc>
<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="#OVERVIEW">Overview</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</span> 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</span> & <span class=SpellE>cimcrl</span> 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>
<p>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. </p>
<p>This guide requires a basic understanding of SSL, <span class=SpellE>OpenSSL</span>,
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 education
on SSL. If you are not familiar with these <span class=GramE>technologies</span>,
consult the sources in the <a href="#RESOURCES">Resources</a> section at the
bottom. </p>
<p>Note: In this document, the term "trust" refers only to
authentication. It does not imply full trust in the traditional sense, because
it does not take into account authorization checks. It remains the
responsibility of providers and clients to perform authorization, and therefore
establish real trust. Likewise, the term "Trust Store" can be
misleading since the "store" is only a source of authentication
credentials. Please bear this in mind when documenting recommended deployments
or building clients or providers. </p>
<h3><a name=RELATED>Related Information</a></h3>
<p class=MsoNormal>A significant portion of the information in this document is
taken <span class=GramE>from various <span class=SpellE>PEP's</span></span>.
This document attempts to bring all of this information together in a cohesive
and simplified format. </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l15 level1 lfo2;tab-stops:list .5in'>PEP#035 - Add support for
/dev/random in <span class=SpellE>SSLContext</span> </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</span> and Certificate verification interface
enhancement </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#165 - SSL Client
Verification </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#187 - SSL Certificate
Management Enhancements </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#200 - Recommended <span
class=SpellE>OpenPegasus</span> 2.5 Build and Configuration Options for
Selected Platforms</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#268 – SSL Client Certificate
Propagation</li>
</ul>
<h3><a name=BUILDING>Building Pegasus with SSL</a></h3>
<p>To build Pegasus with HTTPS support, you will need to build against the <a
href="http://www.openssl.org"><span class=SpellE>OpenSSL</span> package</a>. <span
style='color:black'>The SSL support outlined here has been tested against
recent releases of the major versions 0.9.7X and 0.9.8X (most notably, 0.9.7d).
Because some versions of 0.9.6X do not contain full support for the security
functions that Pegasus utilizes (for example, certificate-based authentication
is not fully supported by some versions of 0.9.6X), Pegasus does not officially
support major version 0.9.6. See <span class=SpellE>Bugzilla</span> 4048 for
more information. </span>Because this is an open source project, the SSL
support has been tested with many versions of <span class=SpellE>OpenSSL</span>,
but we cannot guarantee it has been tested with every version on every
platform. A list of recent <span class=SpellE>OpenSSL</span> releases, and
important-to-review security advisories and fixes, can be found on the <a
href="http://www.openssl.org/news"><span class=SpellE>OpenSSL</span> News page</a>.
</p>
<p>After grabbing the <span class=SpellE>OpenSSL</span> source <span
class=SpellE>tarball</span>, you need to set the following environment
variables before building Pegasus: </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l14 level1 lfo3;tab-stops:list .5in'>PEGASUS_HAS_SSL=1 </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l14 level1 lfo3;tab-stops:list .5in'>OPENSSL_HOME=<location of
the SDK package> <span class=GramE>This</span> directory must contain
the <span class=SpellE>OpenSSL</span> include directory,
$(OPENSSL_HOME)/include, and the <span class=SpellE>OpenSSL</span> library
directory, $(OPENSSL_HOME)/lib. </li>
<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
the binary package> <span class=GramE>This</span> only needs to be set
if the <span class=SpellE>OpenSSL</span> binaries are not in
$(OPENSSL_HOME)/bin.</li>
</ul>
<p class=MsoNormal>Note that Pegasus supports SSLv3 and TLSv1 by default. It
does NOT support SSLv2. To turn on SSLv2 support, enable the additional
environment variable: </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l9 level1 lfo4;tab-stops:list .5in'>PEGASUS_ENABLE_SSLV2=1 </li>
</ul>
<p>It is not recommended to enable this protocol, as there have been many
security weaknesses associated with it. Unless you are dealing with very
outdated clients, you probably do not need to enable it. </p>
<p>After setting these variables, proceed as normal with the build instructions
in the <span class=SpellE>readme</span> file. </p>
<h3><a name=CERTS>Creating SSL Certificates</a></h3>
<p class=MsoNormal>There are two options for creating the <span class=SpellE>CIMOM's</span>
certificate: </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l5 level1 lfo5;tab-stops:list .5in'>Self-signed certificate </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l5 level1 lfo5;tab-stops:list .5in'>Certificate issued by a
third-party certificate authority</li>
</ul>
<p>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, <span
class=SpellE>ssl.cnf</span> 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. You will also need an <span class=SpellE>OpenSSL</span>
configuration file. There is a sample configuration file that comes with the <span
class=SpellE>OpenSSL</span> package. </p>
<ul type=disc>
<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<span class=GramE>:</span><br>
<span class=SpellE><span style='font-family:Courier;color:#009900'>openssl</span></span><span
style='font-family:Courier;color:#009900'> <span class=SpellE>genrsa</span>
-out <span class=SpellE>myserver.key</span> 1024</span><br>
Set the "<span class=SpellE>sslKeyFilePath</span>" 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:<br>
<span class=SpellE><span style='font-family:Courier;color:#009900'>openssl</span></span><span
style='font-family:Courier;color:#009900'> <span class=SpellE>req</span> -<span
class=SpellE>config</span> <span class=SpellE>openssl.cnf</span> -new -key
<span class=SpellE>myserver.key</span> -out <span class=SpellE>myserver.csr</span></span>
</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>:</span><br>
<span class=SpellE><span style='font-family:Courier;color:#009900'>openssl</span></span><span
style='font-family:Courier;color:#009900'> x509 -in <span class=SpellE>myserver.csr</span>
-out <span class=SpellE>myserver.cert</span> -<span class=SpellE>req</span>
-<span class=SpellE>signkey</span> <span class=SpellE>myserver.key</span>
-days 365</span><br>
Set the "<span class=SpellE>sslCertificateFilePath</span>"
configuration property to point to this certificate file. The above CSR
file can be discarded after the certificate is created. </li>
</ul>
<p>After creating the <span class=SpellE>keypair</span>, make sure you protect
the information sufficiently by changing permissions on the files and/or
directories. The following table shows the recommended privileges: </p>
<table class=MsoNormalTable border=1 cellspacing=1 cellpadding=0 width="30%"
style='width:30.0%;mso-cellspacing:.7pt'>
<tr style='mso-yfti-irow:0'>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal align=center style='text-align:center'><b>SSL file<o:p></o:p></b></p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal align=center style='text-align:center'><b>Pegasus <span
class=SpellE>Config</span> property<o:p></o:p></b></p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal align=center style='text-align:center'><b>Permissions<o:p></o:p></b></p>
</td>
</tr>
<tr style='mso-yfti-irow:1'>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal>Private key</p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal><span class=SpellE>sslKeyFilePath</span></p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal><span class=SpellE>rwx</span>------</p>
</td>
</tr>
<tr style='mso-yfti-irow:2'>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal>Public certificate</p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal><span class=SpellE>sslCertificateFilePath</span></p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal><span class=SpellE>rwxr-xr-x</span></p>
</td>
</tr>
<tr style='mso-yfti-irow:3'>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal><span class=SpellE>Truststore</span></p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal><span class=SpellE>sslTrustStore</span></p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal><span class=SpellE>rwxr-xr-x</span></p>
</td>
</tr>
<tr style='mso-yfti-irow:4;mso-yfti-lastrow:yes'>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal>CRL store </p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal><span class=SpellE>crlStore</span></p>
</td>
<td style='padding:.75pt .75pt .75pt .75pt'>
<p class=MsoNormal><span class=SpellE>rwxr-xr-x</span></p>
</td>
</tr>
</table>
<p>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-writable. Pegasus only checks the following conditions when starting up: </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l1 level1 lfo7;tab-stops:list .5in'>The <span class=SpellE>sslKeyFilePath</span>
and the <span class=SpellE>sslCertificateFilePath</span> are readable by
the CIMOM. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l1 level1 lfo7;tab-stops:list .5in'>The <span class=SpellE>sslTrustStore</span>
and <span class=SpellE>crlStore</span> are readable by the CIMOM if they
are a single file. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l1 level1 lfo7;tab-stops:list .5in'>The <span class=SpellE>sslTrustStore</span>
and <span class=SpellE>crlStore</span> are readable and writable by the
CIMOM if they are a directory.</li>
</ul>
<p>These same file permissions should be used for protecting a client's private
key, public key, <span class=SpellE>truststore</span>, and <span class=SpellE>crl</span>
store as well. </p>
<p>For more information on generating keys and certificates, consult the <a
href="http://www.openssl.org/docs/HOWTO/"><span class=SpellE>OpenSSL</span>
HOW-TO documentation</a>. </p>
<h3><a name=CONFIGURE>Configuring Pegasus for SSL</a></h3>
<p class=MsoNormal>There are many environment variable settings associated with
SSL. Here is a brief discussion of the subtleties of these options and how they
work together to create a more secure environment. More information on the
default and recommended settings can be found in PEP#200 Recommended <span
class=SpellE>OpenPegasus</span> 2.5 Build and Configuration Options for
Selected Platforms. Additionally, the section on <a href="#DESIGN">Design
Question List</a> should help determine what these settings should be for a
given application. </p>
<p><span class=SpellE><span class=GramE><b>enableHttpsConnection</b></span></span><br>
This is disabled by default on most platforms. It is recommended that all
remote communication be done over the HTTPS port. However, if you are sending <span
class=SpellE>cleartext</span> passwords over the wire, it is imperative that
you only use the secure port. For added security, the HTTP port can be disabled
to prevent clients from connecting to it. The HTTPS connection is enabled by
default only on the following platforms: </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
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>
<p><span class=SpellE><span class=GramE><b>httpsPort</b></span></span><br>
The default setting is 5989, the official WBEM secure port. </p>
<p><span class=SpellE><span class=GramE><b>sslCertificateFilePath</b></span></span>
<br>
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 <span class=SpellE>enableHttpsConnection</span> is
true. Any failure in finding this file will result in the <span class=SpellE>cimserver</span>
failing to start. See <a href="#CERTS">Creating SSL Certificates</a> for more
information. </p>
<p><span class=SpellE><span class=GramE><b>sslKeyFilePath</b></span></span><br>
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 <span class=SpellE>enableHttpsConnection</span>
is true. Any failure in finding this file will result in the <span
class=SpellE>cimserver</span> failing to start. See <a href="#CERTS">Creating
SSL Certificate</a> for more information. </p>
<p><span class=SpellE><span class=GramE><b>sslClientVerificationMode</b></span></span><br>
This setting controls how the <span class=SpellE>cimserver</span> (i.e. the
HTTPS port) is configured. 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 <span class=SpellE>OpenSSL</span> handshake: </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l4 level1 lfo9;tab-stops:list .5in'><b>"<span class=GramE>required</span>"</b>
-- The server requires that the client certificate be trusted in order for
the handshake to continue. If the client fails to send a certificate or
sends an <span class=SpellE>untrusted</span> certificate, the handshake is
immediately terminated. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l4 level1 lfo9;tab-stops:list .5in'><b>"<span class=GramE>optional</span>"</b>
-- The server will request that a client certificate be sent, but will
continue the handshake even if no certificate is received. If
authentication is enabled, the server will seek to authenticate the client
via an alternative method of authentication. <span style='color:black'>As
of 2.5.1, if a certificate is sent but it is not validated, the handshake
will fail. <i>Before 2.5.1<span class=GramE>,the</span> handshake would
have continued and basic authentication would have proceeded.</i></span> </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l4 level1 lfo9;tab-stops:list .5in'><b>"<span class=GramE>disabled</span>"</b>
-- The server will not prompt the client for a certificate. <i>This is the
default.</i></li>
</ul>
<p class=MsoNormal>Pegasus currently ties a certificate to a valid OS user.
Multiple certificates may be registered to the same user. When a certificate is
authenticated, Pegasus views it in the same way as if a user was authenticated
via basic authentication. The providers receive the username that the
certificate was mapped to. See the SSL Authorization section for more
information. </p>
<p><span class=SpellE><span class=GramE><b>sslTrustStore</b></span></span><br>
This setting controls the <span class=SpellE>truststore</span> for the <span
class=SpellE>cimserver's</span> 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 <span class=SpellE>cimtrust</span> CLI to populate the <span
class=SpellE>truststore</span> as there are strict naming requirements for
trusted certificate files. See the <a href="#CLI"><span class=SpellE>cimtrust</span>
& <span class=SpellE>cimcrl</span> CLI</a> section for further information.
</p>
<p><span class=SpellE><span class=GramE><b>sslTrustStoreUserName</b></span></span><br>
This setting is only utilized if the <span class=SpellE>sslTrustStore</span> is
a single CA file. It is not used if the <span class=SpellE>sslTrustStore</span>
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 <span
class=SpellE>sslTrustStore</span> setting. This property represents the valid
OS user that corresponds to the root certificate. All requests authenticated
with a certificate under the root CA will be associated with this user and the
username will be propagated to providers. If applications desire for there to
be a one-to-one correspondence between users and certificates, it is
recommended that each certificate be registered individually using the <a
href="#CLI"><span class=SpellE>cimtrust</span> CLI</a>. </p>
<p><span class=SpellE><span class=GramE><b>crlStore</b></span></span><br>
This is where the CRL (Certificate Revocation List) store resides. It is important
to note that certificates are checked first against the CRL (if specified) and
then against the server <span class=SpellE>truststore</span>. The <a href="#CLI"><span
class=SpellE>cimcrl</span> CLI</a> should be used for CRL management. </p>
<h4>Configuration Limitations</h4>
<p class=MsoNormal>The following are configuration limitations: </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l2 level1 lfo10;tab-stops:list .5in'>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 <span class=SpellE>unencrypt</span>
it. Therefore, the best way to secure the file is to follow the file
permissions settings specified in <a href="#CERTS">Creating SSL
Certificates.</a> </li>
<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</span> cipher list. The cipher lists can be found at <a
href="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</a>
and <a
href="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</a>
</li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l2 level1 lfo10;tab-stops:list .5in'>The verification depth
cannot be specified. Pegasus uses the default <span class=SpellE>OpenSSL</span>
depth of 9. This means the <span class=SpellE>OpenSSL</span> will only
accept client certificate chains up to 9 levels deep. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l2 level1 lfo10;tab-stops:list .5in'>No hostname checking is
performed to ensure that the subject field of the distinguished name (DN)
matches the hostname.</li>
</ul>
<h3><a name=DESIGN>SSL Design Question List</a></h3>
<p>The following questions may be helpful in determining how to configure
Pegasus CIM Server.</p>
<p class=MsoNormal><b>Should I enable the HTTPS port?</b><br>
Yes, especially if you are sending passwords with requests. The HTTP port can
be disabled for additional security if desired. <br>
<b>Should I configure the CIMOM to use a <span class=SpellE>truststore</span>?</b><br>
This depends on the infrastructure of the application. If all clients are using
basic authentication over the secure port (and the passwords are secured), then
a <span class=SpellE>truststore</span> may not be needed. If an application
does not want to store user/<span class=SpellE>pw</span> information, then it
is a good idea to use a certificate-based infrastructure. If a CIMOM
certificate is compromised, the <span class=SpellE>cimserver</span> and the
providers of the system are compromised. The severity of this scenario is
dependent on the resources the providers have access to. If an OS password is
compromised, the entire system may be compromised. If using peer verification,
it is important to ensure that 1) the <span class=SpellE>cimserver</span> is
properly configured to use a <span class=SpellE>truststore</span>, 2) the <span
class=SpellE>truststore</span> is loaded properly and protected, and 3)
authorization checks are performed after a certificate is verified. These same
conditions also apply to a client that is verifying a server.<br>
<b>Should I use a self-signed certificate or one issued by a third-party
certificate authority?</b><br>
Generally, scalability will determine whether it's appropriate to use a self-signed
certificate or one issued by <span class=SpellE>Verisign</span> or another
third-party certificate authority. 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 <span class=SpellE>certs</span> it has signed, in large
deployments. In small deployments the incremental cost might never outweigh the
initial CA-setup cost. <br>
One important thing to remember is that you should not use the same certificate
for multiple <span class=SpellE>CIMOMs</span>. If using a self-signed
certificate, a different one should be generated for each CIMOM, using some
unique piece of data to make them different. That way, if one of the
certificates is compromised, the other ones remain secure. <br>
<b>Should the <span class=SpellE>truststore</span> be a single root CA file or
a directory?</b><br>
If you only anticipate connections from a narrowly defined set of clients, then
a single root CA certificate file should be sufficient. Alternatively, multiple
trusted certificates may be stored in PEM format inside of a single CA file. If
you anticipate getting requests from a heterogeneous set of clients, then it
probably makes sense to use the directory option to allow flexibility in the
future. In the latter scenario, the same single root CA file can still be used
with the additional step of using <span class=SpellE>cimtrust</span> to
register it. It's important to note that when registering a root CA, only one
user can be associated with ALL certificates under that CA. Following the
principle of least privilege, it is not a good idea to register a root CA to a
privileged user if lesser privileged users will be connecting with it. <br>
<b>How do I protect the <span class=SpellE>keystore</span> and the <span
class=SpellE>truststore</span>?</b><br>
The server's private key should always be protected; it is private for a
reason. Only the system administrator should be able to see it. The public
certificate can be viewed by <span class=GramE>anyone,</span> however, it
should be protected from alteration by system users. Similarly, any <span
class=SpellE>truststore</span> or CRL file or directory should also be
protected from alteration. See <a href="#CERTS">Creating SSL Certificates</a>
for the recommended file privileges. <br>
<b>When do I need to use a CRL?</b><br>
Certificate Revocation Lists are regularly issued by CA's. They contain a list
of certificates that have been revoked. Any application using a CA certificate
in its <span class=SpellE>truststore</span> should also implement <span
class=SpellE>CRLs</span> (if the CA supports them). Pegasus itself does not
check CRL validity dates during startup. Therefore, it is the responsibility of
the administrator to regularly download or acquire the CRL and import it into
the CRL store using the <a href="#CLI"><span class=SpellE>cimcrl</span> CLI</a>.
<span class=SpellE><span style='color:black'>CRLs</span></span><span
style='color:black'> are not checked for expiration during the SSL callback.
This means that if a CRL for a particular issuer has expired, Pegasus still
accepts certificates from the issuer and uses the expired CRL as the latest.
Again, it is the responsibility of the administrator to ensure the CRL is up to
date. <span class=SpellE>CRLs</span> are not checked for critical extensions
during CRL verification. If a CRL contains a critical extension it will be
ignored. </span><br>
If using self-signed certificates, however, a CRL is most likely not needed
(You can create a self-signed CRL but it is not really necessary). Because of
this, the certificate deletion option available via <span class=SpellE>cimtrust</span>
is primarily intended for self-signed certificates. Technically, <span
class=SpellE>CRL's</span> are the correct way to revoke compromised or invalid
certificates. <br>
<b>What is the order of operations for certificate verification?</b><br>
The certificate is checked against any <span class=SpellE>CRLs</span> first
before going through the rest of the verification process. Verification starts
with the root certificate and continues down to the peer certificate. If
verification fails at any of these points, the certificate is considered <span
class=SpellE>untrusted</span> and the verification process reports an error. </p>
<h3><a name=TRUSTSTORE></a><span class=SpellE><span style='mso-bookmark:TRUSTSTORE'>Truststore</span></span><span
style='mso-bookmark:TRUSTSTORE'> Management</span></h3>
<p class=MsoNormal>There are two directions of trust in an SSL client-server
handshake: The client trusts the server. The server trusts the client. Pegasus
provides a way to implement one or both of these relationships. Ideally, an
application should support both levels of trust for maximum security and this
is the implementation Pegasus recommends. However, in some scenarios it may
make sense to only implement one of these; in that case, it is possible to override
the client or the server to "trust all certificates." For example, if
all clients will be using basic authentication over HTTPS, then the server can
be setup to "trust all client certificates." </p>
<p>To tell the <span class=SpellE>cimserver</span> to require that all clients
be trusted, simply set the <span class=SpellE>sslClientVerification<span
style='color:black'>Mode</span></span> property to "required."<br>
To tell the <span class=SpellE>cimserver</span> to trust all clients, set the <span
class=SpellE>sslClientVerification<span style='color:black'>Mode</span></span>
property to "disabled" or "optional". </p>
<p>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. <span style='color:black'>In situations where a client is not
authenticated by SSL because the client sent no certificate and the setting is
"optional", the server will attempt to authenticate the client via
another method of <span class=GramE>authentication .</span> In this case, the
authentication mechanism specified by the configuration property "<span
class=SpellE>httpAuthType</span>" will be used for remote connections and
local authentication will be used for local connections. In situations where a
client is not authenticated by SSL because the client certificate was invalid,
the handshake will be terminated. <br>
<i>Note: Before 2.5.1, in the latter case, authentication would have proceeded
in the same way as if the client had sent no certificate. To enable the legacy
behavior, the compile-time flag PEGASUS_OVERRIDE_SSL_CERT_VERIFICATION_RESULT
should be defined.</i> </span></p>
<p>See the <a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a>
section below on how to setup the client's <span class=SpellE>truststore</span>.
</p>
<h3><a name=CLI></a><span class=SpellE><span class=GramE><span
style='mso-bookmark:CLI'>cimtrust</span></span></span><span style='mso-bookmark:
CLI'> & <span class=SpellE>cimcrl</span> CLI</span></h3>
<p class=MsoNormal><span class=SpellE><span class=GramE>cimtrust</span></span>
CLI may be used to add, remove or list X509 certificates in a PEM format <span
class=SpellE>truststore</span>. <span class=SpellE><span class=GramE>cimcrl</span></span>
CLI may be used to add, remove or list X509 Certificate Revocation Lists in a
PEM format CRL store. The <span class=SpellE>CLIs</span> interface with a
Certificate control provider that runs as part of Pegasus's core. It operates
on the <span class=SpellE>PG_SSLCertificate</span> and <span class=SpellE>PG_SSLCertificateRevocationList</span>
classes in root/<span class=SpellE>PG_Internal</span>. It is recommended that
the <span class=SpellE>CLIs</span> be used in place of manual configuration for
several reasons: </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l13 level1 lfo11;tab-stops:list .5in'><span class=SpellE>OpenSSL</span>
places strict naming restrictions on certificates and <span class=SpellE>CRLs</span>
in a directory (the files are looked up via a subject hash code) </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
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><span class=SpellE><span class=GramE><span
style='color:black'>cimtrust</span></span></span><span style='color:black'>
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.</span> </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l13 level1 lfo11;tab-stops:list .5in'><span style='color:black'>The
<span class=SpellE>CLIs</span>, or more correctly the provider they
operate on, supports dynamic deletion of certificates by resetting the <span
class=SpellE>cimserver's</span> SSL context.</span><span style='color:
fuchsia'> </span>Normally, you would need to stop and start the <span
class=SpellE>cimserver</span> 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 <span class=SpellE>CLIs</span>,
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>
<p class=MsoNormal>The CIMOM must be up and running while executing <span
class=SpellE>cimtrust/cimcrl</span> CLI. The <span class=SpellE>cimtrust</span>
and <span class=SpellE>cimcrl</span> <span class=SpellE>manpages</span> provide
more information on commands and syntax. </p>
<h3><a name=CLIENT>Configuring the Pegasus CIM Client for SSL</a></h3>
<p>A Pegasus CIM client can be configured to use SSL by using a constructor
that takes an <span class=SpellE>SSLContext</span>. The construction of the <span
class=SpellE>SSLContext</span> 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</span> constructor parameters. </p>
<p>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 <span class=SpellE>truststore</span> and specifies an
additional callback in addition to the default one (the user-specified callback
is optional and can be set to null). </p>
<p class=MsoNormal style='margin-left:.5in'><span class=SpellE><span
class=GramE><span style='font-family:Courier'>client.connect</span></span></span><span
class=GramE><span style='font-family:Courier'>(</span></span><span
style='font-family:Courier'> hostname, port, <span class=SpellE><b>SSLContext</b></span><b>(<span
class=SpellE>trustStore</span>, <span class=SpellE>certPath</span>, <span
class=SpellE>keyPath</span>, <span class=SpellE>verifyCert</span>, <span
class=SpellE>randomFile</span>),</b> username, password); </span></p>
<p>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>. </p>
<p class=MsoNormal style='margin-left:.5in'><span class=SpellE><span
class=GramE><span style='font-family:Courier'>client.connect</span></span></span><span
class=GramE><span style='font-family:Courier'>(</span></span><span
style='font-family:Courier'> hostname, port, <span class=SpellE><b>SSLContext</b></span><b>(<span
class=SpellE>trustStore</span>, NULL, <span class=SpellE>randomFile</span>),</b>
username password); </span></p>
<ul type=disc>
<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=SpellE><span
class=GramE><b>trustStore</b></span></span> -- This specifies the <span
class=SpellE>truststore</span> that the client uses to verify server
certificates. It can be <span class=SpellE>String::EMPTY</span> if no <span
class=SpellE>truststore</span> 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=SpellE><span
class=GramE><b>certPath</b></span></span> -- 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 <span class=SpellE>keyPath</span> 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=SpellE><span
class=GramE><b>keyPath</b></span></span> -- This specifies the private key
of the client. If this option is specified, the <span class=SpellE>certPath</span>
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=SpellE><span
class=GramE><b>crlPath</b></span></span> -- 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=SpellE><span
class=GramE><b>verifyCert</b></span></span> -- This is a user-specified
verification callback. If this is set to null, the default <span
class=SpellE>OpenSSL</span> verification callback will be executed. You
can implement this method to "trust all servers" or to perform
additional authentication checks that <span class=SpellE>OpenSSL</span>
does not perform by default. </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=SpellE><span
class=GramE><b>randomFile</b></span></span> -- A file to seed the pseudo
random number generator (PRNG).</li>
</ul>
<p>Here are some general guidelines on implementing peer verification for the
client: </p>
<ul type=disc>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should enable
peer verification by specifying a <span class=SpellE>truststore</span> and
(optionally) a user-specified callback function. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should employ a <span
class=SpellE>truststore</span> in order to properly verify the server. The
<span class=SpellE>truststore</span> should contain a file or directory of
trusted CA certificates. The <span class=SpellE>cimtrust</span> CLI cannot
be used to configure client <span class=SpellE>truststores</span>. The
trusted certificate(s) should be placed in a protected file or directory
specified by the <span class=SpellE>trustStore</span> parameter. Keep in
mind that the SSL context generally has to be reloaded to pick up any <span
class=SpellE>truststore</span> changes. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client could also use a
user-specified callback in addition to the default verification callback,
if additional verifications are desired over the normal checks that <span
class=SpellE>OpenSSL</span> performs. In most cases, the default
verification callback is sufficient for checking server certificates. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should ensure
that adequate entropy is attained. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should use a CRL
store if the <span class=SpellE>truststore</span> contains CA certificates
that support one. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should only use
the SSLv3 and TLSv1 protocols. By default, Pegasus is not built with SSLv2
support. </li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l11 level1 lfo15;tab-stops:list .5in'>The client should perform
post-connection checks. </li>
<ul type=circle>
<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 a certificate
was received. </li>
<ul type=square>
<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: In
some implementations of SSL a NULL server certificate is perfectly valid
and authenticates against all trust stores. If the client does not
ensure a certificate exists then the client is not providing server
authentication and could have a security bulletin class defect.</li>
</ul>
<li 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
certificate received was issued to the host for which the client was attempting
to connect. </li>
<ul type=square>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:
auto;mso-list:l11 level3 lfo15;tab-stops:list 1.5in'>Ensure that the
common name (CN) in the server’s certificate subject matches the host
name of the server. For X509v3 certificates, the “<span
class=SpellE><span class=spelle>SubjectAltName</span></span>” 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>
</ul>
<p>Because only the above arguments can be passed into the Pegasus <span
class=SpellE>SSLContext</span>, there are some limitations in the client
configuration: </p>
<ul type=disc>
<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 <span class=SpellE>OpenSSL</span>
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 <span class=SpellE>OpenSSL</span>
cipher list. The cipher lists can be found at <a
href="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</a>
and <a
href="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</a>
</li>
<li class=MsoNormal style='mso-margin-top-alt:auto;mso-margin-bottom-alt:auto;
mso-list:l10 level1 lfo16;tab-stops:list .5in'>No hostname checking is
performed to ensure that the subject field of the distinguished name (DN)
matches the hostname. If desired, a user-specified callback should be
configured to perform this check or any additional checks relevant to the
application.</li>
</ul>
<h3><a name=AUTH>SSL Authorization</a></h3>
<p>The following paragraphs concern authorization of users authenticated by
certificate on the <span class=SpellE>cimserver's</span> HTTPS port. </p>
<p>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 <span class=SpellE>sslClientVerification</span>
property is set to "required" and no certificate or an <span
class=SpellE>untrusted</span> certificate is sent. </p>
<p>Further <b><i>authorization</i></b> checks must be performed when validating
the user that is mapped to the certificate. First, the user that is registered
to the certificate is validated as a valid system user and a valid <span
class=SpellE>cimuser</span> (if the <span class=SpellE>cimuser</span> function
has been configured). <span style='color:black'>In the case of a certificate
chain, the username authorization starts with the leaf certificate. If it
successfully finds a mapping for the leaf certificate, it continues; if there
is no username for the leaf certificate, the validation proceeds up to the root
certificate. If the root certificate is reached and there is still no mapped
username, the authorization fails.</span><span style='color:fuchsia'> </span>Additionally,
if Pegasus was configured to use PAM, the <span class=SpellE>pam_acct_mgmt</span>
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 <span class=SpellE>pam_authenticate</span>
method will NOT be called. Lastly, the providers must authorize the user. They
receive the username that was mapped to the certificate in the <span
class=SpellE>OperationContext</span>. </p>
<p>A provider may request the client's certificate chain information through
its provider registration MOF. The "<span class=SpellE>RequestedOperationContextContainers</span>"
property of <span class=SpellE>PG_Provider</span> should be set to include the
"<span class=SpellE>SSLCertificateChain</span>" by setting the value “0”.
If a client is authenticated via trusted certificate, then the container will
include a certificate for each level in the client's certificate chain, up to a
maximum depth of seven.</p>
<p><span style='font-family:Times'>The behavior of this property is dependent
on the overall CIMOM settings. The "<span class=SpellE>enableHttpsConnection</span>"
configuration property must be set to true for the property to have any effect.
Additionally, the "<span class=SpellE>sslClientVerificationMode</span>"
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 <span class=SpellE>OperationContext</span>,
providers should always check for its existence before performing operations on
it. See the <span class=SpellE>SSLCertificateInfo</span> class in
Pegasus/Common/<span class=SpellE>SSLContext.h</span> for a full list of
certificate parameters that the <span class=SpellE>SSLCertificateChainContainer</span>
supports. <u1:p></u1:p></span></p>
<h3><a name=EXT>Critical Extension Handling</a></h3>
<p><span style='color:black'>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
<span class=SpellE>OpenSSL</span> implementation to handle critical extensions
specified in a certificate. Please refer to the <span class=SpellE>OpenSSL</span>
documentation for more information on currently supported extensions in <span
class=SpellE>OpenSSL</span> and on the behavior of <span class=SpellE>OpenSSL</span>
in the case of unhandled critical extensions.</span><span style='color:fuchsia'>
</span></p>
<h3><a name=RESOURCES>Resources</a></h3>
<p>For <span class=SpellE>OpenSSL</span> information pick up a copy of
O'Reilly's Network Security with <span class=SpellE>OpenSSL</span> or go to the
<span class=SpellE>OpenSSL</span> Site<span class=GramE>:</span><br>
<a href="http://www.openssl.org">http://www.openssl.org</a> </p>
<p>A really fabulous guide on certificate management and installation with <span
class=SpellE>OpenSSL</span><span class=GramE>:</span><br>
<a href="http://www.gagravarr.org/writing/openssl-certs/index.shtml">http://www.gagravarr.org/writing/openssl-certs/index.shtml</a>
</p>
<p><span class=GramE>x509</span> Certificate and CRL RFC:<br>
<a href="http://www.ietf.org/rfc/rfc2459.txt?number=2459">http://www.ietf.org/rfc/rfc2459.txt?number=2459</a>
</p>
<p>SSLv3 RFC<span class=GramE>:</span><br>
<a href="http://wp.netscape.com/eng/ssl3/">http://wp.netscape.com/eng/ssl3</a> </p>
<p>TLSv1 RFC<span class=GramE>:</span><br>
<a href="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</a>
</p>
<p>Basic Authentication RFC<span class=GramE>:</span><br>
<a href="http://www.faqs.org/rfcs/rfc2617.html">http://www.faqs.org/rfcs/rfc2617.html</a>
</p>
<div class=MsoNormal align=center style='text-align:center'>
<hr size=2 width="100%" align=center>
</div>
<p><i><span style='font-size:10.0pt'>Copyright (c) 2005 EMC Corporation;
Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open Group; VERITAS
Software Corporation</span><br>
<br>
</i><i><span style='font-size:7.5pt'>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:</span><br>
</i><i><span style='font-size:10.0pt'><br>
</span></i><i><span style='font-size:7.5pt'>THE ABOVE COPYRIGHT NOTICE AND THIS
PERMISSION NOTICE SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF
THE SOFTWARE. THE SOFTWARE IS PROVIDED<span class=GramE> "</span>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.</span></i></p>
<div class=MsoNormal align=center style='text-align:center'>
<hr size=2 width="100%" align=center>
</div>
</div>
</body>
</html>
| No CVS admin address has been configured |
Powered by ViewCVS 0.9.2 |