1 dave.sudlik 1.3 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <title>OpenPegasus SSL Guidelines</title>
5 </head>
6 <body>
7 <h2>OpenPegasus 2.5.1 SSL Guidelines</h2>
8 <p><b>Version: </b>1.1<br>
9 <b>Created: </b>July 20, 2005</p>
10 <b>Updated: </b>March 20, 2006
11 <p></p>
12 <ul>
13 <li><a href="#OVERVIEW">Overview</a> </li>
14 <li><a href="#RELATED">Related Information</a> </li>
15 <li><a href="#BUILDING">Building Pegasus with SSL</a> </li>
16 <li><a href="#CERTS">Creating SSL Certificates</a> </li>
17 <li><a href="#CONFIGURE">Configuring Pegasus for SSL</a> </li>
18 <li><a href="#DESIGN">SSL Design Question List</a> </li>
19 <li><a href="#TRUSTSTORE">Truststore Management</a> </li>
20 <li><a href="#CLI">ssltrustmgr CLI</a> </li>
21 <li><a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a> </li>
22 dave.sudlik 1.3 <li><a href="#AUTH">SSL Authorization</a> </li>
23 <li><a href="#EXT">Critical Extension Handling</a> </li>
24 <li><a href="#RESOURCES">Resources</a>
25 </li>
26 </ul>
27 <h3><a name="OVERVIEW">Overview</a></h3>
28 <p>
29 The following document serves as a guide on how to build and configure
30 Pegasus for SSL support. It also discusses how to utilize a
31 certificate-based
32 infrastructure and configure the Pegasus CIM client. </p>
33 <p>This guide requires a basic understanding of SSL, OpenSSL, and basic
34 authentication. This guide is intended to help developers and
35 administrators make the right decisions about how to use SSL for their
36 particular application. It is not intended to be a primary source of
37 education on SSL. If you are not familiar with these technologies,
38 consult the sources in the <a href="#RESOURCES">Resources</a> section
39 at the bottom.
40 </p>
41 <p></p>
42 <p>Note: In this document, the term "trust" refers only to
43 dave.sudlik 1.3 authentication. It does not imply full trust in the traditional sense,
44 because it does not take into account authorization checks. It remains
45 the responsibility of providers and clients to perform authorization,
46 and therefore establish real trust. Likewise, the term "Trust Store"
47 can be misleading since the "store" is only a source of authentication
48 credentials. Please bear this in mind when documenting recommended
49 deployments or building clients or providers.
50 </p>
51 <h3><a name="RELATED">Related Information</a></h3>
52 A significant portion of the information in this document is taken from
53 various PEP's. This document attempts to bring all of this information
54 together in a cohesive and simplified format.
55 <p></p>
56 <ul>
57 <li>PEP#035 - Add support for /dev/random in SSLContext</li>
58 <li>PEP#060 - SSL support in CIM/XML indication delivery</li>
59 <li>PEP#074 - SSLContext and Certificate verification interface
60 enhancement</li>
61 <li>PEP#155 - Support for Client SSL Certificate Verification in CIM
62 Server for CIMExport requests</li>
63 <li>PEP#165 - SSL Client Verification</li>
64 dave.sudlik 1.3 <li>PEP#187 - SSL Certificate Management Enhancements</li>
65 <li>PEP#200 - Recommended OpenPegasus 2.5 Build and Configuration
66 Options for Selected Platforms</li>
67 </ul>
68 <p></p>
69 <h3><a name="BUILDING">Building Pegasus with SSL</a></h3>
70 <p> To build Pegasus with HTTPS support, you will need to build against
71 the <a href="http://www.openssl.org">OpenSSL package</a>. <font
72 style="color: rgb(0, 0, 0);" color="MAGENTA">The SSL support outlined
73 here has been tested against recent releases of the major versions
74 0.9.7X and 0.9.8X (most notably, 0.9.7d). Because some versions of
75 0.9.6X do not contain full support for the security functions that
76 Pegasus utilizes (for example, certificate-based authentication is not
77 fully supported by some versions of 0.9.6X), Pegasus does not
78 officially support major version 0.9.6.
79 See Bugzilla 4048 for more information. </font>
80 Because this is an open source project, the SSL support has been tested
81 with many versions of OpenSSL, but we cannot guarantee it has been
82 tested with every version on every platform. A list of recent OpenSSL
83 releases, and important-to-review security advisories and fixes, can
84 be found on the <a href="http://www.openssl.org/news">OpenSSL News page</a>.
85 dave.sudlik 1.3 </p>
86 <p>
87 After grabbing the OpenSSL source tarball, you need to set the
88 following environment variables before building Pegasus:
89 </p>
90 <ul>
91 <li>PEGASUS_HAS_SSL=1</li>
92 <li>OPENSSL_HOME=<location of the SDK package> This directory
93 must contain the OpenSSL include directory, $(OPENSSL_HOME)/include,
94 and the OpenSSL library directory, $(OPENSSL_HOME)/lib.</li>
95 <li>OPENSSL_BIN=<location of the binary package> This only
96 needs to be set if the OpenSSL binaries are not in $(OPENSSL_HOME)/bin.</li>
97 </ul>
98 Note that Pegasus supports SSLv3 and TLSv1 by default. It does NOT
99 support SSLv2. To turn on SSLv2 support, enable the additional
100 environment variable:
101 <ul>
102 <li> PEGASUS_ENABLE_SSLV2=1 </li>
103 </ul>
104 <p>
105 It is not recommended to enable this protocol, as there have been many
106 dave.sudlik 1.3 security weaknesses associated with it. Unless you are dealing
107 with very outdated clients, you probably do not need to enable it. </p>
108 <p>
109 After setting these variables, proceed as normal with the build
110 instructions in the readme file.
111 </p>
112 <h3><a name="CERTS">Creating SSL Certificates</a></h3>
|
113 h.sterling 1.1 There are two options for creating the CIMOM's certificate:
|
114 dave.sudlik 1.3 <ul>
115 <li>Self-signed certificate</li>
116 <li>Certificate issued by a third-party certificate authority</li>
117 </ul>
118 <p>
119 To generate a self-signed certificate, you must create a private key, a
120 certificate signing request (CSR), and finally the public x509
121 certificate.
122 You also need an SSL configuration file that defines the parameters of
123 the Distinguished Name (DN). You can use the one that comes with
124 Pegasus, ssl.cnf in the root directory, or generate your own. For a
125 self-signed certificate, the subject
126 is the same as the issuer. Execute the following commands to create a
127 self-signed certificate. The PEGASUS_ROOT and PEGASUS_HOME have to be
128 set to your respective installation and source directory. You will also
129 need an OpenSSL configuration
130 file. There is a sample configuration file that comes with the OpenSSL
131 package. </p>
132 <p></p>
133 <ul>
134 <li>To generate a private key, execute the following:<br>
135 dave.sudlik 1.3 <font color="#009900" face="courier">openssl genrsa -out
136 myserver.key 1024</font><br>
137 Set the "sslKeyFilePath" configuration property to point to this key
138 file. </li>
139 <li>To generate a certificate signing request, execute the following:<br>
140 <font color="#009900" face="courier">openssl req -config
141 openssl.cnf -new -key myserver.key -out myserver.csr</font>
142 </li>
143 <li> At this point, the certificate signing request can be sent out
144 to a third-party certificate authority for signing, or a self-signed
145 certificate can be generated. To generate a self-signed certificate,
146 execute the following:<br>
147 <font color="#009900" face="courier">openssl x509 -in myserver.csr
148 -out myserver.cert -req -signkey myserver.key -days 365</font><br>
149 Set the "sslCertificateFilePath" configuration property to point to
150 this certificate file. The above CSR file can be discarded after the
151 certificate is created.
152 </li>
153 </ul>
154 <p>
155 After creating the keypair, make sure you protect the information
156 dave.sudlik 1.3 sufficiently by changing permissions on the files and/or directories.
|
157 h.sterling 1.1 The following table shows the recommended privileges:
|
158 dave.sudlik 1.3 </p>
159 <p>
160 <table border="1" cellspacing="1" width="30%">
161 <tbody>
162 <tr>
163 <th><b>SSL file</b></th>
164 <th><b>Pegasus Config property</b></th>
165 <th><b>Permissions</b></th>
166 </tr>
167 <tr>
168 <td>Private key</td>
169 <td>sslKeyFilePath</td>
170 <td>rwx------</td>
171 </tr>
172 <tr>
173 <td>Public certificate</td>
174 <td>sslCertificateFilePath</td>
175 <td>rwxr-xr-x</td>
176 </tr>
177 <tr>
178 <td>Truststore</td>
179 dave.sudlik 1.3 <td>sslTrustStore, exportSSLTruststore</td>
180 <td>rwxr-xr-x</td>
181 </tr>
182 <tr>
183 <td>CRL store </td>
184 <td>crlStore</td>
185 <td>rwxr-xr-x</td>
186 </tr>
187 </tbody>
188 </table>
189 </p>
190 <p>The administrator is responsible for ensuring that the above file
191 permissions are set correctly. The administrator should also ensure
192 that all containing directories all the way up to the base directory
193 are not world-writable. Pegasus only checks the following conditions
194 when starting up:
195 </p>
196 <ul>
197 <li>The sslKeyFilePath and the sslCertificateFilePath are readable by
198 the CIMOM.</li>
199 <li>The sslTrustStore, exportSSLTrustStore, and crlStore are readable
200 dave.sudlik 1.3 by the CIMOM if they are a single file.</li>
201 <li>The sslTrustStore, exportSSLTrustStore, and crlStore are readable
202 and writable by the CIMOM if they are a directory.</li>
203 </ul>
204 <p>
205 These same file permissions should be used for protecting a client's
206 private key, public key, truststore, and crl store as well.
207 </p>
208 <p> For more information on generating keys and certificates, consult
209 the <a href="http://www.openssl.org/docs/HOWTO/">OpenSSL HOW-TO
210 documentation</a>. </p>
211 <h3><a name="CONFIGURE">Configuring Pegasus for SSL</a></h3>
212 There are many environment variable settings associated with SSL. Here
213 is a brief discussion of the subtleties of these options and how they
214 work together to
215 create a more secure environment. More information on the default and
216 recommended settings can be found in PEP#200 Recommended OpenPegasus
217 2.5 Build and Configuration Options for Selected Platforms.
218 Additionally, the section on <a href="#DESIGN">Design Question List</a>
219 should help determine what these settings should be for a given
220 application.
221 dave.sudlik 1.3 <p><b>enableHttpsConnection</b><br>
222 This is disabled by default on most platforms. It is recommended that
223 all remote communication be done over the HTTPS port. However, if you
224 are sending cleartext passwords over the wire, it is imperative that
225 you only use the secure port. For added security, the HTTP port can be
226 disabled to prevent clients from connecting to it. The HTTPS connection
227 is enabled by default only on the following platforms:
228 </p>
229 <p></p>
230 <ul>
231 <li>LINUX</li>
232 <li>OS-400</li>
233 <li>HP_UX (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</li>
234 <li>VMS (if PEGASUS_USE_RELEASE_CONFIG_OPTIONS is true)</li>
235 </ul>
236 <p></p>
237 <p>
238 <b>httpsPort</b><br>
239 The default setting is 5989, the official WBEM secure port. </p>
240 <p> <b>sslCertificateFilePath</b> <br>
241 This is the path to the x509 server certificate. The server certificate
242 dave.sudlik 1.3 may be a chain in which case the file should contain PEM encoded
243 certificates beginning with the server certificate and followed by each
244 signing certificate authority (CA) including the root CA. If the server
245 certificate is a self signed certificate, the file only contains the
246 self-signed certificate in PEM format.
247 The certificate cannot be encrypted because there is currently no
248 mechanism for decrypting the certificate using a user-supplied
249 password. This property must be defined if enableHttpsConnection is
250 true. Any failure in finding this file will result in the cimserver
251 failing to start. See <a href="#CERTS">Creating SSL Certificates</a>
|
252 h.sterling 1.1 for more information.
|
253 dave.sudlik 1.3 </p>
254 <p><b>sslKeyFilePath</b><br>
255 This is the path to the server's private key. All keys should be at
256 least 1024 bytes long. This property must be defined if
257 enableHttpsConnection is true. Any failure in finding this file will
258 result in the cimserver failing to start. See <a href="#CERTS">Creating
259 SSL Certificate</a> for more information.
260 </p>
261 <p><b>sslClientVerificationMode</b><br>
262 This setting controls how the cimserver (i.e. the HTTPS port) is
263 configured. It does not control the configuration of the export
264 connection. There are three possible settings: disabled, required,
265 optional. There is no "right" setting for this property. The default is
266 disabled and it is fine to leave the setting as disabled if you are
267 going to use basic authentication to authenticate all client requests.
268 In many applications where a physical person is there to supply a
269 username and password, basic authentication is sufficient. Other
270 environments may be heterogeneous, in which case it makes sense to
271 allow both basic authentication and SSL certificate verification. The
272 setting of this variable also impacts what happens during the OpenSSL
273 handshake: </p>
274 dave.sudlik 1.3 <ul>
275 <li><b>"required"</b> -- The server requires that the client
276 certificate be trusted in order for the handshake to continue. If the
277 client fails to send a certificate or sends an untrusted certificate,
278 the handshake is immediately terminated.</li>
279 <li><b>"optional"</b> -- The server will request that a client
280 certificate be sent, but will continue the handshake even if no
281 certificate is received. If authentication is enabled, the server will
282 seek to authenticate the client via an alternative method of
283 authentication. <font style="color: rgb(0, 0, 0);" color="MAGENTA">As
284 of 2.5.1, if a certificate is sent but it is not validated, the
285 handshake will fail. <i>Before 2.5.1,the handshake would have
286 continued and basic authentication would have proceeded.</i></font> </li>
287 <li><b>"disabled"</b> -- The server will not prompt the client for a
288 certificate. <i>This is the default.</i></li>
289 </ul>
290 Pegasus currently ties a certificate to a valid OS user. Multiple
291 certificates may be registered to the same user. When a certificate is
292 authenticated, Pegasus views it in the same way as if a user was
293 authenticated via basic authentication. The providers
294 receive the username that the certificate was mapped to. See the SSL
295 dave.sudlik 1.3 Authorization section
296 for more information.
297 <p><b>sslTrustStore</b><br>
298 This setting controls the truststore for the cimserver's HTTPS
299 connection. It can be
300 either a directory or a single root CA file. When set to a directory,
301 it is recommended that you use the ssltrustmgr CLI to populate the
302 truststore as there are strict naming requirements for trusted
303 certificate files. See the <a href="#CLI">ssltrustmgr CLI</a>
|
304 h.sterling 1.1 section for further information.
|
305 dave.sudlik 1.3 </p>
306 <p><b>sslTrustStoreUserName</b><br>
307 This setting is only utilized if the sslTrustStore is a single CA file.
308 It is not used if the sslTrustStore setting is a directory, but it
309 still must be set to a valid system user. This is because the
310 validation of the property is done independently of the sslTrustStore
311 setting. This property represents the valid OS user that corresponds to
312 the root certificate. All requests authenticated with a certificate
313 under the root CA will be associated with this user and the username
314 will be propagated to providers. If applications desire for there to be
315 a one-to-one correspondence between users and certificates, it is
316 recommended that each certificate be registered individually using the
317 <a href="#CLI">ssltrustmgr CLI</a>. </p>
318 <p> <b>crlStore</b><br>
319 This is where the CRL (Certificate Revocation List) store resides.
320 There is only one CRL store for all truststores. Currently, only two
321 truststores are supported (cimserver and export) and these both share
322 the same CRL store. It is important to note that certificates are
323 checked first against the CRL (if specified) and then against the
324 truststore. The <a href="#CLI">ssltrustmgr CLI</a> should be used for
325 CRL management. </p>
326 dave.sudlik 1.3 <p><b>enableSSLExportClientVerification</b><br>
327 This setting controls whether an ADDITIONAL port is used to listen for
328 incoming indications. This port is used only as a CIM indication
329 listener
330 and only supports HTTPS. The port number of the export connection is
331 currently not configurable; the port is determined by looking
|
332 h.sterling 1.2 in /etc/services for the service name wbem-exp-https.
|
333 dave.sudlik 1.3 The export port is primarily used as a way to authenticate client
334 indication requests. Because indications are generated by providers
335 and do not have a username/password associated with them, traditional
336 basic authentication cannot be sent in the export request. To work
337 around this, a truststore can be configured to authenticate incoming
338 requests. This truststore is configured like the "required"
|
339 h.sterling 1.1 setting of sslClientVerificationMode.
|
340 dave.sudlik 1.3 </p>
341 <p><b>exportSSLTrustStore</b><br>
342 This setting controls the truststore for the export connection. It may
343 be the same as the sslTrustStore. Additionally, it can be
344 either a directory or a single root CA file. When set to a directory,
345 it is recommended that you use the <a href="#CLI">ssltrustmgr CLI</a>
346 to populate the truststore as there are strict naming requirements for
347 trusted certificate files. </p>
348 <h4>Configuration Limitations</h4>
|
349 h.sterling 1.1 The following are configuration limitations:
|
350 dave.sudlik 1.3 <ul>
351 <li>The x509 server certificate file cannot be encrypted. The reason
352 for this is that there is currently no mechanism in Pegasus to grab the
353 password needed to unencrypt it. Therefore, the best way to secure the
354 file is to follow the file permissions settings specified in <a
355 href="#CERTS">Creating SSL Certificates.</a></li>
356 <li>There is no property to specify supported cipher lists at this
357 time. Pegasus uses the default OpenSSL cipher list. The cipher lists
358 can be found at <a
359 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>
360 and <a
361 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>
362 <li>The verification depth cannot be specified. Pegasus uses the
363 default OpenSSL depth of 9. This means the OpenSSL will only accept
364 client certificate chains up to 9 levels deep.</li>
365 <li>No hostname checking is performed to ensure that the subject
366 field of the distinguished name (DN) matches the hostname.</li>
367 </ul>
368 <h3><a name="DESIGN">SSL Design Question List</a></h3>
369 <p>The following questions may be helpful in determining how to
370 configure Pegasus CIM Server.</p>
371 dave.sudlik 1.3 <b>Should I enable the HTTPS port?</b><br>
372 Yes, especially if you are sending passwords with requests. The HTTP
373 port can be disabled for additional security if desired.
374 <br>
375 <b>Should I enable the export port?</b><br>
376 Currently, the export connection provides the only way to authenticate
377 incoming CIM indication requests. Because basic authentication cannot
378 be used with these requests, the export connection should be enabled if
379 there is a concern over rogue client export requests. Otherwise, the
380 export requests can still be sent over HTTPS using the standard port;
381 the information will be encrypted but the client's identity will not be
382 validated.
383 <br>
384 <b>Should I configure the CIMOM to use a truststore?</b><br>
385 This depends on the infrastructure of the application. If all clients
386 are using basic authentication over the secure port
387 (and the passwords are secured), then a truststore may not be needed.
388 If an application does not want to store user/pw information,
389 then it is a good idea to use a certificate-based infrastructure. If a
390 CIMOM certificate is compromised, the cimserver and the providers
391 of the system are compromised. The severity of this scenario is
392 dave.sudlik 1.3 dependent on the resources the providers have access to. If an OS
393 password is compromised, the entire system may be compromised.
394 If using peer verification, it is important to ensure that 1) the
395 cimserver is properly configured to use a truststore,
396 2) the truststore is loaded properly and protected, and 3)
397 authorization checks are performed after a certificate is verified.
398 These same conditions also apply to a client that is verifying a server.<br>
399 <b>Should I use a self-signed certificate or one issued by a
400 third-party certificate authority?</b><br>
401 Generally, scalability will determine whether it's appropriate to use a
402 self-signed certificate or one issued by Verisign
|
403 h.sterling 1.1 or another third-party certificate authority.
|
404 dave.sudlik 1.3 If an administrator administrates their self-signed certificates
405 correctly, they are no less secure than one issued by a CA. What a CA
406 buys you is scalability. An up front cost of setting up a CA
407 relationship will be offset by the convenience of having that CA
408 "vouch" for certs it has signed, in large deployments. In small
409 deployments the incremental cost might never outweigh the initial
410 CA-setup cost. <br>
411 One important thing to remember is that you should not use the same
412 certificate for multiple CIMOMs. If using a self-signed certificate, a
413 different one should be generated for each CIMOM, using some unique
414 piece of data to make them different. That way, if one of the
415 certificates is compromised, the other ones remain secure. <br>
416 <b>Should the truststore be a single root CA file or a directory?</b><br>
417 If you only anticipate connections from a narrowly defined set of
418 clients, then a single root CA certificate file should be sufficient.
419 Alternatively, multiple trusted certificates may be stored in PEM
420 format inside of a single CA file.
421 If you anticipate getting requests from a heterogeneous set of clients,
422 then it probably makes sense to use the directory option to allow
423 flexibility in the future. In the latter scenario, the same single root
424 CA file can still be used with the additional step of using ssltrustmgr
425 dave.sudlik 1.3 to register it.
426 It's important to note that when registering a root CA, only one user
427 can be associated with ALL certificates under that CA. Following the
428 principle of
429 least privilege, it is not a good idea to register a root CA to a
430 privileged user if lesser privileged users will be connecting with it.
431 <br>
432 <b>How do I protect the keystore and the truststore?</b><br>
433 The server's private key should always be protected; it is private for
434 a reason. Only the system administrator should be able to see it. The
435 public certificate can be viewed by anyone, however, it should be
436 protected from alteration by system users. Similarly, any truststore or
437 CRL file or directory should also be protected from alteration. See <a
438 href="#CERTS">Creating SSL Certificates</a> for the recommended file
439 privileges. <br>
440 <b>When do I need to use a CRL?</b><br>
441 Certificate Revocation Lists are regularly issued by CA's. They contain
442 a list of certificates that have been revoked. Any application using a
443 CA certificate in its truststore should also implement CRLs (if the CA
444 supports them). Pegasus itself
445 does not check CRL validity dates during startup. Therefore, it is the
446 dave.sudlik 1.3 responsibility of the administrator
447 to regularly download or acquire the CRL and import it into the CRL
448 store using the <a href="#CLI">ssltrustmgr CLI</a>.
449 <font style="color: rgb(0, 0, 0);" color="MAGENTA">CRLs are not checked
450 for expiration during the SSL callback. This means that if a CRL for a
451 particular issuer has expired,
452 Pegasus still accepts certificates from the issuer and uses the expired
453 CRL as the latest. Again, it is the responsibility of the administrator
454 to ensure the CRL is up to date. CRLs are not checked for critical
455 extensions during CRL verification. If a CRL contains a critical
456 extension it will be ignored.
457 </font><br>
458 If using self-signed certificates, however, a CRL is most likely not
459 needed (You can create a self-signed CRL but it is not really
460 necessary). Because of this, the certificate deletion option available
461 via ssltrustmgr is primarily intended for self-signed certificates.
462 Technically, CRL's are the correct way to revoke compromised or invalid
463 certificates.
464 <br>
465 <b>What is the order of operations for certificate verification?</b><br>
466 The certificate is checked against any CRLs first before going through
467 dave.sudlik 1.3 the rest of the verification process. Verification starts with the
468 root certificate and continues down to the peer certificate. If
469 verification fails at any of these points, the certificate is
470 considered
|
471 h.sterling 1.1 untrusted and the verification process reports an error.
|
472 dave.sudlik 1.3 <h3><a name="TRUSTSTORE">Truststore Management</a></h3>
473 There are two directions of trust in an SSL client-server handshake:
474 The client trusts the server. The server trusts the client. Pegasus
475 provides a way to implement one or both of these relationships.
476 Ideally, an application should support both levels of trust for maximum
477 security and this is the implementation Pegasus recommends. However, in
478 some scenarios it may make sense to only implement one of these; in
479 that case, it is possible to override the client or the server to
480 "trust all certificates." For example, if all clients will be using
481 basic authentication over HTTPS, then the server can be setup to "trust
482 all client certificates."
483 <p> To tell the cimserver to require that all clients be trusted,
484 simply set the sslClientVerification<font style="color: rgb(0, 0, 0);"
485 color="MAGENTA">Mode</font> property to "required."<br>
486 To tell the cimserver to trust all clients, set the
487 sslClientVerification<font style="color: rgb(0, 0, 0);" color="MAGENTA">Mode</font>
488 property to "disabled" or "optional".
489 </p>
490 <p>The SSL verification in Pegasus is independent of any other
491 authentication mechanism. It can still be utilized when authentication
492 is disabled.
493 dave.sudlik 1.3 When authentication is enabled, the first line of defense is SSL client
494 verification. <font style="color: rgb(0, 0, 0);" color="MAGENTA">
495 In situations where a client is not authenticated by SSL because the
496 client sent no certificate and the setting is "optional", the server
497 will attempt to authenticate the client via another method of
498 authentication . In this case, the authentication mechanism specified
499 by the configuration property "httpAuthType" will be used for remote
500 connections and local authentication will be used for local
501 connections.
502 In situations where a client is not authenticated by SSL because the
503 client certificate was invalid, the handshake will be terminated. <br>
504 <i>Note: Before 2.5.1, in the latter case, authentication would have
505 proceeded in the same way as if the client had sent no certificate. To
506 enable the legacy behavior, the compile-time flag
507 PEGASUS_OVERRIDE_SSL_CERT_VERIFICATION_RESULT should be defined.</i>
508 </font></p>
509 <p>See the <a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a>
510 section below on how to setup the client's truststore.
511 </p>
512 <h3><a name="CLI">ssltrustmgr CLI</a></h3>
513 Pegasus 2.5 comes with a new CLI, ssltrustmgr, that should be used to
514 dave.sudlik 1.3 manage the cimserver's truststore, the export truststore, and the CRL
515 store.
516 The CLI interfaces with a certificate control provider that runs as
517 part of Pegasus's core. It operates on the PG_SSLCertificate and
518 PG_SSLCertificateRevocationList
|
519 h.sterling 1.1 classes in root/pg_internal.
|
520 dave.sudlik 1.3 It is recommended that this CLI be used in place of manual
521 configuration for several reasons:
522 <ul>
523 <li>OpenSSL places strict naming restrictions on certificates and
524 CRLs in a directory (the files are looked up via a subject hash code)</li>
525 <li>Certificate instances are stored in the repository along with the
526 corresponding username. If the certificate is not properly registered,
527 the username mapping will fail.<font color="MAGENTA"> <span
528 style="color: rgb(0, 0, 0);">As of 2.5.1, ssltrustmgr supports the
529 ability to register a certificate without a username for root
530 certificates and intermediate certificates, since these certificates
531 represent a collection of users. In this scenario, each leaf
532 certificate must be registered to an individual user. See the
533 Authorization section for more information on username validation.</span></font>
534 </li>
535 <li><font color="MAGENTA"><span style="color: rgb(0, 0, 0);">The CLI,
536 or more correctly the provider it operates on, supports dynamic
537 deletion of certificates by resetting the cimserver's SSL context.</span>
538 </font> Normally, you would need to stop and start the cimserver to
539 accomplish this.</li>
540 <li>The CLI, or more correctly the provider it operates on, performs
541 dave.sudlik 1.3 a ton of error checking you would not get by manually configuring the
542 stores. This alerts the administrator to various error conditions (e.g.
543 the certificate expired) associated with a certificate or CRL.</li>
544 </ul>
545 The CIMOM must be up and running while executing ssltrustmgr. The
546 ssltrustmgr manpage provides more information on commands and syntax.
547 <h3><a name="CLIENT">Configuring the Pegasus CIM Client for SSL</a></h3>
548 <p> A Pegasus CIM client can be configured to use SSL by using a
549 constructor that takes an SSLContext. The construction of the
550 SSLContext is really what controls the behavior of the client during
551 the SSL handshake. Without going into minute details about what happens
552 under the covers, here is a description of the various SSLContext
553 constructor parameters. The descriptions are written from a client
554 perspective even though the same constructors are utilized by the
555 cimserver HTTPS port and export port. </p>
556 <p> Here's a code snippet that shows how to call a client constructor
557 that connects to a server over SSL and can present its own trusted
558 certificate if the server requests it. In this scenario, the client
559 also checks the server certificate against its truststore and specifies
560 an additional callback in addition to the default one (the
561 user-specified callback is optional and can be set to null).
562 dave.sudlik 1.3 </p>
563 <ul>
564 <font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore,
565 certPath, keyPath, verifyCert, randomFile),</b> username, password); </font>
566 </ul>
567 <p></p>
568 <p> Here's a code snippet that shows how to call a client constructor
569 that connects to a server over SSL and does not possess its own trusted
570 certificate. In this scenario, the client also checks the server
571 certificate against its truststore.
572 </p>
573 <ul>
574 <font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore,
575 NULL, randomFile),</b> username password); </font>
576 </ul>
577 <p></p>
578 <ul>
579 <li><b>trustStore</b> -- This specifies the truststore that the
580 client uses to verify server certificates. It can be String::EMPTY if
581 no truststore exists. </li>
582 <li><b>certPath</b> -- This specifies the x509 certificate of the
583 dave.sudlik 1.3 client that will be sent during an SSL handshake. Note that this
584 certificate will only be sent if the server requests it. If this option
585 is specified, the keyPath parameter must also be specified.</li>
586 <li><b>keyPath</b> -- This specifies the private key of the client.
587 If this option is specified, the certPath parameter must also be
588 specified.</li>
589 <li><b>crlPath</b> -- This specifies an optional CRL store path. The
590 client checks the CRL list first, before attempting any further
591 authentication, including the user-specified callback.</li>
592 <li><b>verifyCert</b> -- This is a user-specified verification
593 callback. If this is set to null, the default OpenSSL verification
594 callback will be executed. You can implement this method to "trust all
595 servers" or to perform additional authentication checks that OpenSSL
596 does not perform by default.</li>
597 <li><b>randomFile</b> -- A file to seed the pseudo random number
598 generator (PRNG).</li>
599 </ul>
600 <p>Here are some general guidelines on implementing peer verification
601 for the client:
602 </p>
603 <ul>
604 dave.sudlik 1.3 <li>The client should enable peer verification by specifying a
605 truststore and (optionally) a user-specified callback function.</li>
606 <li>The client should employ a truststore in order to properly verify
607 the server. The truststore should contain a file or directory of
608 trusted CA certificates. The ssltrustmgr CLI cannot be used to
609 configure client truststores. The trusted certificate(s) should be
610 placed in a protected file or directory specified by the trustStore
611 parameter. Keep in mind that the SSL context generally has to be
612 reloaded to pick up any truststore changes.</li>
613 <li>The client could also use a user-specified callback in addition
614 to the default verification callback, if additional verifications are
615 desired over the normal checks that OpenSSL performs. In most cases,
616 the default verification callback is sufficient for checking server
617 certificates.</li>
618 <li>The client should ensure that adequate entropy is attained.</li>
619 <li>The client should use a CRL store if the truststore contains CA
620 certificates that support one.</li>
621 <li>The client should only use the SSLv3 and TLSv1 protocols. By
622 default, Pegasus is not built with SSLv2 support.</li>
623 <li>The client should perform post-connection checks. </li>
624 <ul>
625 dave.sudlik 1.3 <li>Ensure a certificate was received.</li>
|
626 h.sterling 1.1 <ul>
|
627 dave.sudlik 1.3 <li>WARNING: In some implementations of SSL a NULL server
628 certificate is perfectly valid and authenticates against all trust
629 stores. If the client does not ensure a certificate exists then
630 the client is not providing server authentication and could have a
631 security bulletin class defect.</li>
|
632 h.sterling 1.1 </ul>
|
633 dave.sudlik 1.3 <li>Validate that the certificate received was issued to the host
634 for which the client was attempting to connect.</li>
635 <ul>
636 <li>Ensure that the common name (CN) in the server’s certificate
637 subject matches the host name of the server. For X509v3
638 certificates, the “<span class="SpellE">SubjectAltName</span>” fields
639 in the certificate's extended attributes are also valid host names for
640 the certificate. </li>
641 <li>WARNING: If the client does not ensure the host name of
642 the server is the same as one of the host names explicitly described in
643 the server’s certificate, you have not authenticated the server’s
644 identity. Any other server which was issued a certificate from
645 the same trusted CA can masquerade as the server unless the client
646 performs the host name check.</li>
647 </ul>
648 <li>Ensure that certificate verification methods/routines return no
649 errors.</li>
650 </ul>
651 </ul>
652 <p>
653 Because only the above arguments can be passed into the Pegasus
654 dave.sudlik 1.3 SSLContext, there are some limitations in the client configuration:
655 </p>
656 <ul>
657 <li>The verification depth cannot be specified. Pegasus uses the
658 default OpenSSL depth of 9.</li>
659 <li>The cipher list cannot be specified. Pegasus uses the default
660 OpenSSL cipher list. The cipher lists can be found at <a
661 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>
662 and <a
663 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>
664 <li>No hostname checking is performed to ensure that the subject
665 field of the distinguished name (DN) matches the hostname. If desired,
666 a user-specified callback should be configured to perform this check or
667 any additional checks relevant to the application.</li>
668 </ul>
669 <h3><a name="AUTH">SSL Authorization</a></h3>
670 <p>The following paragraphs concern authorization of users
671 authenticated by certificate on the cimserver's HTTPS port.
672 </p>
673 <p> It is important to note that SSL certificates are verified during
674 the initial handshake, BEFORE any further authentication takes place.
675 dave.sudlik 1.3 If a certificate fails, the connection can be terminated immediately,
676 resulting in a connection exception. This scenario will occur if the
677 sslClientVerification property is set to "required" and no certificate
678 or an untrusted certificate is sent. The export connection will also
679 terminate the connection if an untrusted certificate is presented. Once
680 a certificate is verified, no further <i><b>authentication</b></i> is
681 attempted. This effectively results in any basic or local
682 authentication headers being ignored. </p>
683 <p> Further <i><b>authorization</b></i> checks must be performed when
684 validating the user that is mapped to the certificate. First, the user
685 that is registered to the certificate is validated as a valid system
686 user and a valid cimuser (if the cimuser function has been configured).
687 <font color="magenta"><span style="color: rgb(0, 0, 0);">In the case of
688 a certificate chain, the username authorization starts with the leaf
689 certificate. If it successfully finds a mapping
690 for the leaf certificate, it continues; if there is no username for the
691 leaf certificate, the validation proceeds up to the root certificate.
692 If the root certificate is reached and there is still no mapped
693 username, the authorization fails.</span>
694 </font> Additionally, if Pegasus was configured to use PAM, the
695 pam_acct_mgmt function will be called with the user that is mapped to
696 dave.sudlik 1.3 the certificate. This ensures that any login conditions that would have
697 been placed on a user authenticated via basic authentication are still
698 applied to a user authenticated via certificate. The pam_authenticate
699 method will NOT be called. Lastly, the providers must authorize the
700 user. They receive the username that was mapped to the certificate in
701 the OperationContext. </p>
702 <h3><a name="EXT">Critical Extension Handling</a></h3>
703 <p><font color="MAGENTA"><span style="color: rgb(0, 0, 0);">
704 The extensions defined for X.509 v3 certificates provide methods for
705 associating additional attributes with users or public keys and for
706 managing the certification hierarchy. Each extension in a certificate
707 may be designated as critical or non-critical. Pegasus relies on the
708 underlying OpenSSL implementation to handle critical extensions
709 specified in a certificate. Please refer to the OpenSSL documentation
710 for more information on currently supported extensions in OpenSSL and
711 on the behavior of OpenSSL in the case of unhandled critical extensions.</span>
712 </font></p>
713 <h3><a name="RESOURCES">Resources</a></h3>
714 <p>
715 For OpenSSL information pick up a copy of O'Reilly's Network Security
716 with OpenSSL or go to the OpenSSL Site:<br>
717 dave.sudlik 1.3 <a href="http://www.openssl.org">http://www.openssl.org</a> </p>
718 <p>A really fabulous guide on certificate management and installation
719 with OpenSSL:<br>
720 <a href="http://www.gagravarr.org/writing/openssl-certs/index.shtml">http://www.gagravarr.org/writing/openssl-certs/index.shtml</a>
721 </p>
722 <p>x509 Certificate and CRL RFC:<br>
723 <a href="http://www.ietf.org/rfc/rfc2459.txt?number=2459">http://www.ietf.org/rfc/rfc2459.txt?number=2459</a>
724 </p>
725 <p>SSLv3 RFC:<br>
726 <a href="http://wp.netscape.com/eng/ssl3/">http://wp.netscape.com/eng/ssl3</a>
727 </p>
728 <p>TLSv1 RFC:<br>
729 <a href="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</a>
730 </p>
731 <p>Basic Authentication RFC:<br>
732 <a href="http://www.faqs.org/rfcs/rfc2617.html">http://www.faqs.org/rfcs/rfc2617.html</a>
733 </p>
|
734 h.sterling 1.1 <hr>
|
735 dave.sudlik 1.3 <p><i><font size="2">Copyright (c) 2005 EMC Corporation;
736 Hewlett-Packard Development Company, L.P.; IBM Corp.; The Open Group;
737 VERITAS Software Corporation</font><br>
|
738 h.sterling 1.1 <br>
|
739 dave.sudlik 1.3 <font size="1">Permission is hereby granted, free of charge, to any
740 person obtaining a copy of this software and associated
741 documentation files (the "Software"), to deal in the Software without
742 restriction, including without limitation the rights to use, copy,
743 modify, merge, publish, distribute, sublicense, and/or sell copies of
744 the Software, and to permit persons to whom the Software is furnished
745 to do so, subject to the following conditions:</font><br>
|
746 h.sterling 1.1 <font size="2"><br>
747 </font>
|
748 dave.sudlik 1.3 <font size="1">THE ABOVE COPYRIGHT NOTICE AND THIS PERMISSION NOTICE
749 SHALL BE INCLUDED IN ALL COPIES OR SUBSTANTIAL PORTIONS OF THE
750 SOFTWARE. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
751 ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
752 WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
753 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
754 LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
755 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
756 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</font></i></p>
|
757 h.sterling 1.1 <hr>
|
758 dave.sudlik 1.3 </body>
759 </html>
|
Return to
PegasusSSLGuidelines.htm
CVS log
Up to [Pegasus] / pegasus / doc