Corporate Info | News | Solutions | Products | Partners | Services | Events | Download | How To Buy

# Using WebLogic SSL I. Introduction Authentication Encryption How is SSL transported? II. Setting up WebLogic SSL Acquiring a certificate for your WebLogic Server Installing certificates on a WebLogic Server III. Using SSL in the WebLogic environment Making client SSL connections to WebLogic Server Setting up two-way authentication Setting up WebLogic to require two-way authentication Requesting and accepting certificates from clients Mapping a client certificate to a WebLogic Server user Getting a certificate for a browser Setting up a Java client Ping example JNDI client SSL example HTTPS example Opening a secure connection to another server Using SSL in servlets IV. Questions and Answers about SSL V. Change history Other related documents Guide to WebLogic Server security documentation Installing WebLogic (non-Windows) Installing WebLogic (Windows) Using WebLogic ACLs (Access Control Lists) The Developers Guides WebLogic API Reference Manual Troubleshooting Applet Security problems Glossary Code examples Other online resources SSL 3.0 Specification Crypto Standards & Protocols Frequently asked questions about Cryptography # I. Introduction 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. ## Authentication SSL 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. ### Certificates With 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 authentication SSL 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. ## Encryption The 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: RSA (Rivest, Shamir, and Adelman, the names of its designers) for key exchange DES (Data Encryption Standard) and its variants RC2 (a block cipher) and RC4 (a faster stream cipher) for bulk encryption MD5 and SHA for message digests 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
1. 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. # II. Setting up WebLogic SSL 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: Acquire a certificate for your server. You can use the Certificate servlet to generate a public key, private key, and a certificate request, which contains your public key. To obtain a certificate, you send the certificate request to a certificate authority (CA) and follow their procedures for obtaining a signed certificate.
   Note: | Certificates from Microsoft Internet Information Server and Netscape Enterprise Server cannot be used with WebLogic Server because they are stored in a proprietary format.
Install the certificate you received from the CA in the per-server directory of your WebLogic Server. You can use certificates in either .der or .pem format. Set properties in the weblogic.properties file to enable SSL and specify your certificate and private key files. You can also set certificate chain properties to allow clients to authenticate the certificate authority who issued your certificate. For two-way authentication, set properties in the weblogic.properties file so that the WebLogic Server requests certificates from clients. Install the root certificates for CAs whose certificates your WebLogic Server will accept. See the Administrators Guide Setting WebLogic Properties for more properties you can set to configure WebLogic SSL. Begin using SSL in the WebLogic environment. 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 Server To 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. Exportable SSL supports 512-bit certificates and 40-bit bulk data encryption. Domestic SSL also supports 768-bit and 1024-bit certificates, and 56-bit and 128-bit bulk data encryption. 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. #### Prerequisites Check the following prerequisites before you continue: WebLogic Server must be installed, running, and configured to support SSL. See Installing and Setting up WebLogic Server for installation help. See Setting up and Starting WebLogic Server for help starting WebLogic Server. See Installing certificates on WebLogic Server for help installing your server certificate and configuring SSL in WebLogic Server. If you want to support domestic-strength browsers and strong encryption, make sure you have the domestic version of WebLogic Server before you generate a CSR. You can verify that SSL is operational and that you have domestic strength SSL by searching the WebLogic Server log for a message like this one:
      <SSLListenThread> Using domestic strength SSL.
4. - You must know the password for your WebLogic Server "system". If you do not know this password, you will need the help of your WebLogic Server system administrator. ### Obtaining a Web Server Certificate 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. Follow these steps: Select a Certificate Authority and follow the instructions on their web site to purchase a certificate. VeriSign, Inc. offers two options for WebLogic Server: Global Site Services, which features strong 128-bit encryption for domestic and export web browsers, and Secure Site Services, which offers 128-bit encryption for domestic web browsers and 40-bit encryption for export web browsers. Entrust.net certificates offer 128-bit encryption for domestic browser versions and 40-bit encryption for export browser versions. When you are instructed to select a server type, choose "BEA WebLogic Server" to ensure that you receive a certificate that is compatible with WebLogic Server. When you reach the step in the Certificate Authority's enrollment procedure where you are instructed to Generate a CSR, continue with the next step in this process. In a web browser, enter the URL for the WebLogic Server Certificate Request Generator servlet. The URL is in this format: http://hostname:port/Certificate hostname is the DNS name of the computer running WebLogic Server. port is the port number where WebLogic Server listens for connections. The default is 7001. For example, if WebLogic Server is running on the computer named "ogre" and it is configured to listen at the default port 7001, enter this URL in your browser:
         http://ogre:7001/Certificate
