|
|
|
Using WebLogic SSL
WebLogic SSL offers private and reliable connections using SSL (Secure Sockets Layer), the standard protocol for secure web connections developed by Netscape Communications. SSL provides secure connections by allowing two applications connecting over a network to authenticate the others' identity and by encrypting the data exchanged between the applications. Authentication allows a client or server application to verify the identity of the application on the other end of a network connection. Encryption makes data transmitted over the network intelligible only to the intended recipient. WebLogic SSL implements the SSL 3.0 specification. It does not support SSL 2.0. WebLogic Server includes a pure-Java SSL implementation. A native library that provides faster performance for some SSL operations is provided for some platforms. The native version is used automatically if it exists. WebLogic Server supports SSL on a dedicated listen port, which defaults to port 7002. To establish an SSL connection, a web browser connects to WebLogic Server by supplying the SSL listen port and the HTTPS schema in the connection URL, for example https://myserver:7002. A Java application can get an SSL connection to WebLogic Server by supplying the T3S schema in the connection protocol. For example, to connect with JNDI, a client sets the Context.PROVIDER_URL environment variable to the WebLogic Server URL with the t3s schema, as in this example: Context ctx = null;
Hashtable ht = new Hashtable();
ht.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
ht.put(Context.PROVIDER_URL,
"t3s://localhost:7001");
try {
ctx = new InitialContext(ht);
// Use the context in your program
}
catch (NamingException e) {
}
finally {
try {ctx.close();}
catch (Exception e) {
}
}
SSL is computationally intensive and adds significant overhead to a connection. You should avoid using it when it is not necessary. For example, in an e-commerce application, use the regular HTTP protocol for catalog searches, then switch to HTTPS to secure the customer's personal data during order processing. HTTPS connections take longer to negotiate. By default, WebLogic Server waits up to 25 seconds for an SSL connection before it times out the connection (as opposed to 5 seconds for a plain connection). You may need to configure a higher connection timeout value for SSL. See Setting client timeout in Setting WebLogic properties for help. An SSL connection begins with a handshake protocol during which the applications exchange certificates, agree on the encryption algorithms to use, and generate the encryption keys used for the remainder of the session. AuthenticationSSL uses public key encryption technology for authentication. With public key encryption, a public key and private key are generated for an individual or other entity such as a web server or application server. The keys are related such that data encrypted with the public key can only be decrypted using the corresponding private key. The private key is carefully protected so that only the owner can decrypt messages. The public key, however, is distributed freely so that anyone can encrypt messages intended for the owner. CertificatesWith SSL, the public key is embedded into a certificate (also called a digital ID) with additional information describing the owner of the public key, such as name, street address, and e-mail address. To support SSL connections for clients, you need to obtain a server certificate and install it in WebLogic Server. The server certificate includes the URL of the WebLogic Server, for example, http://www.yourdomain.com. The data embedded in a certificate is verified by a certificate authority (CA) and digitally signed with the CA's certificate. Well-known certificate authorities include VeriSign and Entrust.net. VeriSign, for example, offers different certification types that indicate to what degree VeriSign has verified the certificate holder. A CA certificate that is used to sign other certificates is called a root certificate. Root certificates for trusted CAs are installed into applications that authenticate certificates. For example, web browsers are usually distributed with several common CA root certificates pre-installed. If you want WebLogic Server to also be able to authenticate certificates presented by its clients, you can install up to four CA root certificates. WebLogic Server will authenticate only client certificates issued by one these CAs. An application participating in a an SSL connection is authenticated when the other party evaluates and accepts their certificate. Web browsers, web servers, and other SSL-enabled applications generally accept as genuine any certificate that is signed by a trusted CA and is otherwise valid. For example, a certificate can be invalidated because it has expired or the CA certificate used to sign it has expired. A server certificate can be invalidated if the URL of the server that presented the certificate does not match the URL embedded in the certificate. Web browsers are usually configured to warn the user when they encounter a suspect certificate and let the user decide whether to continue with the connection.
One-way and two-way authenticationSSL authentication can be one-way or two-way. With one-way authentication, which is the WebLogic Server default, the server is required to present a certificate to the client, but the client is not required to present a certificate to the server. To successfully negotiate an SSL connection, the client must authenticate the server, but the server will accept any client into the connection. One-way authentication is common on the Internet, where customers want to create secure connections before they share personal data. With two-way authentication, the client also presents a certificate to the server. WebLogic Server can be configured to require clients to submit certificates issued by any of up to four specified CAs. Client authentication is useful when you must restrict access to trusted clients only. For example, you could restrict access by accepting only clients with certificates you provide them. In this case, you are the CA. This requires additional software that allows you to generate certificates. (With BEA software, you can generate a certificate request to submit to a CA, but you cannot generate a digitally-signed certificate.) WebLogic Server also supports server-to-server authentication, where a server can request a secure connection to another server and a server can be configured to require high security connections. EncryptionThe protocol for establishing an SSL connection includes negotiating the most secure encryption algorithm both client and server support. The most commonly used encryption algorithms are:
A cipher suite is made up of three algorithms -- one each for key exchange, bulk encryption, and message digest. For example, the cipher suite RSA_WITH_RC4_128_MD5 uses RSA for key exchange, RC4 with a 128-bit key for bulk encryption, and MD5 for message digest. BEA provides two versions of WebLogic Server. The generally-available version supports 512-bit certificates and 40-bit bulk data encryption. You can obtain a version that supports 768-bit and 1024-bit certificates and 128-bit bulk data encryption by contacting your BEA sales representative. How is SSL transported?The SSL protocol is customarily "tunneled" over an IP-based protocol. "Tunneling" means simply that each SSL record is encapsulated and packaged up with the proper headers to send over another protocol. SSL communications between web browsers and WebLogic Server are encapsulated in HTTPS packets for transport, the "S" signaling that SSL is in use. Java clients connecting to WebLogic Server with SSL tunnel over BEA's multiplexed T3 protocol. The use of SSL is signified in the protocol scheme of the URL, for example: https://myserver.com/mypage.html t3s://myserver.com:7002/mypage.html Tunneling adds overhead to any sort of communications. Using a communication protocol that must be unencrypted or authenticated will add noticeably to a client's perceived wait time. WebLogic supports HTTPS with browsers that support SSL3. The JVM (Java Virtual Machine) doesn't currently support the HTTPS protocol adapter and consequently WebLogic depends on the implementation of SSL in the browser. Non-browser clients can form an SSL connection to WebLogic Server by using WebLogic's T3S protocol, which has SSL support. Java programs running in WebLogic Server can establish T3S connections to other WebLogic Servers or HTTPS connections to other servers that support SSL, such as web servers or secure proxy servers.
To use SSL with WebLogic, you need a private key and a digitally-signed certificate containing the matching public key. If the certificate authority who signed your certificate is not well-known, you may also need to install their root certificate in your WebLogic Server. Here are the steps:
An SSL client typically keeps a list of trusted certificate authorities and alerts the user when a server presents a certificate that is not issued by a recognized authority. Extending the list of trusted certificate authorities is part of security configuration. Newer browsers (beginning with Netscape version 2.x and Internet Explorer 4.0) can extend this list dynamically using a sequence of dialogs presented to the user when a questionable certificate is encountered. Earlier browsers have a hard-coded list of valid certificate authorities. If one of these browsers encounters a certificate from an unknown CA, it will not complete a secure connection. For these earlier browsers (Netscape 1.x, Internet Explorer 2.x and 3.x), you must request a certificate from a recognized certificate authority like VeriSign or Entrust.net. For a demonstration of using SSL with WebLogic, you can use the .pem files in the weblogic/myserver directory. The ca.pem file is a demonstration CA root certificate. For this certificate, WebLogic is the certificate authority. The democert.pem file is a certificate signed with the public key in ca.pem. The demokey.pem file is the private key that matches the public key in democert.pem. To install these files, copy them to your per-server directory (if it is other than /weblogic/myserver, and add these properties to your weblogic.properties file: weblogic.system.SSLListenPort=7001 weblogic.security.ssl.enable=true weblogic.security.key.server=demokey.pem weblogic.security.certificate.server=democert.pem weblogic.security.certificate.authority=ca.pem These properties are already enabled in the distributed weblogic.properties file. The demonstration certificate files help to understand how SSL certificates work, but are not useful for secure communications, since WebLogic is not a well-known or trusted certificate authority.
Acquiring a certificate for your WebLogic ServerTo acquire a certificate from a certificate authority, you submit your request in a particular format called a "Certificate Signature Request" (CSR). The WebLogic distribution includes a server certificate signature request generator. This is a servlet that collects information from you and generates a private key file and a certificate request file. The servlet generates requests that you can submit to VeriSign or Entrust.net. WebLogic Server is available with exportable- or domestic-strength SSL.
The standard WebLogic Server distribution supports exportable-strength SSL only. The domestic version is available only by request to your BEA sales representative. Since the United States Government relaxed restrictions on exporting encryption software in early 2000, the domestic version of WebLogic Server can be used in most countries. The domestic WebLogic Server distribution is recommended because it allows stronger encryption. If you generate your CSR using the exportable WebLogic Server distribution, you cannot support high-strength connections and you cannot authenticate clients that present domestic-strength certificates. PrerequisitesCheck the following prerequisites before you continue:
To purchase a web server certificate for WebLogic Server, you choose a Certificate Authority and follow the enrollment instructions on their web site. During the enrollment process, you are instructed to Generate a CSR. At that point, you use the WebLogic Server Certificate Request Generator servlet to generate a CSR. Then you continue with the the Certificate Authority's enrollment procedure, submitting the CSR according to their instructions.
Installing certificates on a WebLogic ServerOnce you have a certificate, you can set up your WebLogic Server for SSL as follows.
Certificate chainsThe weblogic.security.certificate.authorityN properties, along with weblogic.security.certificate.server, make it possible to set up a certificate chain that allows clients to authenticate your server certificate if it was not directly issued by a recognized CA. The certificates for the server, authority, authority2, and authority3 constitute a chain where the server certificate is signed by the authority, the authority's certificate is signed by authority2, and authority2's certificate is signed by authority3. Clients typically have a database of trusted certificate authorities, so you do not have to provide the chain of CA root certificates unless your certificate was not issued by a well-known CA. If the authority who issues your certificate is not well-known, providing a root certificate chain that terminates with a certificate from a well-known CA allows a client to authorize your certificate. If the signature on your certificate is not a CA the client recognizes, the client checks the signature on that CA's certificate. If the second CA is trusted, then the client can trust the CA who signed your certificate. It is up to the client to determine how far it will trace a certificate chain and still maintain trust. WebLogic Server allows you to chain four certificates (your own and three CAs). To set up a chain, set each property to the filename of the appropriate CA's root certificate. All of the CA's root certificates should be located in the WebLogic Server's per-server directory. The demo certificates included in the distribution are for demonstration purposes only. If you set one of these properties to point to the CA.pem certificate included in the WebLogic distribution, an inconsistent configuration will be detected and an Exception will be thrown.
III. Using SSL in the WebLogic environment
Making client SSL connections to WebLogic ServerWhen a client requests an SSL connection, WebLogic Server presents its certificate for the client to evaluate. The client decides whether to accept the certificate and proceed to form a secure connection.
If the certificate issuer is unknown, a browser may not be able to accept the certificate. If the browser accepts the certificate from an unknown certificate authority, it presents the user with several options on how to proceed. The user can view information about the certificate authority that issued the server certificate before accepting it.
Two-way authenticationTwo-way authentication requires clients to present a certificate to the WebLogic Server in order to establish an SSL connection. The client first authenticates the server's certificate, and then the server authenticates the client's certificate.To enable two-way authentication, you set weblogic.security.enforceClientCert to "true" and set the weblogic.security.clientRootCA properties in the weblogic.properties file to the filenames of the root certificates of the CAs you want to accept. With these properties set, WebLogic asks each client to present a certificate and denies the connection if the certificate was not issued by a specified CA. If you issue your own certificates, you can use two-way authentication to allow access only to clients with certificates you issue. Just set the weblogic.security.clientRootCA property to the name of your own certificate file. Note that to issue your own certificates, you need additional software. WebLogic software allows you to generate a request for a certificate, which can be fulfilled by a certificate authority, but you cannot generate an actual certificate. Setting up WebLogic Server to require SSL connectionsTo restrict WebLogic Server to only SSL connections, you set the two-way authentication properties described above and you must protect your non-SSL listen port with a firewall that allows access only to the SSL listen port. For example, configure the firewall to allow access only to port 443 and configure WebLogic Server to listen for SSL connections on that port: weblogic.system.SSLListenPort=443 Configure the CA for SSL clients by setting the weblogic.security.clientRootCA property to the filename of the certificate from the certificate authority and enable two-way authentication by setting weblogic.security.enforceClientCert to "true." Requesting and accepting certificates from clientsTo authenticate clients in a servlet (or any other server-side Java class), you can check whether the client presented a certificate, and if that certificate was issued by a trusted CA. The servlet author is responsible for asking if there is a valid certificate. See the section Using SSL in servlets for more about SSL and the servlet API. Two-way authentication from an applet is more difficult because applets cannot access the certificate of the browser in which they run. One solution is to allow applets indirect access to the browser's certificate via WebLogic Server. The servlet can capture the browser's certificate and reveal it only when a specific 64-bit token is presented. It can then create an HTML page with an applet tag that passes the token as a parameter. The ClientAuthenticationServlet addresses the problem of how an applet can establish an SSL connection using the same certificate as the browser that loaded the applet. If your browser client connects to the WebLogic Server with the URL path authenticated/some_directory, the client certificate submitted by the browser certificate is captured and stored in WebLogic Server as a randomly generated 64-bit token. The ClientAuthenticationServlet then creates an HTML page for the applet. This page contains the token, which the applet can redeem once (and only once). The applet presents the token to WebLogic Server and WebLogic Server accepts the token just as if it had authenticated the certificate instead. To prevent storing unclaimed tokens indefinitely, you can limit the number of certificates that are tokenized and stored by setting the following property: weblogic.security.certificateCacheSize=number of certificates The default setting for this property is 3: // Registration for authentication servlet
weblogic.httpd.register.authenticated=\
weblogic.t3.srvr.ClientAuthenticationServlet
// Registration for servlet that identifies certificate roots
// of certificates that should be accepted
weblogic.httpd.register.AdminCaptureRootCA=\
admin.AdminCaptureRootCA
weblogic.security.certificateCacheSize=3
Mapping a client certificate to a WebLogic Server userWhen a client presents a certificate, WebLogic Server authenticates the certificate for purposes of establishing the SSL connection. The certificate does not identify the client as a WebLogic Server, however. If a client with an SSL connection requests a resource protected by an ACL, WebLogic Server requires the client to provide a username and password. The weblogic.security.acl.CertAuthenticator interface provides a way to map a client certificate to a WebLogic Server user. The interface defines an authenticate() method that WebLogic Server calls after evaluating a certificate presented by a client. The method can examine the certificate as a weblogic.security.Certificate object and use any of the data embedded in the certificate to derive a WebLogic user. The weblogic.security.cert.SimpleCertAuthenticator example demonstrates how this works. It extracts the client's email address from the certificate and returns that WebLogic user with the same name, providing that user exists. To install a CertAuthenticator class, edit the weblogic.properties file and set the property weblogic.security.realm.certAuthenticator to the name of the Java class that implements CertAuthenticator. Getting a certificate for a browserLow-security browser certificates are easy to acquire and can be done from within the browser, usually by selecting the Security menu item in Options or Preferences. Go to the Personal Certificates item and ask to obtain a new certificate. You will be asked for some information about yourself. The certificate you receive contains public information, including your name and public key, and additional information you would like authenticated by a third party, such as your email address. Later you will present the certificate when authentication is requested. As part of the process of acquiring a certificate, the browser generates a public-private key pair. Your private key should remain secret. It is stored on your local file system and should never leave the browser's machine, to ensure that the process of acquiring a certificate is itself safe. With some browsers, the private key can be encrypted using a password, which is not stored. When you encrypt your private key, you will be asked by the browser for your password at least once per session. As part of SSL negotiation, after your certificate has been submitted to a server, your browser will send a CertificateVerify message, consisting of a digest of the messages sent thus far, signed with your private key. The digest can be computed on the server and the signature verified using your public key, which is part of your public certificate. You should note that certificates are not universally useful for multiple browsers, or even for different versions of the same browser.
A Java client requests a secure connection with WebLogic Server by using the URL scheme "t3s" and the SSL listen port in the WebLogic Server URL. Ping ExampleYou can ping the WebLogic Server to test secure communications, with the command:$ java weblogic.Admin t3s://WebLogicURL:Port PINGwhere the WebLogicURL is set to your server and Port is set to the port that is listening for SSL connections (weblogic.system.SSLListenPort). The ping first agrees on a cipher suite to use. For example, cipher suite 3 is SSL_RSA_EXPORT_WITH_RC4_40_MD5, which means that the connection uses SSL with RSA exportable grade authenticated key exchange, 40-bit bulk data encryption using the RC4 stream cipher algorithm, and the MD5 algorithm for digesting. To see which cipher suite is selected and all the gory encryption details, run the command with -Dssl.debug, as in: $ java -Dssl.debug weblogic.Admin t3s://WebLogicURL:Port PING JNDI client SSL exampleThis example shows how to get a secure connection using JNDI: Context ctx = null;
Hashtable ht = new Hashtable();
ht.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
ht.put(Context.PROVIDER_URL,
"t3s://localhost:7001");
try {
ctx = new InitialContext(ht);
// Use the context in your program
}
catch (NamingException e) {
}
finally {
try {ctx.close();}
catch (Exception e) {
}
}
Once the client has the JNDI context, an SSL connection is established and all subsequent operations on that connection are secure. HTTPS ExampleTo enable SSL on WebLogic Server, you set the property weblogic.security.SSLListenPort to non-zero and start the WebLogic Server. Then you use that port number in your clients' URLs. Browse the URL https://localhost:7002/AdminMain, where the URL matches your WebLogic Server and SSL listen port. The browser and WebLogic Server will then negotiate a cipher suite. If there is no satisfactory resolution, you can edit the security preferences in the browser to enable "RC4 encryption with a 40-bit key and an MD5 MAC." When the connection is established, the AdminMain servlet executes exactly as if it had been requested with an HTTP URL. However, all network traffic between the client and server is encrypted.
Using SSL in servletsWhen writing servlets with the servlet API, you have access to certain information about the SSL connection through the HttpServletRequest object's getAttribute() method. In order to print SSL information, this method could be added to the SnoopServlet, which is provided in the WebLogic Server examples. As written, the SnoopServlet echos back the request line and headers that were sent by the client, plus any HTTPS information which is accessible. The following attributes are supported in WebLogic Server servlets:
Opening a secure connection to another serverYou can connect to a second server using two-way authentication with your server's certificate. The example below establishes a secure connection to a WebLogic Server called "server2.weblogic.com" from a servlet running in another server: Environment e = new Environment();
e.setProviderUrl("t3s://server2.weblogic.com:443");
e.setSSLClientCertificateFromServer();
e.setSSLServerName("server2.weblogic.com");
e.setSSLRootCAFingerprints("ac45e2d1ce492252acc27ee5c345ef26");
T3Client t3c = e.createProviderClient();
t3c.connect();
e.setInitialContextFactory("weblogic.jndi.WLInitialContextFactory");
Context ctx = new InitialContext(e.getProperties())
The Environment class creates a Hashtable to store parameters to pass to the JNDI InitialContext factory. The provider client URL specifies the t3s protocol, which is the WebLogic specific protocol, t3, over SSL. The next line enables the server's own certificate to be used for SSL client authentication. An alternative method setSSLClientCertificate(), could be used here instead to set a certificate chain to use for the connection. The chain is an array that contains a private key, the matching signed public key, and a chain of CA certificates, each the issuer of the previous certificate. The next two lines protect against a man-in-the-middle attack. They specify that the server certificate must be for a specific server, in this example, "server2.weblogic.com," and the certificate must be issued by a certificate authority with a specific fingerprint. The createProviderClient() method creates the secure connection using the parameters stored in the Environment object. See Using WebLogic JNDI for more on using JNDI to access services in a WebLogic Server. For more information on servlets, see the Developers Guide Using WebLogic HTTP Servlets.
IV. Questions and Answers about SSLBecause there are many issues related to using SSL that aren't specific to WebLogic, we have provided an additional set of questions and answers to help you with your implementation.
weblogic.httpd.session.cookie.domain=.mydomain.com
Configure WebLogic for client authentication with the properties: weblogic.security.clientRootCA=client-ca-cert.der weblogic.security.enforceClientCert=truewhere client-ca-cert.der is a certificate file in .der format. The certificate from the configured weblogic.security.clientRootCA and its digest are accessible through the servlet request attributes javax.net.ssl.rootCA, and javax.net.ssl.rootCADigest.
The weblogic.security.JDK111Certificate.getFingerprint() method calculates the fingerprint of a certificate, returning a byte array. Here is some code to demonstrate how to get the fingerprint of a certificate and print it out in hexadecimal: import java.io.*;
import weblogic.security.X509;
import weblogic.security.JDK11Certificate;
public class fingerprint {
private static char hexdigits[] = {
'0','1','2','3','4','5','6','7',
'8','9','A','B','C','D','E','F'};
public static void main(String[] argv)
throws Exception
{
InputStream is = null;
JDK11Certificate cert = null;
byte fp[];
try {
is = new FileInputStream(argv[0]);
}
catch (FileNotFoundException e) {
System.out.println("Can't find file " + argv[0]);
e.printStackTrace();
}
try {
cert = new JDK11Certificate(new X509(is));
}
catch (Exception e) {
e.printStackTrace();
}
fp = cert.getFingerprint();
System.out.print("Fingerprint:");
for (int i = 0; i < fp.length; i++) {
System.out.print(" "
+ hexdigits[(fp[i] & 0xff) >> 4]
+ hexdigits[(fp[i] & 0xf)]);
}
System.out.println("");
}
}
An example of this is the "SnoopServlet" in package examples.servlets, which uses javax.net.ssl.peer_certificates to access, display, and print the certificate. The applet, however, cannot directly access the browser's certificate. If it needs information from the certificate, it must get it from the server. A special servlet can store the browser's certificate and exchange it for a token, which is passed to the applet as a parameter. If you want to use certificates in place of password authentication, follow these steps to set up WebLogic Server.
|
|
|
|
Copyright © 2000 BEA Systems, Inc. All rights reserved.
|
When a Netscape browser starts a session with WebLogic Server on an HTTP page
and then moves to an HTTPS page, a new session is created. How can I preserve
the session while switching to or from HTTPS?
The cookie WebLogic Server sends includes the port number. When the
Netscape browser sees a cookie with a different port number, it
assumes the destination is a different server, so it does not return
the cookie to WebLogic Server. The way to prevent this is to specify
the domain name that WebLogic Server writes in the cookie with the weblogic.httpd.session.cookie.domain
property. For example: