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 <h4>Configuration Limitations</h4>
|
322 h.sterling 1.1 The following are configuration limitations:
|
323 dave.sudlik 1.3 <ul>
324 <li>The x509 server certificate file cannot be encrypted. The reason
325 for this is that there is currently no mechanism in Pegasus to grab the
326 password needed to unencrypt it. Therefore, the best way to secure the
327 file is to follow the file permissions settings specified in <a
328 href="#CERTS">Creating SSL Certificates.</a></li>
329 <li>There is no property to specify supported cipher lists at this
330 time. Pegasus uses the default OpenSSL cipher list. The cipher lists
331 can be found at <a
332 href="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</a>
333 and <a
334 href="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</a></li>
335 <li>The verification depth cannot be specified. Pegasus uses the
336 default OpenSSL depth of 9. This means the OpenSSL will only accept
337 client certificate chains up to 9 levels deep.</li>
338 <li>No hostname checking is performed to ensure that the subject
339 field of the distinguished name (DN) matches the hostname.</li>
340 </ul>
341 <h3><a name="DESIGN">SSL Design Question List</a></h3>
342 <p>The following questions may be helpful in determining how to
343 configure Pegasus CIM Server.</p>
344 dave.sudlik 1.3 <b>Should I enable the HTTPS port?</b><br>
345 Yes, especially if you are sending passwords with requests. The HTTP
346 port can be disabled for additional security if desired.
347 <br>
348 <b>Should I configure the CIMOM to use a truststore?</b><br>
349 This depends on the infrastructure of the application. If all clients
350 are using basic authentication over the secure port
351 (and the passwords are secured), then a truststore may not be needed.
352 If an application does not want to store user/pw information,
353 then it is a good idea to use a certificate-based infrastructure. If a
354 CIMOM certificate is compromised, the cimserver and the providers
355 of the system are compromised. The severity of this scenario is
356 dependent on the resources the providers have access to. If an OS
357 password is compromised, the entire system may be compromised.
358 If using peer verification, it is important to ensure that 1) the
359 cimserver is properly configured to use a truststore,
360 2) the truststore is loaded properly and protected, and 3)
361 authorization checks are performed after a certificate is verified.
362 These same conditions also apply to a client that is verifying a server.<br>
363 <b>Should I use a self-signed certificate or one issued by a
364 third-party certificate authority?</b><br>
365 dave.sudlik 1.3 Generally, scalability will determine whether it's appropriate to use a
366 self-signed certificate or one issued by Verisign
|
367 h.sterling 1.1 or another third-party certificate authority.
|
368 dave.sudlik 1.3 If an administrator administrates their self-signed certificates
369 correctly, they are no less secure than one issued by a CA. What a CA
370 buys you is scalability. An up front cost of setting up a CA
371 relationship will be offset by the convenience of having that CA
372 "vouch" for certs it has signed, in large deployments. In small
373 deployments the incremental cost might never outweigh the initial
374 CA-setup cost. <br>
375 One important thing to remember is that you should not use the same
376 certificate for multiple CIMOMs. If using a self-signed certificate, a
377 different one should be generated for each CIMOM, using some unique
378 piece of data to make them different. That way, if one of the
379 certificates is compromised, the other ones remain secure. <br>
380 <b>Should the truststore be a single root CA file or a directory?</b><br>
381 If you only anticipate connections from a narrowly defined set of
382 clients, then a single root CA certificate file should be sufficient.
383 Alternatively, multiple trusted certificates may be stored in PEM
384 format inside of a single CA file.
385 If you anticipate getting requests from a heterogeneous set of clients,
386 then it probably makes sense to use the directory option to allow
387 flexibility in the future. In the latter scenario, the same single root
|
388 sushma.fernandes 1.4 CA file can still be used with the additional step of using cimtrust
|
389 dave.sudlik 1.3 to register it.
390 It's important to note that when registering a root CA, only one user
391 can be associated with ALL certificates under that CA. Following the
392 principle of
393 least privilege, it is not a good idea to register a root CA to a
394 privileged user if lesser privileged users will be connecting with it.
395 <br>
396 <b>How do I protect the keystore and the truststore?</b><br>
397 The server's private key should always be protected; it is private for
398 a reason. Only the system administrator should be able to see it. The
399 public certificate can be viewed by anyone, however, it should be
400 protected from alteration by system users. Similarly, any truststore or
401 CRL file or directory should also be protected from alteration. See <a
402 href="#CERTS">Creating SSL Certificates</a> for the recommended file
403 privileges. <br>
404 <b>When do I need to use a CRL?</b><br>
405 Certificate Revocation Lists are regularly issued by CA's. They contain
406 a list of certificates that have been revoked. Any application using a
407 CA certificate in its truststore should also implement CRLs (if the CA
408 supports them). Pegasus itself
409 does not check CRL validity dates during startup. Therefore, it is the
410 dave.sudlik 1.3 responsibility of the administrator
411 to regularly download or acquire the CRL and import it into the CRL
|
412 sushma.fernandes 1.4 store using the <a href="#CLI">cimcrl CLI</a>.
|
413 dave.sudlik 1.3 <font style="color: rgb(0, 0, 0);" color="MAGENTA">CRLs are not checked
414 for expiration during the SSL callback. This means that if a CRL for a
415 particular issuer has expired,
416 Pegasus still accepts certificates from the issuer and uses the expired
417 CRL as the latest. Again, it is the responsibility of the administrator
418 to ensure the CRL is up to date. CRLs are not checked for critical
419 extensions during CRL verification. If a CRL contains a critical
420 extension it will be ignored.
421 </font><br>
422 If using self-signed certificates, however, a CRL is most likely not
423 needed (You can create a self-signed CRL but it is not really
424 necessary). Because of this, the certificate deletion option available
|
425 sushma.fernandes 1.4 via cimtrust is primarily intended for self-signed certificates.
|
426 dave.sudlik 1.3 Technically, CRL's are the correct way to revoke compromised or invalid
427 certificates.
428 <br>
429 <b>What is the order of operations for certificate verification?</b><br>
430 The certificate is checked against any CRLs first before going through
431 the rest of the verification process. Verification starts with the
432 root certificate and continues down to the peer certificate. If
433 verification fails at any of these points, the certificate is
434 considered
|
435 h.sterling 1.1 untrusted and the verification process reports an error.
|
436 dave.sudlik 1.3 <h3><a name="TRUSTSTORE">Truststore Management</a></h3>
437 There are two directions of trust in an SSL client-server handshake:
438 The client trusts the server. The server trusts the client. Pegasus
439 provides a way to implement one or both of these relationships.
440 Ideally, an application should support both levels of trust for maximum
441 security and this is the implementation Pegasus recommends. However, in
442 some scenarios it may make sense to only implement one of these; in
443 that case, it is possible to override the client or the server to
444 "trust all certificates." For example, if all clients will be using
445 basic authentication over HTTPS, then the server can be setup to "trust
446 all client certificates."
447 <p> To tell the cimserver to require that all clients be trusted,
448 simply set the sslClientVerification<font style="color: rgb(0, 0, 0);"
449 color="MAGENTA">Mode</font> property to "required."<br>
450 To tell the cimserver to trust all clients, set the
451 sslClientVerification<font style="color: rgb(0, 0, 0);" color="MAGENTA">Mode</font>
452 property to "disabled" or "optional".
453 </p>
454 <p>The SSL verification in Pegasus is independent of any other
455 authentication mechanism. It can still be utilized when authentication
456 is disabled.
457 dave.sudlik 1.3 When authentication is enabled, the first line of defense is SSL client
458 verification. <font style="color: rgb(0, 0, 0);" color="MAGENTA">
459 In situations where a client is not authenticated by SSL because the
460 client sent no certificate and the setting is "optional", the server
461 will attempt to authenticate the client via another method of
462 authentication . In this case, the authentication mechanism specified
463 by the configuration property "httpAuthType" will be used for remote
464 connections and local authentication will be used for local
465 connections.
466 In situations where a client is not authenticated by SSL because the
467 client certificate was invalid, the handshake will be terminated. <br>
468 <i>Note: Before 2.5.1, in the latter case, authentication would have
469 proceeded in the same way as if the client had sent no certificate. To
470 enable the legacy behavior, the compile-time flag
471 PEGASUS_OVERRIDE_SSL_CERT_VERIFICATION_RESULT should be defined.</i>
472 </font></p>
473 <p>See the <a href="#CLIENT">Configuring the Pegasus CIM Client for SSL</a>
474 section below on how to setup the client's truststore.
475 </p>
|
476 sushma.fernandes 1.4 <h3><a name="CLI">cimtrust & cimcrl CLI</a></h3>
|
477 kumpf 1.5 cimtrust CLI may be used to add, remove or list X509 certificates in a
|
478 sushma.fernandes 1.4 PEM format truststore. cimcrl CLI may be used to add, remove or list
479 X509 Certificate Revocation Lists in a PEM format CRL store.
480
481 The CLIs interface with a Certificate control provider that runs as
|
482 dave.sudlik 1.3 part of Pegasus's core. It operates on the PG_SSLCertificate and
|
483 sushma.fernandes 1.4 PG_SSLCertificateRevocationList classes in root/PG_Internal.
484 It is recommended that the CLIs be used in place of manual
|
485 dave.sudlik 1.3 configuration for several reasons:
486 <ul>
487 <li>OpenSSL places strict naming restrictions on certificates and
488 CRLs in a directory (the files are looked up via a subject hash code)</li>
489 <li>Certificate instances are stored in the repository along with the
490 corresponding username. If the certificate is not properly registered,
491 the username mapping will fail.<font color="MAGENTA"> <span
|
492 sushma.fernandes 1.4 style="color: rgb(0, 0, 0);">cimtrust CLI supports the
|
493 dave.sudlik 1.3 ability to register a certificate without a username for root
494 certificates and intermediate certificates, since these certificates
495 represent a collection of users. In this scenario, each leaf
496 certificate must be registered to an individual user. See the
497 Authorization section for more information on username validation.</span></font>
498 </li>
|
499 sushma.fernandes 1.4 <li><font color="MAGENTA"><span style="color: rgb(0, 0, 0);">The CLIs,
500 or more correctly the provider they operate on, supports dynamic
|
501 dave.sudlik 1.3 deletion of certificates by resetting the cimserver's SSL context.</span>
502 </font> Normally, you would need to stop and start the cimserver to
503 accomplish this.</li>
|
504 sushma.fernandes 1.4 <li>The CLIs, or more correctly the provider they operate on, performs
|
505 dave.sudlik 1.3 a ton of error checking you would not get by manually configuring the
506 stores. This alerts the administrator to various error conditions (e.g.
507 the certificate expired) associated with a certificate or CRL.</li>
508 </ul>
|
509 sushma.fernandes 1.4 The CIMOM must be up and running while executing cimtrust/cimcrl CLI. The
510 cimtrust and cimcrl manpages provide more information on commands and syntax.
|
511 dave.sudlik 1.3 <h3><a name="CLIENT">Configuring the Pegasus CIM Client for SSL</a></h3>
512 <p> A Pegasus CIM client can be configured to use SSL by using a
513 constructor that takes an SSLContext. The construction of the
514 SSLContext is really what controls the behavior of the client during
515 the SSL handshake. Without going into minute details about what happens
516 under the covers, here is a description of the various SSLContext
|
517 sushma.fernandes 1.4 constructor parameters. </p>
|
518 dave.sudlik 1.3 <p> Here's a code snippet that shows how to call a client constructor
519 that connects to a server over SSL and can present its own trusted
520 certificate if the server requests it. In this scenario, the client
521 also checks the server certificate against its truststore and specifies
522 an additional callback in addition to the default one (the
523 user-specified callback is optional and can be set to null).
524 </p>
525 <ul>
526 <font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore,
527 certPath, keyPath, verifyCert, randomFile),</b> username, password); </font>
528 </ul>
529 <p></p>
530 <p> Here's a code snippet that shows how to call a client constructor
531 that connects to a server over SSL and does not possess its own trusted
532 certificate. In this scenario, the client also checks the server
533 certificate against its truststore.
534 </p>
535 <ul>
536 <font face="courier"> client.connect( hostname, port, <b>SSLContext(trustStore,
537 NULL, randomFile),</b> username password); </font>
538 </ul>
539 dave.sudlik 1.3 <p></p>
540 <ul>
541 <li><b>trustStore</b> -- This specifies the truststore that the
542 client uses to verify server certificates. It can be String::EMPTY if
543 no truststore exists. </li>
544 <li><b>certPath</b> -- This specifies the x509 certificate of the
545 client that will be sent during an SSL handshake. Note that this
546 certificate will only be sent if the server requests it. If this option
547 is specified, the keyPath parameter must also be specified.</li>
548 <li><b>keyPath</b> -- This specifies the private key of the client.
549 If this option is specified, the certPath parameter must also be
550 specified.</li>
551 <li><b>crlPath</b> -- This specifies an optional CRL store path. The
552 client checks the CRL list first, before attempting any further
553 authentication, including the user-specified callback.</li>
554 <li><b>verifyCert</b> -- This is a user-specified verification
555 callback. If this is set to null, the default OpenSSL verification
556 callback will be executed. You can implement this method to "trust all
557 servers" or to perform additional authentication checks that OpenSSL
558 does not perform by default.</li>
559 <li><b>randomFile</b> -- A file to seed the pseudo random number
560 dave.sudlik 1.3 generator (PRNG).</li>
561 </ul>
562 <p>Here are some general guidelines on implementing peer verification
563 for the client:
564 </p>
565 <ul>
566 <li>The client should enable peer verification by specifying a
567 truststore and (optionally) a user-specified callback function.</li>
568 <li>The client should employ a truststore in order to properly verify
569 the server. The truststore should contain a file or directory of
|
570 sushma.fernandes 1.4 trusted CA certificates. The cimtrust CLI cannot be used to
|
571 dave.sudlik 1.3 configure client truststores. The trusted certificate(s) should be
572 placed in a protected file or directory specified by the trustStore
573 parameter. Keep in mind that the SSL context generally has to be
574 reloaded to pick up any truststore changes.</li>
575 <li>The client could also use a user-specified callback in addition
576 to the default verification callback, if additional verifications are
577 desired over the normal checks that OpenSSL performs. In most cases,
578 the default verification callback is sufficient for checking server
579 certificates.</li>
580 <li>The client should ensure that adequate entropy is attained.</li>
581 <li>The client should use a CRL store if the truststore contains CA
582 certificates that support one.</li>
583 <li>The client should only use the SSLv3 and TLSv1 protocols. By
584 default, Pegasus is not built with SSLv2 support.</li>
585 <li>The client should perform post-connection checks. </li>
586 <ul>
587 <li>Ensure a certificate was received.</li>
|
588 h.sterling 1.1 <ul>
|
589 dave.sudlik 1.3 <li>WARNING: In some implementations of SSL a NULL server
590 certificate is perfectly valid and authenticates against all trust
591 stores. If the client does not ensure a certificate exists then
592 the client is not providing server authentication and could have a
593 security bulletin class defect.</li>
|
594 h.sterling 1.1 </ul>
|
595 dave.sudlik 1.3 <li>Validate that the certificate received was issued to the host
596 for which the client was attempting to connect.</li>
597 <ul>
598 <li>Ensure that the common name (CN) in the server’s certificate
599 subject matches the host name of the server. For X509v3
600 certificates, the “<span class="SpellE">SubjectAltName</span>” fields
601 in the certificate's extended attributes are also valid host names for
602 the certificate. </li>
603 <li>WARNING: If the client does not ensure the host name of
604 the server is the same as one of the host names explicitly described in
605 the server’s certificate, you have not authenticated the server’s
606 identity. Any other server which was issued a certificate from
607 the same trusted CA can masquerade as the server unless the client
608 performs the host name check.</li>
609 </ul>
610 <li>Ensure that certificate verification methods/routines return no
611 errors.</li>
612 </ul>
613 </ul>
614 <p>
615 Because only the above arguments can be passed into the Pegasus
616 dave.sudlik 1.3 SSLContext, there are some limitations in the client configuration:
617 </p>
618 <ul>
619 <li>The verification depth cannot be specified. Pegasus uses the
620 default OpenSSL depth of 9.</li>
621 <li>The cipher list cannot be specified. Pegasus uses the default
622 OpenSSL cipher list. The cipher lists can be found at <a
623 href="http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#SSL_v3_0_cipher_suites_</a>
624 and <a
625 href="http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_">http://www.openssl.org/docs/apps/ciphers.html#TLS_v1_0_cipher_suites_</a></li>
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 dave.sudlik 1.3 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