6. The browser prompts for a WebLogic Server login and password. Log in as system. The Certificate Request Generator servlet loads a form in your browser. Complete the Certificate Request Generator form as follows:
   Country code | The two-letter ISO code for your country. The code for the United States is "US". You can find a complete list here.
   Organizational unit name | The name of your division, department, or other operational unit of your organization.
   Organization name | The name of your organization. The certificate authority may require that the host name you enter in this field is in a domain registered to this organization.
   E-mail address | Enter the e-mail address of the host administrator.
   Full host name | Enter the fully-qualified name of the server where the certificate will be installed. This is the name used for DNS lookups of the server, such as www.mydomain.com. Browsers compare the site name in the URL to the name in the certificate. If you change the site name later, you must request a new certificate.
   Locality name (city) | Enter the name of your city, town, or other locality. If you operate with a license granted by a city, this is a required field and you must enter the name of the city that granted your license, and you must enter your State or Province in the State name field.
   State name | If you are in the United States or Canada, enter the name of the State or Province in which your organization operates. Do not abbreviate.
   Random string | (Optional) Enter a string of characters to be used by the encryption algorithm. You do not have to remember this string in the future. It is used to add an external factor to the encryption algorithm, making it more difficult for anyone to break the encryption. For this reason, you should enter a string that is not likely to be guessed. A long string with a good mixture of uppercase and lowercase letters, digits, spaces, and punctuation characters contributes to more secure encryption.
   Strength | The length (in bits) of the keys to be generated. The longer the key, the more difficult it is for someone to break the encryption. If you have the exportable WebLogic Server version, this field does not appear. 512-bit keys are generated. With the domestic version, you can choose 512-, 768-, or 1024-bit keys. 1024-bit is recommended.
1. Click Generate Request. The Servlet displays messages if any required fields are empty or if any fields contain invalid values. Click Back in your browser and correct any errors. When all of the fields have been accepted, the Servlet displays the Certificate Request, the name of your private key file, and the name of the certificate request file. The servlet generates three files in the WebLogic Server startup directory. www_mydomain_com-key.der This is your private key file. www_mydomain_com-request.dem This is the encrypted certificate request file, in a binary format. www_mydomain_com-request.pem This is the CSR file, which you submit to the certificate authority. It contains the same data as the .dem file, but encoded in ASCII so that you can copy it into email or paste it into a web form. Make a backup copy of the key file and CSR on a floppy disk. Store the backup copy in a safe, private place. Return to the Certificate Authority's enrollment procedure and submit the CSR as instructed. You can copy the CSR from the Certificate Request Generator browser screen and paste it into the CA's form, or you can retrieve the CSR from the CSR file saved in the WebLogic Server startup directory. When you receive your certificate from the CA, follow the instructions in the next section to install it in WebLogic Server. # Installing certificates on a WebLogic Server Once you have a certificate, you can set up your WebLogic Server for SSL as follows. Copy private key file generated by the Certificate servlet and the certificate you received from the certificate authority into the per-server directory of your WebLogic Server. WebLogic Server can use certificates in either .pem or .der format. It depends upon the file extension to determine the format of the certificate file. A .pem format file (privacy-enhanced mail) begins with this line:
         -----BEGIN CERTIFICATE-----
   and ends with this line:
         -----END CERTIFICATE-----
A .der format file contains binary data. WebLogic Server requires that the file extension match the contents of the certificate file, so be sure to save the file you receive from your Certificate Authority with the correct file extension. Set the following properties in your weblogic.properties file: weblogic.system.SSLListenPort Set a a non-zero value to designate the port for the SSL listener. The default weblogic.properties file has the property enabled and set to port 7702. weblogic.security.ssl.enable Set to "true", the default, to enable SSL. When SSL is enabled, WebLogic Server looks for the properties that identify keys and certificates. weblogic.security.key.server Set to the name of your private key file. weblogic.security.certificate.server Set to the name of the certificate file you received from the certificate authority. weblogic.security.certificate.authority weblogic.security.certificate.authority2 weblogic.security.certificate.authority3 If your certificate is not issued by a well-known certificate authority, copy the certificate authority's root certificate into the per-server directory and set the authority property to the name of the file. You can also set the similar properties that end with authority2 and authority3 to set up a certificate chain. weblogic.security.clientRootCA weblogic.security.clientRootCA2 weblogic.security.clientRootCA3 weblogic.security.clientRootCA4 If you want to use two-way authentication, copy root certificates for the CAs whose certificates you want to accept into the per-server directory, and set these properties to the names of the certificate files. Clients will then be required to present certificates issued by one of these CAs. If you do not want to use two-way authentication, omit this property or set it to "none". weblogic.security.enforceClientCert Set this property to true to have WebLogic reject SSL connections that fail client authentication, either because the requested client certificate was not furnished, or because the client did not submit a certificate or the certificate was not issued by a CA specified by one of the weblogic.security.clientRootCA properties. Start, or restart, WebLogic Server. ## Certificate chains The 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 connections to WebLogic Server with SSL Setting up two-way authentication Setting up WebLogic Server to require two-way authentication Requesting and accepting certificates from clients Mapping a client certificate to a WebLogic Server user Getting a certificate for a browser Setting up a Java client Ping example JNDI client SSL example HTTPS example Opening a secure connection to another server Using SSL in servlets ## Making client SSL connections to WebLogic Server When 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 authentication Two-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 connections To 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 clients To 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 user When 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 browser Low-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. ## Setting up a Java client 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 Example You can ping the WebLogic Server to test secure communications, with the command:
      $ java weblogic.Admin t3s://WebLogicURL:Port PING
