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