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