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