JavaTM Secure Socket Extension (JSSE) 1.0.2


  1. What does JSSE 1.0.2 do in simple terms?
  2. What is new in JSSE 1.0.2 compared to JSSE 1.0.1?
  3. Where does JSSE fit in the JavaTM Security Architecture?
  4. Why should I be interested in JSSE APIs, JSSE 1.0.2 and commercial versions of JSSE?
  5. Is the JavaTM Secure Socket Extension a reference implementation of the specification or a commercial product?
  6. What is the cost of JSSE 1.0.2?
  7. What is the U.S. Department of Commerce Bureau of Export Affairs classification of JSSE 1.0.2?
  8. I read that the US Government has relaxed the export restrictions on encryption products. Can the JSSE 1.0.2 reference implementation be downloaded by any organization, anywhere?
  9. Now that the export requirements have been relaxed, can I download the JSSE 1.0.2 reference implementation if I'm in a country that has been subject to a US Government embargo?
  10. I'm located in the US or Canada. What encryption strength products can I download?
  11. I'm located outside of the US and Canada. What encryption strength products can I download?
  12. Since both the domestic and global version of JSSE 1.0.2 have strong encryption, why do you have two versions?
  13. What versions of the JDKTM does JSSE 1.0.2 support?
  14. Does the reference implementation have the ability to do RSA encryption?
  15. What standard(s) does JSSE 1.0.2 follow?
  16. What version of SSL is supported?
  17. Is the reference implementation of JSSE written in the JavaTM programming language?
  18. Is there any sample source code available?
  19. Something is not working. How can I debug what is going wrong?
  20. It seems the first SSL connection takes longer than subsequent connections. Is there anything I can do to improve the performance of the first connection?
  21. What troubleshooting tips can you provide?

Questions and Answers

  1. Q: What does JSSE 1.0.2 do in simple terms?
    A: JSSE implements a JavaTM version of SSL (Secure Sockets Layer) and TLS (Transport Layer Security) protocols to provide for secure Internet communications.

    Using JSSE, developers can provide for the passage of secure data between a client and a server running any application protocol (such as HTTP, Telnet, NNTP, and FTP) over TCP/IP. JSSE will enable data encryption, server authentication, message integrity, and optional client authentication for a TCP/IP connection.

  2. Q: What is new in JSSE 1.0.2 compared to JSSE 1.0.1?
    A: The following three areas were changed:

  3. Q: Where does JSSE fit in the JavaTM Security Architecture?
    A: JSSE is the latest development in the JavaTM Security Architecture, building upon the JavaTM 2 Security Architecture in the core SDK, the JavaTM Cryptography Extension (JCE), the JavaTM Authentication and Authorization Service (JAAS), and the JavaTM Security Tools. See the
    JavaTM 2 Security Architecture document for more information.

  4. Q: Why should I be interested in JSSE APIs, JSSE 1.0.2 and commercial versions of JSSE?
    A: JSSE enables developers to utilize secure, encrypted communications channels in their applications. It simplifies application development by serving as a building block which developers can integrate directly into their applications. Furthermore, by abstracting the complex underlying security algorithms and "handshaking" mechanisms, JSSE minimizes the risk of creating subtle but dangerous security vulnerabilities.

  5. Q: Is the JavaTM Secure Socket Extension a reference implementation of the specification or a commercial product?
    A: Sun's JavaTM Secure Socket Extension 1.0.2 implementation is a reference implementation. It is intended to familiarize developers with the APIs and the technology before they make a choice on commercial implementations. A reference implementation is similar to a proof-of-concept implementation of a specification. It is used to demonstrate that the specification is implementable and that various compatibility tests can be written against it.

    A non-commercial implementation typically lacks the overall completeness of a commercial-grade product. While the implementation meets the API specification, it will be lacking things such as a fully-featured toolkit, sophisticated debugging tools, commercial-grade documentation and regular maintenance updates.

  6. Q: What is the cost of JSSE 1.0.2?
    A: The JSSE 1.0.2 reference implementation binary code is free for commercial use and redistribution. See the license and the legal documents that are downloaded with the code.

  7. Q: What is the U.S. Department of Commerce Bureau of Export Affairs classification of JSSE 1.0.2?

    A: JSSE 1.0.2 has been classified as an ENC/Retail product by the U.S. Department of Commerce Bureau of Export Affairs. This license exception means that JSSE may be freely exported, without any additional approval, with strong encryption, to all nations except for those specifically denied.

    The following countries may not receive ANY US-developed encryption items: Afghanistan, Cuba, Iran, Iraq, Libya, North Korea, Serbia/Montenegro (Yugoslavia), Sudan, Syria and parties listed on the Denied and Restricted Parties List. Additionally, it is Sun company policy to not ship products to Burma.

  8. Q: I read that the US Government has relaxed the export restrictions on encryption products. Can the JSSE 1.0.2 reference implementation be downloaded by any organization, anywhere?
    A: While there has been some relaxation in the export requirements, there are many restrictions still in place for strong encryption products. Go to
    http://www.epic.org/crypto/export_controls/regs_1_00.html for the complete 33 page report. In addition, some countries may have import restrictions. Note also that a vendor's product status is dependent on the type of application they have with the US government -- JSSE 1.0.2 has been classified as ENC/Retail. Contrary to some articles in the press, export of encryption technology is still a complicated, multi-dimensional issue. You are advised to consult your export/import control counsel or attorney to determine the exact requirements.

  9. Q: Now that the export requirements have been relaxed, can I download the JSSE 1.0.2 reference implementation if I'm in a country that has been subject to a US Government embargo?
    A: No. Even with an ENC/Retail classification, the following countries may not receive ANY US-developed encryption items: Afghanistan, Cuba, Iran, Iraq, Libya, North Korea, Serbia/Montenegro (Yugoslavia), Sudan, Syria and parties listed on the
    Denied and Restricted Parties List. Additionally, it is Sun company policy to not ship products to Burma.

  10. Q: I'm located in the US or Canada. What encryption strength products can I download?
    A: If you are located in the US or Canada, you can download the 128 bit strength domestic JSSE 1.0.2 reference implementation.

  11. Q: I'm located outside of the US and Canada. What encryption strength products can I download?
    A: If you are located outside of the US or Canada, you can download the 128 bit strength global JSSE 1.0.2 reference implementation.

  12. Q: Since both the domestic and global version of JSSE 1.0.2 have strong encryption, why do you have two versions?
    A: There are two versions to comply with the approved application Sun received from the U.S. Department of Commerce Bureau of Export Affairs. The domestic version supports alternate SSL security providers; the global version supports only the Sun SSL provider.

  13. Q: What versions of the JDKTM does JSSE 1.0.2 support?
    A: Sun's reference implementation supports JavaTM 2 SDK, Standard Edition, version 1.2.1 or later. The JSSE API is implementable on either JDK 1.1.x or JavaTM 2 Platform, Standard Edition.

  14. Q: Does the reference implementation have the ability to do RSA encryption?
    A: Yes, JSSE 1.0.2 contains RSA encryption.

  15. Q: What standard(s) does JSSE 1.0.2 follow?
    A: JSSE 1.0.1 provides Secure Sockets Layer (SSL) v3 and Transport Layer Security (TLS) 1.0 support to the JavaTM 2 Platform.

  16. Q: What version of SSL is supported?
    A: JSSE 1.0.2 supports SSL version 3. It is widely available and generally believed to be more secure than version 2. SSL was originally developed by Netscape. You can find out more about SSL by looking at
    Netscape SSL information or the SSL 3.0 Protocol Internet Draft.

  17. Q: Is the reference implementation of JSSE written in the JavaTM programming language?
    A: Yes, the reference implementation is written in the JavaTM programming language.

  18. Q: Is there any sample source code available?
    A: Sample source code, including directions for running the sample code, is provided with the JSSE 1.0.2 distribution as a separate bundle.

  19. Q: Something is not working. How can I debug what is going wrong?
    A: Use the dynamic debug tracing support. This is similar to that used for debugging access control failures in JavaTM 2. You can configure this via the javax.net.debug system property. A value of "help" will dump out the various options. For example:

    java -Djavax.net.debug=help SomeClass

  20. Q: It seems the first SSL connection takes longer than subsequent connections. Is there anything I can do to improve the performance of the first connection?
    A: The SSLContext needs a java.security.SecureRandom object. It is expensive to seed a SecureRandom object. You should see better performance for the first connection if you can provide a pre-seeded SecureRandom object when initializing the SSLContext. However, extreme care should be taken in such action as seeding is an important aspect of cryptographic effectiveness.

  21. Q: What troubleshooting tips can you provide?
    A: Troubleshooting Tips:

    JSSE Package Not Found During Compilation

    Problem: When compiling a program that uses the JSSE 1.0.2 packages, one of the following errors occur:

        Package com.sun.net.ssl not found in import.
    
        Package javax.net not found in import.
    
        Package javax.net.ssl not found in import.
    
        Package javax.security.cert not found in import.
    

    Cause: The JSSE JAR files are not installed properly.

    Solution: JSSE 1.0.2 is supplied as an extension to the Java 2 platform. Its JAR files can be installed either as "installed" extensions (recommended) or as "bundled" extensions. A JAR file is considered an "installed" extension if it is stored in a particular directory established for all installed extensions, as described in http://java.sun.com/products/jsse/install.html, and no class path modifications are needed. "Bundled" extensions may be bundled with applications or made available in a separate directory. If they are bundled with an application, be sure to specify them in the Class-Path attribute in the application's manifest file. Otherwise, be sure to set the Java CLASSPATH variable correctly so the JSSE JAR files can be found. For more information about bundled extensions, see Bundled Extensions.

    Runtime Exception: SSL Service Not Available

    Problem: When running a program that uses JSSE 1.0.2, an exception occurs indicating that an SSL service is not available. For example, an exception similar to one of the following occurs:

        Exception in thread "main"
            java.net.SocketException: no SSL Server Sockets
    
        Exception in thread "main":
            SSL implementation not available
    

    Cause 1: The cryptographic service provider is not registered properly.

    Solution 1: Before using JSSE 1.0.2, you must register the SunJSSE provider, either statically by modifying the java.security file or dynamically by calling the Security.addProvider method, as described in http://java.sun.com/products/jsse/install.html.

    Cause 2: There was a problem with SSLContext initialization, for example due to a corrupted keystore. (Note: One vendor has shipped a keystore in an unknown format, and that may cause this type of error.)

    Solution 2: Check initialization parameters. Ensure any keystores specified are valid (e.g., by trying to use the keytool to examine them).

    Runtime Exception: untrusted cert chains

    Problem: When negotiating an SSL connection, the client or server throws one of the following exceptions:

        javax.net.ssl.SSLException: untrusted server cert chain
        javax.net.ssl.SSLException: untrusted client cert chain
    

    Cause 1: This is generally caused by the remote side sending a certificate that is unknown to the local side.

    Solution 1: The best way to debug this type of problem is to turn on debugging and watch as certificates are loaded and when certificates are received via the network connection. Most likely, the received certificate is unknown to the trust mechanism because the wrong trust file was loaded.

    Cause 2: The system clock is not set correctly.

    Solution 2: If the clock is not set correctly, the perceived time may be outside the validity period on one of the certificates, and unless the certificate can be replaced with a valid one from a truststore, the system must assume that the certificate is invalid, and therefore throw the exception.

    Cause 3: Older versions of Java 2 Enterprise Edition use earlier versions of JSSE. In particular, some previous versions of J2EE shipped with JSSE 1.0, which couldn't replace received expired certificates with current ones from a truststore.

    Solution 3: Be sure that the new JSSE jar files occur in the class path(s) ahead of any older J2EE jar files.

    Runtime Exception: Class Definition Not Found

    Problem: When running a program that uses JSSE 1.0.2, an exception occurs indicating that a JSSE class definition cannot be found. For example, an exception similar to the following occurs:

        Exception in thread "main" java.lang.NoClassDefFoundError:
            javax/net/ssl/SSLServerSocketFactory
    

    Cause: The JSSE JAR files are not installed properly.

    Solution: JSSE must be installed as an extension to the Java 2 Platform. Install the JSSE JAR files as discussed in the Solution to the JSSE Package Not Found During Compilation problem shown above.

    Runtime Exception: No Cipher Suites in Common

    Problem: When using Netscape Navigator or Microsoft Internet Explorer (IE) to access files on a server that only has DSA-based certificates, a runtime exception occurs indicating that there are no cipher suites in common.

    Cause: By default, certificates created with keytool use DSA public keys. Navigator and IE do not use DSA public keys in their enabled cipher suites.

    Solution: To interact with Navigator or IE, you should create certificates that use RSA-based keys. To do this, you need to specify the -keyalg RSA option when using keytool. For example:

        keytool -genkey -alias duke -keystore testkeys -keyalg rsa