|
|
|
Using WebLogic SSL
With WebLogic SSL, WebLogic offers encrypted, authenticated connections via Secure Socket Layer (SSL). SSL is a standard protocol proposed by Netscape for negotiating a secure connection. WebLogic SSL implements the SSL 3.0
specification. It does not support SSL 2.0. WebLogic SSL works with
JDK This document provides a step-by-step guide for using SSL with WebLogic. There are two parts to secure communications:
AuthenticationAuthentication takes place at two levels: first, verifying that the communicating parties are who they say they are, and second, verifying that each message exchanged is from the expected sender and has not been tampered with. SSL authentication uses a certificate, made up of a public key and some information about the owner of the corresponding private key. The certificate is signed cryptographically by a certificate authority, such as VeriSign, Baltimore CyberTrust, or Entrust. VeriSign, for example, offers four certification types that indicate to what degree the holder has been verified. (There is a full list of certificate authorities, including some lesser-known, on the SSLeay website.) A cryptographic signature can be verified based on the public key of the certificate authority. Forging a cryptographic signature without knowing the certificate authority's private key is statistically close to impossible. Two-way authentication requires that each party, both the server and the client, exchange certificates. Server-to-server authentication is also supported beginning with release 3.1.3 of the WebLogic Server. A server can request a secure connection to another server and a server can be configured to require high security connections. EncryptionSSL uses public-key cryptography to authenticate the participants in an SSL connection and to ensure a private negotiation of parameters used to encrypt data sent over the SSL connection.Public-key cryptography is based upon public/private key pairs. A public key is used to encrypt and to verify a cryptographical signature. The corresponding private key is used to decrypt and to sign messages cryptographically. You advertise your public key to the world so that anyone can send you messages that only you can decrypt, and anyone can verify your cryptographic signature on messages you sign. You protect your private key carefully; it is never necessary to share it with anyone else and you should never send it over a network. The protocol for establishing an SSL connection includes negotiating the most secure 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. Applications have different security requirements, which can be satisfied with various combinations of SSL features. For example, while a customer browses a retail catalog on the internet, authentication and encryption are generally not required. However, during a purchase transaction, encryption protects customers' personal data such as address and phone number, and server authentication allows the customer to trust the identification of the server on the other end of the transaction. Client authentication probably is not required -- potential customers are welcomed and the application verifies credit and payments using a process better suited to financial transactions than SSL authentication. 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 certificate authority. This requires additional software that allows you to generate certificates. (With WebLogic software, you can generate a certificate request to submit to a certificate authority, but you cannot generate a digitally-signed certificate.) WebLogic Server and U.S. cryptography regulationsThe United States regulates the export of cryptographic software to other nations. "Strong" encryption can only be exported from the United States to qualifying customers. Because of these restrictions, the generally-available WebLogic Server has only exportable-strength encryption. The "strength" of encryption in a software product is regulated according to the number of bits in the encryption keys. The more bits in an encryption key, the more difficult it is to break the encryption.
Customers in the United States and in other qualifying nations can request the domestic-strength version of WebLogic Server by contacting Sales. 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 a web or application server and its clients are encapsulated in HTTP packets for transport. You can also tunnel SSL over WebLogic's fast, multiplexed IP-based protocol, T3. The use of SSL is signified in the protocol scheme of the URL, for example: https://myserver.com/mypage.htm t3s://myserver.com:7002/mypage.htm 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. Clients outside of a browser can form an SSL connection to the WebLogic Server by using WebLogic's T3S protocol, which has SSL support. Java programs running in the WebLogic Server can establish T3S connections to other WebLogic Server's or HTTPS connections to other servers that support SSL, such as webservers 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 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 GTE Cybertrust. For a demonstration of using SSL with WebLogic, you can use the .der files in the weblogic/myserver directory. The ca.der file is a demonstration certificate authority's certificate. For this demonstration, WebLogic is the certificate authority. The democert.der file is a certificate signed with the public key in ca.der. The democert.key file is the private key that matches the public key in democert.der. 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=democert.key weblogic.security.certificate.server=democert.der weblogic.security.certificate.authority=ca.der The demonstration certificate files help to understand how SSL certificates work, but are not sufficient 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. The WebLogic distribution includes a server certificate request generator. This is a servlet that collects information from you and generates a private key file and a certificate request file. The servlet lets you submit the certificate request file to VeriSign or GTE CyberTrust. To run the server certificate request generator, load the Certificate servlet from your WebLogic Server into a browser, using a URL similar to this one: http://localhost:7001/Certificate If the WebLogic Server is running on a different computer or listening on a different port, replace localhost or port with the correct computer name or port number.
The servlet includes extensive online help, including instructions for obtaining a test certificate and installing the certificate on your WebLogic Server. The certificate generates three files in the WebLogic Server's startup directory.
If you apply to VeriSign for a permanent certificate, you are asked to select a Server Type. Choose "Apache Freeware with SSLeay" to ensure that you receive a certificate that is compatible with WebLogic Server. If you purchase a certificate from GTE CyberTrust, follow the instructions provided for WebLogic Server.
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 certificate chains. Certificates for the server, authority, authority2, and authority3 constitute a chain where the server certificate is digitally signed by the first certificate authority, the first certificate authority's certificate is signed by the second certificate authority, and the second certificate authority's certificate is signed by the third certificate authority. Clients typically have an independent database of trusted certificate authorities, so you do not usually have to provide certificate authorities' certificates. Your WebLogic SSL configuration needs only a digitally-signed certificate, which contains your public key, and your matching private key. However, if the authority who issues your certificate is not well-known, a certificate chain leading to a trusted certificate authority allows a client to authorize your certificate. If the signature on your certificate (authority) is not a trusted authority, the client checks the signature on that certificate (authority2). If authority2 is trusted, then the client can trust authority, and if authority is trusted, the client can trust you. It is up to the client to determine how far it will trace a certificate chain and still maintain trust. WebLogic allows you to chain four certificates (your own and three certificate authorities). To set up a chain, set each property to the filename of the appropriate certificate authority's public key. All keys should be located in the WebLogic Server's per-server directory. The SecureServerCA.der certificate included in the distribution is VeriSign's issuer certificate, and may be used as a value for weblogic.security.certificate.authority if your certificate was issued by VeriSign. The demo certificate included in the distribution is for demo purposes only. If you set this property to point to the demo certificate included in the distribution an inconsistent configuration will be detected and an Exception will be thrown.
III. Using SSL in the WebLogic environment
Making client connections to WebLogic with SSLEach time a client requests an SSL connection, the 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, the user will have several options as to how permanent its acceptance of certificates from this issuer should be. The user can check information about the certificate authority that issued the site 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 property in the weblogic.properties file to the public key of a certificate authority. With these properties set, WebLogic asks each client to present a certificate and denies the connection if the certificate was not issued by the specified CA. Currently, WebLogic supports only a single client root certificate authority. 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 will 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 to require SSL connectionsTo restrict WebLogic 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 the WebLogic Server to listen for SSL connections on that port: weblogic.system.SSLListenPort=443 Configure the certificate authority 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 program), you can check whether the client presented a certificate, and if that certificate was authorized by a trusted issuer. 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 the 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 htm page with an applet tag that passes the token as a parameter. The ClientAuthenticationServlet addresses the problem of how applets can establish secure communications that use the same certificates for authorization as the browser that loaded the applet. If your browser client connects to the WebLogic Server with the URL path authenticated/some_directory, the browser's certificate will be captured and stored in a safe place under a randomly generated 64-bit token. The servlet then creates an htm page -- with the stored token -- for loading the applet. The token can be redeemed once (and only once) and is as good as the certificate itself. In general, presenting the right token authenticates applets just as presenting the certificate authenticated the browser running the applet. To safeguard the WebLogic Server from having to store tokens indefinitely that are never claimed and used, 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.T3AdminCaptureRootCA=\
admin.T3AdminCaptureRootCA
weblogic.security.certificateCacheSize=3
If you are using access control
lists 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.
When a T3Client requests a secure connection, the WebLogic Server first sends a public key to the T3Client that will be used for future encrypted transactions. Your request for a secure transaction is in the WebLogic Server URL you use when you construct a T3Client. You use the URL scheme "t3s" in the URL, as in this example: T3Client t3s = new T3Client("t3s://WebLogicURL:port");
where the WebLogicURL is set to your server and port is set to the port that is listening for SSL connections (weblogic.system.SSLListenPort). There is more info on connecting to WebLogic over various protocols in the Developers Guide, Writing a T3Client. Once secured, a connection to WebLogic is secure for all transactions. Using SSL slows network transfer rates. Although not as fast an unencrypted data transfer, in many interactions, encrypted data transfer is not the bottleneck. Data transfer is only one part of a client-to-server interaction. Ping ExampleYou can ping the WebLogic Server to test secure communications, with the command:$ java weblogic.T3Admin 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.T3Admin t3s://WebLogicURL:Port PING HTTPS ExampleTo enable SSL on WebLogic, you set the property weblogic.security.SSLListenPort to non-zero and start the WebLogic Server. Then you use that port number in your client's URLs. Make sure that you have set the property before continuing. Note that HTTPS is not available for use in a browser application unless the browser supports SSL3 as it is in most browsers. If you have problems running a browser based application, verify that the browser you are using is new enough to include SSL3. Both Microsoft Internet Explorer and Netscape versions after 4.0 include support for SSL. Point a local browser at the URL https://localhost:7002/T3AdminMain, where the URL matches your WebLogic Server and SSL listenport. The browser and the 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 a MD5 MAC." When the connection is established, the T3Admin 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 Security:
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.
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("");
}
}
How do you implement two-way authentication in an applet?
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 needs to 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. (This only applies to WebLogic version 3 and higher):
The vulnerability is purely theoretical. It consists of distinguishing between two kinds of error responses. To exploit it, an attacker would have to carefully generate and analyze on the order of one million error responses from an SSL server. WebLogic uses RSA in its SSL implementation. Based on the suggested fix from RSA, WebLogic changed how encoding failures are handled so that error messages are completely uniform. The changes are included in WebLogic release 3.1 and later.
V. Change history
|
1.1.x, and the T3Client and WebLogic Server 
If I am accepting
certificates from a third party signer, such as VeriSign, how do I limit
access to users who have registered with me? Should I capture the
fingerprint of their certificate when they register at the site and then
validate it every time they they attach in the future?
Unfortunately, it is
not quite so simple. The certificate really identifies a specific browser,
not an individual. Until browsers integrate with smart cards for their
certificates, an individual will have as many separate certificates as
browsers. You might consider capturing the certificate holder's name
rather than the certificate's fingerprint, since -- in theory -- the CA
guarantees that the name is significant. Unfortunately, the free VeriSign
certificate guarantees only the email address. Another option is to act as
your own certificate authority on registration.
