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 karl 1.6.8.1 <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 dave.sudlik 1.3 <h4>Configuration Limitations</h4>
|
330 h.sterling 1.1 The following are configuration limitations:
|
331 dave.sudlik 1.3 <ul>
332 <li>The x509 server certificate file cannot be encrypted. The reason
333 for this is that there is currently no mechanism in Pegasus to grab the
334 password needed to unencrypt it. Therefore, the best way to secure the
335 file is to follow the file permissions settings specified in <a
336 href="#CERTS">Creating SSL Certificates.</a></li>
337 <li>The verification depth cannot be specified. Pegasus uses the
338 default OpenSSL depth of 9. This means the OpenSSL will only accept
339 client certificate chains up to 9 levels deep.</li>
340 <li>No hostname checking is performed to ensure that the subject
341 field of the distinguished name (DN) matches the hostname.</li>
342 </ul>
343 <h3><a name="DESIGN">SSL Design Question List</a></h3>
344 <p>The following questions may be helpful in determining how to
345 configure Pegasus CIM Server.</p>
346 <b>Should I enable the HTTPS port?</b><br>
347 Yes, especially if you are sending passwords with requests. The HTTP
348 port can be disabled for additional security if desired.
349 <br>
350 <b>Should I configure the CIMOM to use a truststore?</b><br>
351 This depends on the infrastructure of the application. If all clients
352 dave.sudlik 1.3 are using basic authentication over the secure port
353 (and the passwords are secured), then a truststore may not be needed.
354 If an application does not want to store user/pw information,
355 then it is a good idea to use a certificate-based infrastructure. If a
356 CIMOM certificate is compromised, the cimserver and the providers
357 of the system are compromised. The severity of this scenario is
358 dependent on the resources the providers have access to. If an OS
359 password is compromised, the entire system may be compromised.
360 If using peer verification, it is important to ensure that 1) the
361 cimserver is properly configured to use a truststore,
362 2) the truststore is loaded properly and protected, and 3)
363 authorization checks are performed after a certificate is verified.
364 These same conditions also apply to a client that is verifying a server.<br>
365 <b>Should I use a self-signed certificate or one issued by a
366 third-party certificate authority?</b><br>
367 Generally, scalability will determine whether it's appropriate to use a
368 self-signed certificate or one issued by Verisign
|
369 h.sterling 1.1 or another third-party certificate authority.
|
370 dave.sudlik 1.3 If an administrator administrates their self-signed certificates
371 correctly, they are no less secure than one issued by a CA. What a CA
372 buys you is scalability. An up front cost of setting up a CA
373 relationship will be offset by the convenience of having that CA
374 "vouch" for certs it has signed, in large deployments. In small
375 deployments the incremental cost might never outweigh the initial
376 CA-setup cost. <br>
377 One important thing to remember is that you should not use the same
378 certificate for multiple CIMOMs. If using a self-signed certificate, a
379 different one should be generated for each CIMOM, using some unique
380 piece of data to make them different. That way, if one of the
381 certificates is compromised, the other ones remain secure. <br>
382 <b>Should the truststore be a single root CA file or a directory?</b><br>
383 If you only anticipate connections from a narrowly defined set of
384 clients, then a single root CA certificate file should be sufficient.
385 Alternatively, multiple trusted certificates may be stored in PEM
386 format inside of a single CA file.
387 If you anticipate getting requests from a heterogeneous set of clients,
388 then it probably makes sense to use the directory option to allow
389 flexibility in the future. In the latter scenario, the same single root
|
390 sushma.fernandes 1.4 CA file can still be used with the additional step of using cimtrust
|
391 dave.sudlik 1.3 to register it.
392 It's important to note that when registering a root CA, only one user
393 can be associated with ALL certificates under that CA. Following the
394 principle of
395 least privilege, it is not a good idea to register a root CA to a
396 privileged user if lesser privileged users will be connecting with it.
397 <br>
398 <b>How do I protect the keystore and the truststore?</b><br>
399 The server's private key should always be protected; it is private for
400 a reason. Only the system administrator should be able to see it. The
401 public certificate can be viewed by anyone, however, it should be
402 protected from alteration by system users. Similarly, any truststore or
403 CRL file or directory should also be protected from alteration. See <a
404 href="#CERTS">Creating SSL Certificates</a> for the recommended file
405 privileges. <br>
406 <b>When do I need to use a CRL?</b><br>
407 Certificate Revocation Lists are regularly issued by CA's. They contain
408 a list of certificates that have been revoked. Any application using a
409 CA certificate in its truststore should also implement CRLs (if the CA
410 supports them). Pegasus itself
411 does not check CRL validity dates during startup. Therefore, it is the
412 dave.sudlik 1.3 responsibility of the administrator
413 to regularly download or acquire the CRL and import it into the CRL
|
414 sushma.fernandes 1.4 store using the <a href="#CLI">cimcrl CLI</a>.
|
415 dave.sudlik 1.3 <font style="color: rgb(0, 0, 0);" color="MAGENTA">CRLs are not checked
416 for expiration during the SSL callback. This means that if a CRL for a
417 particular issuer has expired,
418 Pegasus still accepts certificates from the issuer and uses the expired
419 CRL as the latest. Again, it is the responsibility of the administrator
420 to ensure the CRL is up to date. CRLs are not checked for critical
421 extensions during CRL verification. If a CRL contains a critical
422 extension it will be ignored.
423 </font><br>
424 If using self-signed certificates, however, a CRL is most likely not
425 needed (You can create a self-signed CRL but it is not really
426 necessary). Because of this, the certificate deletion option available
|
427 sushma.fernandes 1.4 via cimtrust is primarily intended for self-signed certificates.
|
428 dave.sudlik 1.3 Technically, CRL's are the correct way to revoke compromised or invalid
429 certificates.
430 <br>
431 <b>What is the order of operations for certificate verification?</b><br>
432 The certificate is checked against any CRLs first before going through
433 the rest of the verification process. Verification starts with the
434 root certificate and continues down to the peer certificate. If
435 verification fails at any of these points, the certificate is
436 considered
|
437 h.sterling 1.1 untrusted and the verification process reports an error.
|
438 dave.sudlik 1.3 <h3><a name="TRUSTSTORE">Truststore Management</a></h3>
439 There are two directions of trust in an SSL client-server handshake:
440 The client trusts the server. The server trusts the client. Pegasus
441 provides a way to implement one or both of these relationships.
442 Ideally, an application should support both levels of trust for maximum
443 security and this is the implementation Pegasus recommends. However, in
444 some scenarios it may make sense to only implement one of these; in
445 that case, it is possible to override the client or the server to
446 "trust all certificates." For example, if all clients will be using
447 basic authentication over HTTPS, then the server can be setup to "trust
448 all client certificates."
449 <p> To tell the cimserver to require that all clients be trusted,
450 simply set the sslClientVerification<font style="color: rgb(0, 0, 0);"
451 color="MAGENTA">Mode</font> property to "required."<br>
452 To tell the cimserver to trust all clients, set the
453 sslClientVerification<font style="color: rgb(0, 0, 0);" color="MAGENTA">Mode</font>
454 property to "disabled" or "optional".
455 </p>
456 <p>The SSL verification in Pegasus is independent of any other
457 authentication mechanism. It can still be utilized when authentication
458 is disabled.
459 dave.sudlik 1.3 When authentication is enabled, the first line of defense is SSL client
460 verification. <font style="color: rgb(0, 0, 0);" color="MAGENTA">
461 In situations where a client is not authenticated by SSL because the
462 client sent no certificate and the setting is "optional", the server
463 will attempt to authenticate the client via another method of
464 authentication . In this case, the authentication mechanism specified
465 by the configuration property "httpAuthType" will be used for remote
466 connections and local authentication will be used for local
467 connections.
468 In situations where a client is not authenticated by SSL because the
469 client certificate was invalid, the handshake will be terminated. <br>
470 <i>Note: Before 2.5.1, in the latter case, authentication would have
471 proceeded in the same way as if the client had sent no certificate. To
472 enable the legacy behavior, the compile-time flag
473 PEGASUS_OVERRIDE_SSL_CERT_VERIFICATION_RESULT should be defined.</i>
474 </font></p>
475 <p>See the <a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a>
476 section below on how to setup the client's truststore.
477 </p>
|
478 sushma.fernandes 1.4 <h3><a name="CLI">cimtrust & cimcrl CLI</a></h3>
|
479 kumpf 1.5 cimtrust CLI may be used to add, remove or list X509 certificates in a
|
480 sushma.fernandes 1.4 PEM format truststore. cimcrl CLI may be used to add, remove or list
481 X509 Certificate Revocation Lists in a PEM format CRL store.
482
483 The CLIs interface with a Certificate control provider that runs as
|
484 dave.sudlik 1.3 part of Pegasus's core. It operates on the PG_SSLCertificate and
|
485 sushma.fernandes 1.4 PG_SSLCertificateRevocationList classes in root/PG_Internal.
486 It is recommended that the CLIs be used in place of manual
|
487 dave.sudlik 1.3 configuration for several reasons:
488 <ul>
489 <li>OpenSSL places strict naming restrictions on certificates and
490 CRLs in a directory (the files are looked up via a subject hash code)</li>
491 <li>Certificate instances are stored in the repository along with the
492 corresponding username. If the certificate is not properly registered,
493 the username mapping will fail.<font color="MAGENTA"> <span
|
494 sushma.fernandes 1.4 style="color: rgb(0, 0, 0);">cimtrust CLI supports the
|
495 dave.sudlik 1.3 ability to register a certificate without a username for root
496 certificates and intermediate certificates, since these certificates
497 represent a collection of users. In this scenario, each leaf
498 certificate must be registered to an individual user. See the
499 Authorization section for more information on username validation.</span></font>
500 </li>
|
501 sushma.fernandes 1.4 <li><font color="MAGENTA"><span style="color: rgb(0, 0, 0);">The CLIs,
502 or more correctly the provider they operate on, supports dynamic
|
503 dave.sudlik 1.3 deletion of certificates by resetting the cimserver's SSL context.</span>
504 </font> Normally, you would need to stop and start the cimserver to
505 accomplish this.</li>
|
506 sushma.fernandes 1.4 <li>The CLIs, or more correctly the provider they operate on, performs
|
507 dave.sudlik 1.3 a ton of error checking you would not get by manually configuring the
508 stores. This alerts the administrator to various error conditions (e.g.
509 the certificate expired) associated with a certificate or CRL.</li>
510 </ul>
|
511 sushma.fernandes 1.4 The CIMOM must be up and running while executing cimtrust/cimcrl CLI. The
512 cimtrust and cimcrl manpages provide more information on commands and syntax.
|
513 dave.sudlik 1.3 <h3><a name="CLIENT">Configuring the Pegasus CIM Client for SSL</a></h3>
514 <p> A Pegasus CIM client can be configured to use SSL by using a
515 constructor that takes an SSLContext. The construction of the
516 SSLContext is really what controls the behavior of the client during
517 the SSL handshake. Without going into minute details about what happens
518 under the covers, here is a description of the various SSLContext
|
519 sushma.fernandes 1.4 constructor parameters. </p>
|
520 dave.sudlik 1.3 <p> Here's a code snippet that shows how to call a client constructor
521 that connects to a server over SSL and can present its own trusted
522 certificate if the server requests it. In this scenario, the client
523 also checks the server certificate against its truststore and specifies
524 an additional callback in addition to the default one (the
525 user-specified callback is optional and can be set to null).
526 </p>
527 <ul>
528 <font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore,
|
529 karl 1.6.8.1 certPath, keyPath, verifyCert, randomFile, cipherSuite),</b> username, password); </font>
|
530 dave.sudlik 1.3 </ul>
531 <p></p>
532 <p> Here's a code snippet that shows how to call a client constructor
533 that connects to a server over SSL and does not possess its own trusted
534 certificate. In this scenario, the client also checks the server
535 certificate against its truststore.
536 </p>
537 <ul>
538 <font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore,
539 NULL, randomFile),</b> username password); </font>
540 </ul>
541 <p></p>
542 <ul>
543 <li><b>trustStore</b> -- This specifies the truststore that the
544 client uses to verify server certificates. It can be String::EMPTY if
545 no truststore exists. </li>
546 <li><b>certPath</b> -- This specifies the x509 certificate of the
547 client that will be sent during an SSL handshake. Note that this
548 certificate will only be sent if the server requests it. If this option
549 is specified, the keyPath parameter must also be specified.</li>
550 <li><b>keyPath</b> -- This specifies the private key of the client.
551 dave.sudlik 1.3 If this option is specified, the certPath parameter must also be
552 specified.</li>
553 <li><b>crlPath</b> -- This specifies an optional CRL store path. The
554 client checks the CRL list first, before attempting any further
555 authentication, including the user-specified callback.</li>
556 <li><b>verifyCert</b> -- This is a user-specified verification
557 callback. If this is set to null, the default OpenSSL verification
558 callback will be executed. You can implement this method to "trust all
559 servers" or to perform additional authentication checks that OpenSSL
560 does not perform by default.</li>
561 <li><b>randomFile</b> -- A file to seed the pseudo random number
562 generator (PRNG).</li>
|
563 karl 1.6.8.1 <li><b>cipherSuite</b> -- This specifies the cipher list used by the
564 client during the SSL handshake phase. This is an experimental
565 interface.</li>
|
566 dave.sudlik 1.3 </ul>
567 <p>Here are some general guidelines on implementing peer verification
568 for the client:
569 </p>
570 <ul>
571 <li>The client should enable peer verification by specifying a
572 truststore and (optionally) a user-specified callback function.</li>
573 <li>The client should employ a truststore in order to properly verify
574 the server. The truststore should contain a file or directory of
|
575 sushma.fernandes 1.4 trusted CA certificates. The cimtrust CLI cannot be used to
|
576 dave.sudlik 1.3 configure client truststores. The trusted certificate(s) should be
577 placed in a protected file or directory specified by the trustStore
578 parameter. Keep in mind that the SSL context generally has to be
579 reloaded to pick up any truststore changes.</li>
580 <li>The client could also use a user-specified callback in addition
581 to the default verification callback, if additional verifications are
582 desired over the normal checks that OpenSSL performs. In most cases,
583 the default verification callback is sufficient for checking server
584 certificates.</li>
585 <li>The client should ensure that adequate entropy is attained.</li>
586 <li>The client should use a CRL store if the truststore contains CA
587 certificates that support one.</li>
588 <li>The client should only use the SSLv3 and TLSv1 protocols. By
589 default, Pegasus is not built with SSLv2 support.</li>
590 <li>The client should perform post-connection checks. </li>
591 <ul>
592 <li>Ensure a certificate was received.</li>
|
593 h.sterling 1.1 <ul>
|
594 dave.sudlik 1.3 <li>WARNING: In some implementations of SSL a NULL server
595 certificate is perfectly valid and authenticates against all trust
596 stores. If the client does not ensure a certificate exists then
597 the client is not providing server authentication and could have a
598 security bulletin class defect.</li>
|
599 h.sterling 1.1 </ul>
|
600 dave.sudlik 1.3 <li>Validate that the certificate received was issued to the host
601 for which the client was attempting to connect.</li>
602 <ul>
603 <li>Ensure that the common name (CN) in the server’s certificate
604 subject matches the host name of the server. For X509v3
605 certificates, the “<span class="SpellE">SubjectAltName</span>” fields
606 in the certificate's extended attributes are also valid host names for
607 the certificate. </li>
608 <li>WARNING: If the client does not ensure the host name of
609 the server is the same as one of the host names explicitly described in
610 the server’s certificate, you have not authenticated the server’s
611 identity. Any other server which was issued a certificate from
612 the same trusted CA can masquerade as the server unless the client
613 performs the host name check.</li>
614 </ul>
615 <li>Ensure that certificate verification methods/routines return no
616 errors.</li>
617 </ul>
618 </ul>
619 <p>
620 Because only the above arguments can be passed into the Pegasus
621 dave.sudlik 1.3 SSLContext, there are some limitations in the client configuration:
622 </p>
623 <ul>
624 <li>The verification depth cannot be specified. Pegasus uses the
625 default OpenSSL depth of 9.</li>
626 <li>No hostname checking is performed to ensure that the subject
627 field of the distinguished name (DN) matches the hostname. If desired,
628 a user-specified callback should be configured to perform this check or
629 any additional checks relevant to the application.</li>
630 </ul>
631 <h3><a name="AUTH">SSL Authorization</a></h3>
632 <p>The following paragraphs concern authorization of users
633 authenticated by certificate on the cimserver's HTTPS port.
634 </p>
635 <p> It is important to note that SSL certificates are verified during
636 the initial handshake, BEFORE any further authentication takes place.
637 If a certificate fails, the connection can be terminated immediately,
638 resulting in a connection exception. This scenario will occur if the
639 sslClientVerification property is set to "required" and no certificate
|
640 sushma.fernandes 1.4 or an untrusted certificate is sent. </p>
|
641 dave.sudlik 1.3 <p> Further <i><b>authorization</b></i> checks must be performed when
642 validating the user that is mapped to the certificate. First, the user
643 that is registered to the certificate is validated as a valid system
644 user and a valid cimuser (if the cimuser function has been configured).
645 <font color="magenta"><span style="color: rgb(0, 0, 0);">In the case of
646 a certificate chain, the username authorization starts with the leaf
647 certificate. If it successfully finds a mapping
648 for the leaf certificate, it continues; if there is no username for the
649 leaf certificate, the validation proceeds up to the root certificate.
650 If the root certificate is reached and there is still no mapped
651 username, the authorization fails.</span>
652 </font> Additionally, if Pegasus was configured to use PAM, the
653 pam_acct_mgmt function will be called with the user that is mapped to
654 the certificate. This ensures that any login conditions that would have
655 been placed on a user authenticated via basic authentication are still
656 applied to a user authenticated via certificate. The pam_authenticate
657 method will NOT be called. Lastly, the providers must authorize the
658 user. They receive the username that was mapped to the certificate in
659 the OperationContext. </p>
660 <h3><a name="EXT">Critical Extension Handling</a></h3>
661 <p><font color="MAGENTA"><span style="color: rgb(0, 0, 0);">
662 dave.sudlik 1.3 The extensions defined for X.509 v3 certificates provide methods for
663 associating additional attributes with users or public keys and for
664 managing the certification hierarchy. Each extension in a certificate
665 may be designated as critical or non-critical. Pegasus relies on the
666 underlying OpenSSL implementation to handle critical extensions
667 specified in a certificate. Please refer to the OpenSSL documentation
668 for more information on currently supported extensions in OpenSSL and
669 on the behavior of OpenSSL in the case of unhandled critical extensions.</span>
670 </font></p>
671 <h3><a name="RESOURCES">Resources</a></h3>
672 <p>
673 For OpenSSL information pick up a copy of O'Reilly's Network Security
674 with OpenSSL or go to the OpenSSL Site:<br>
675 <a href="http://www.openssl.org">http://www.openssl.org</a> </p>
676 <p>A really fabulous guide on certificate management and installation
677 with OpenSSL:<br>
678 <a href="http://www.gagravarr.org/writing/openssl-certs/index.shtml">http://www.gagravarr.org/writing/openssl-certs/index.shtml</a>
679 </p>
680 <p>x509 Certificate and CRL RFC:<br>
681 <a href="http://www.ietf.org/rfc/rfc2459.txt?number=2459">http://www.ietf.org/rfc/rfc2459.txt?number=2459</a>
682 </p>
683 dave.sudlik 1.3 <p>SSLv3 RFC:<br>
684 <a href="http://wp.netscape.com/eng/ssl3/">http://wp.netscape.com/eng/ssl3</a>
685 </p>
686 <p>TLSv1 RFC:<br>
687 <a href="http://www.ietf.org/rfc/rfc2246.txt">http://www.ietf.org/rfc/rfc2246.txt</a>
688 </p>
689 <p>Basic Authentication RFC:<br>
690 <a href="http://www.faqs.org/rfcs/rfc2617.html">http://www.faqs.org/rfcs/rfc2617.html</a>
691 </p>
|
692 h.sterling 1.1 <hr>
|
693 martin 1.6 <p>Licensed to The Open Group (TOG) under one or more contributor license
694 agreements. Refer to the OpenPegasusNOTICE.txt file distributed with
695 this work for additional information regarding copyright ownership.
696 Each contributor licenses this file to you under the OpenPegasus Open
697 Source License; you may not use this file except in compliance with the
698 License.</p>
699 <p>Permission is hereby granted, free of charge, to any person obtaining a
700 copy of this software and associated documentation files (the "Software"),
701 to deal in the Software without restriction, including without limitation
702 the rights to use, copy, modify, merge, publish, distribute, sublicense,
703 and/or sell copies of the Software, and to permit persons to whom the
704 Software is furnished to do so, subject to the following conditions:</p>
705 <p>The above copyright notice and this permission notice shall be included
706 in all copies or substantial portions of the Software.</p>
707 <p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
708 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
709 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
710 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
711 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
712 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
713 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
|
714 h.sterling 1.1 <hr>
|
715 dave.sudlik 1.3 </body>
716 </html>
|
Return to
PegasusSSLGuidelines.htm
CVS log
Up to [Pegasus] / pegasus / doc