where 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 example This 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 Example To 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 servlets When 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: javax.net.ssl.cipher_suite returns the cipher suite in use as a String. javax.net.ssl.session, which returns an SSL Session object, contains all of the above data, plus creation and last-used dates. javax.net.ssl.rootCA, which returns the certificate from the configured weblogic.security.clientRootCA as a String. javax.net.ssl.rootCADigest, which returns the certificate digest from the configured weblogic.security.clientRootCA as a String. Obtain information about the client's certificate chains with the attribute javax.net.ssl.peer_certificates, which returns an array of X509 certificate chains as Objects. You can cast the Object array to weblogic.security.X509[]. Given an array of X509 certificate chains, you have access to a set of user information, such as the user name. You can see the available information associated with each certificate chain by calling toString() on it. You can create a weblogic.security.JDK111Certificate object by passing an X509 certificate to its constructor. The weblogic.security.JDK111Certificate class implements the java.security.Certificate interface. Here is an example that converts the first X509 certificate in an array of weblogic.security.X509:
       weblogic.security.JDK11Certificate jdk11cert =
            new weblogic.security.JDK11Certificate(X509certs[0]);
            print(out, "jdk11cert.getPrincipal().getName() - ",
                       jdk11cert.getPrincipal().getName() );
            print(out, "jdk11cert.getGuarantor().getName() - ",
                       jdk11cert.getGuarantor().getName() );
The weblogic.security.JDK111Certificate class has additional member functions that are not accessible through the Certificate interface: getIssuerCertificate() returns the issuer's certificate as a java.security.Certificate object. getFingerprint() returns the certificate's fingerprint. This is the MD5 of the DER encoded X.509 certificate. Is presumed difficult to construct a different certificate with the identical fingerprint. getSubjectOrgUnit() returns a String containing the Organizational Unit of the subjectDN (distinguished name) from the Certificate. ## Opening a secure connection to another server You 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");

      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. 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 SSL Because 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. 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:
      weblogic.httpd.session.cookie.domain=.mydomain.com
If I am accepting certificates from a third party CA, 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 may 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. I want to restrict access only to certificates issued by my company for two-way authentication between clients and the WebLogic Server. How do I do this? For two-way authentication, enable browser SSL client authentication and check the root certificate authority in the body of a servlet. Configure WebLogic for client authentication with the properties:
    weblogic.security.clientRootCA=client-ca-cert.der
    weblogic.security.enforceClientCert=true
where 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. How can I find a certificate's fingerprint? A certificate's fingerprint is not part of the certificate, but it can be computed from it. Browsers tend to display it as if it were part of the certificate. A fingerprint is the MD5 digest of the der-encoded CertificateInfo, which is an ASN.1 type specified as part of the X.509 specification. 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("");
      }
    }
1. I am creating an applet that requires two-way authentication in lieu of the user/password model. How does the token/certificate exchange happen? Client authentication is transparent to the applet. It happens between the browser and the server. The servlet has access to the browser's certificate chain through the request attribute javax.net.ssl.peer_certificates. 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. Turn authentication of the browser certificates off at the WebLogic level by giving the specific servlet X the property everyone:
         weblogic.allow.execute.weblogic.servlet.X=everyone
2. Enable client authentication by specifying a certificate for the client root certificate authority with a property such as:
         weblogic.security.clientRootCA=client-ca-cert.der
where client-ca-cert.der is the root certificate for authentication of client certificates. If you do not have the root certificate for the client certificates that you want to authenticate, you can use the servlet admin.AdminCaptureRootCA to capture the root certificate and save it to a .der file. Within the servlet, access this certificate chain through the servlet request attribute javax.net.ssl.rootCA. Is there a simple way to restrict access only to clients that have certificates issued by a particular certificate authority? You can snoop the certificate authorities of the client with the AdminCaptureRootCA servlet, which is registered in the weblogic.properties file. AdminCaptureRootCA gets a certificate chain from the browser client and writes the certificate authority's key out to a standard file that you can set as the value for the weblogic.security.clientRootCA. Also set weblogic.security.enforceClientCert to "true." Then, once you have restarted the WebLogic Server, the browser client can return and ask for authorization, and the test for RootIsValid will return true.

Copyright © 2000 BEA Systems, Inc. All rights reserved. Required browser: Netscape 4.0 or higher, or Microsoft Internet Explorer 4.0 or higher. Last updated 3/31/2000