diff options
Diffstat (limited to '')
9 files changed, 1962 insertions, 0 deletions
diff --git a/security/nss/doc/rst/legacy/jss/4.3.1_release_notes/index.rst b/security/nss/doc/rst/legacy/jss/4.3.1_release_notes/index.rst new file mode 100644 index 0000000000..21cda12719 --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/4.3.1_release_notes/index.rst @@ -0,0 +1,174 @@ +.. _mozilla_projects_nss_jss_4_3_1_release_notes: + +4.3.1 Release Notes +=================== + +.. _release_date_2009-12-02: + +`Release Date: 2009-12-02 <#release_date_2009-12-02>`__ +------------------------------------------------------- + +.. container:: + +`Introduction <#introduction>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services for Java (JSS) 4.3.1 is a minor release with the following new + features: + + - Support for SSL3 & TLS Renegotiation Vulnerability + - Support to explicitly set the key usage for the generated private key + + JSS 4.3.1 is `tri-licensed <https://www.mozilla.org/MPL>`__ under MPL 1.1/GPL 2.0/LGPL 2.1. + +.. _new_in_jss_4.3.1: + +`New in JSS 4.3.1 <#new_in_jss_4.3.1>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A list of bug fixes and enhancement requests were implemented in this release can be obtained by + running this `bugzilla + query <http://bugzilla.mozilla.org/buglist.cgi?product=JSS&target_milestone=4.3.1&target_milestone=4.3.1&bug_status=RESOLVED&resolution=FIXED>`__ + + **JSS 4.3.1 requires :ref:`mozilla_projects_nss_3_12_5_release_notes` or higher.** + + .. rubric:: SSL3 & TLS Renegotiation Vulnerability + :name: ssl3_tls_renegotiation_vulnerability + + See `CVE-2009-3555 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2009-3555>`__ and `US-CERT + VU#120541 <http://www.kb.cert.org/vuls/id/120541>`__ for more information about this security + vulnerability. + + All SSL/TLS renegotiation is disabled by default in NSS 3.12.5 and therefore will be disabled by + default with JSS 4.3.1. This will cause programs that attempt to perform renegotiation to + experience failures where they formerly experienced successes, and is necessary for them to not + be vulnerable, until such time as a new safe renegotiation scheme is standardized by the IETF. + + If an application depends on renegotiation feature, it can be enabled by setting the environment + variable NSS_SSL_ENABLE_RENEGOTIATION to 1. By setting this environmental variable, the fix + provided by these patches will have no effect and the application may become vulnerable to the + issue. + + This default setting can also be changed within the application by using the following JSS + methods: + + - SSLServerSocket.enableRenegotiation(int mode) + - SSLSocket.enableRenegotiation(int mode) + - SSLSocket.enableRenegotiationDefault(int mode) + + The mode of renegotiation that the peer must use can be set to the following: + + - SSLSocket.SSL_RENEGOTIATE_NEVER - Never renegotiate at all. (Default) + - SSLSocket.SSL_RENEGOTIATE_UNRESTRICTED - Renegotiate without + restriction, whether or not the peer's client hello bears the + renegotiation info extension (like we always did in the past). + - SSLSocket.SSL_RENEGOTIATE_REQUIRES_XTN - NOT YET IMPLEMENTED + + .. rubric:: Explicitly set the key usage for the generated private key + :name: explicitly_set_the_key_usage_for_the_generated_private_key + + | In PKCS #11, each keypair can be marked with the operations it will + | be used to perform. Some tokens require that a key be marked for + | an operation before the key can be used to perform that operation; + | other tokens don't care. NSS/JSS provides a way to specify a set of + | flags and a corresponding mask for these flags. + + - see generateECKeyPairWithOpFlags + - see generateRSAKeyPairWithOpFlags + - see generateDSAKeyPairWithOpFlags + +.. _distribution_information: + +`Distribution Information <#distribution_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS is checked into ``mozilla/security/jss/``. + - The CVS tag for the JSS 4.3.1 release is ``JSS_4_3_1_RTM``. + - Source tarballs are available from + `ftp://ftp.mozilla.org/pub/mozilla.or...-4.3.1.tar.bz2 <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_1_RTM/src/jss-4.3.1.tar.bz2>`__ + - Binary releases are no longer available on mozilla. JSS is a JNI library we provide the + jss4.jar but expect you to build the JSS's matching JNI shared library. We provide the + jss4.jar in case you do not want to obtain your own JCE code signing certificate. JSS is a + JCE provider and therefore the jss4.jar must be signed. + `ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_1_RTM <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_1_RTM/>`__. + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Documentation for JSS 4.3.1 is available as follows: + + - `Build Instructions for JSS 4.3.1 </jss_build_4.3.1.html>`__ + - Javadoc `[online] </javadoc>`__ + `[zipped] <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_1_RTM/doc/JSS_4_3_1_RTM-doc.zip>`__ + - Read the instructions on `using JSS </using_jss.html>`__. + - Source may be viewed with a browser (via the MXR tool) at + http://mxr.mozilla.org/mozilla/source/security/jss/ + - The RUN TIME behavior of JSS can be affected by the + :ref:`mozilla_projects_nss_reference_nss_environment_variables`. + +.. _platform_information: + +`Platform Information <#platform_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - You can check out the source from CVS by + + .. note:: + + cvs co -r JSS_4_3_1_RTM JSS + + - JSS 4.3.1 works with JDK versions 4 or higher we suggest the latest. + + - JSS 4.3.1 requires :ref:`mozilla_projects_nss_3_12_5` or higher. + + - JSS 4.3.1 requires `NSPR 4.7.1 <https://www.mozilla.org/projects/nspr/release-notes/>`__ or + higher. + + - JSS only supports the native threading model (no green threads). + +.. _known_bugs_and_issues: + +`Known Bugs and Issues <#known_bugs_and_issues>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - For a list of reported bugs that have not yet been fixed, `click + here. <http://bugzilla.mozilla.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&&product=JSS>`__ + Note that some bugs may have been fixed since JSS 4.3.1 was released. + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS 4.3.1 is backwards compatible with JSS 4.2. Applications compiled against JSS 4.2 will + work with JSS 4.3.1. + - The 4.3.1 version of libjss4.so/jss4.dll must only be used with jss4.jar. In general, a JSS + JAR file must be used with the JSS shared library from the exact same release. + - To obtain the version info from the jar file use, + "System.out.println(org.mozilla.jss.CryptoManager.JAR_JSS_VERSION)" and to check the shared + library: strings libjss4.so \| grep -i header + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Bugs discovered should be reported by filing a bug report with + `bugzilla <http://bugzilla.mozilla.org/enter_bug.cgi?product=JSS>`__. + - You can also give feedback directly to the developers on the Mozilla Cryptography forums... + + - `Mailing list <https://lists.mozilla.org/listinfo/dev-tech-crypto>`__ + - `Newsgroup <http://groups.google.com/group/mozilla.dev.tech.crypto>`__ + - `RSS feed <http://groups.google.com/group/mozilla.dev.tech.crypto/feeds>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/4_3_releasenotes/index.rst b/security/nss/doc/rst/legacy/jss/4_3_releasenotes/index.rst new file mode 100644 index 0000000000..ca2b5e41bd --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/4_3_releasenotes/index.rst @@ -0,0 +1,175 @@ +.. _mozilla_projects_nss_jss_4_3_releasenotes: + +4.3 Release Notes +================= + +.. _release_date_01_april_2009: + +`Release Date: 01 April 2009 <#release_date_01_april_2009>`__ +------------------------------------------------------------- + +.. container:: + +`Introduction <#introduction>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Network Security Services for Java (JSS) 4.3 is a minor release with the following new features: + + - SQLite-Based Shareable Certificate and Key Databases + - libpkix: an RFC 3280 Compliant Certificate Path Validation Library + - PKCS11 needsLogin method + - support HmacSHA256, HmacSHA384, and HmacSHA512 + - support for all NSS 3.12 initialization options + + JSS 4.3 is `tri-licensed <https://www.mozilla.org/MPL>`__ under MPL 1.1/GPL 2.0/LGPL 2.1. + +.. _new_in_jss_4.3: + +`New in JSS 4.3 <#new_in_jss_4.3>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + A list of bug fixes and enhancement requests were implemented in this release can be obtained by + running this `bugzilla + query <http://bugzilla.mozilla.org/buglist.cgi?product=JSS&target_milestone=4.2.5&target_milestone=4.3&bug_status=RESOLVED&resolution=FIXED>`__ + + **JSS 4.3 requires**\ `NSS + 3.12 <https://www.mozilla.org/projects/security/pki/nss/nss-3.12/nss-3.12-release-notes.html>`__\ **or + higher.** + + - New `SQLite-Based Shareable Certificate and Key + Databases <https://wiki.mozilla.org/NSS_Shared_DB>`__ by prepending the string "sql:" to the + directory path passed to configdir parameter for Crypomanager.initialize method or using the + NSS environment variable :ref:`mozilla_projects_nss_reference_nss_environment_variables`. + - Libpkix: an RFC 3280 Compliant Certificate Path Validation Library (see + `PKIXVerify <http://mxr.mozilla.org/mozilla/ident?i=PKIXVerify>`__) + - PK11Token.needsLogin method (see needsLogin) + - support HmacSHA256, HmacSHA384, and HmacSHA512 (see + `HMACTest.java <http://mxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/tests/HMACTest.java>`__) + - support for all NSS 3.12 initialization options (see InitializationValues) + - New SSL error codes (see https://mxr.mozilla.org/security/sour...util/SSLerrs.h) + + - SSL_ERROR_UNSUPPORTED_EXTENSION_ALERT + SSL_ERROR_CERTIFICATE_UNOBTAINABLE_ALERT + SSL_ERROR_UNRECOGNIZED_NAME_ALERT + SSL_ERROR_BAD_CERT_STATUS_RESPONSE_ALERT + SSL_ERROR_BAD_CERT_HASH_VALUE_ALERT + + - New TLS cipher suites (see https://mxr.mozilla.org/security/sour...SSLSocket.java): + + - TLS_RSA_WITH_CAMELLIA_128_CBC_SHA + TLS_DHE_DSS_WITH_CAMELLIA_128_CBC_SHA + TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA + TLS_RSA_WITH_CAMELLIA_256_CBC_SHA + TLS_DHE_DSS_WITH_CAMELLIA_256_CBC_SHA + TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA + + - Note: the following TLS cipher suites are declared but are not yet implemented: + + - TLS_DH_DSS_WITH_CAMELLIA_128_CBC_SHA + TLS_DH_RSA_WITH_CAMELLIA_128_CBC_SHA + TLS_DH_ANON_WITH_CAMELLIA_128_CBC_SHA + TLS_DH_DSS_WITH_CAMELLIA_256_CBC_SHA + TLS_DH_RSA_WITH_CAMELLIA_256_CBC_SHA + TLS_DH_ANON_WITH_CAMELLIA_256_CBC_SHA + TLS_ECDH_anon_WITH_NULL_SHA + TLS_ECDH_anon_WITH_RC4_128_SHA + TLS_ECDH_anon_WITH_3DES_EDE_CBC_SHA + TLS_ECDH_anon_WITH_AES_128_CBC_SHA + TLS_ECDH_anon_WITH_AES_256_CBC_SHA + +.. _distribution_information: + +`Distribution Information <#distribution_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS is checked into ``mozilla/security/jss/``. + - The CVS tag for the JSS 4.3 release is ``JSS_4_3_RTM``. + - Source tarballs are available from + https://archive.mozilla.org/pub/security/jss/releases/JSS_4_3_RTM/src/jss-4.3.tar.bz2 + - Binary releases are no longer available on mozilla. JSS is a JNI library we provide the + jss4.jar but expect you to build the JSS's matching JNI shared library. We provide the + jss4.jar in case you do not want to obtain your own JCE code signing certificate. JSS is a + JCE provider and therefore the jss4.jar must be signed. + https://archive.mozilla.org/pub/security/jss/releases/JSS_4_3_RTM/ + + -------------- + +`Documentation <#documentation>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Documentation for JSS 4.3 is available as follows: + + - `Build Instructions for JSS 4.3 </jss_build_4.3.html>`__ + - Javadoc `[online] </javadoc>`__ + `[zipped] <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_RTM/doc/JSS_4_3_RTM-doc.zip>`__ + - Read the instructions on `using JSS </using_jss.html>`__. + - Source may be viewed with a browser (via the MXR tool) at + http://mxr.mozilla.org/mozilla/source/security/jss/ + - The RUN TIME behavior of JSS can be affected by the + :ref:`mozilla_projects_nss_reference_nss_environment_variables`. + +.. _platform_information: + +`Platform Information <#platform_information>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS 4.3 works with JDK versions 4 or higher we suggest the latest. + - JSS 4.3 requires `NSS + 3.12 <https://www.mozilla.org/projects/security/pki/nss/nss-3.12/nss-3.12-release-notes.html>`__ + or higher. + - JSS 4.3 requires `NSPR 4.7.1 <https://www.mozilla.org/projects/nspr/release-notes/>`__ or + higher. + - JSS only supports the native threading model (no green threads). + + -------------- + +.. _known_bugs_and_issues: + +`Known Bugs and Issues <#known_bugs_and_issues>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - For a list of reported bugs that have not yet been fixed, `click + here. <http://bugzilla.mozilla.org/buglist.cgi?bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&&product=JSS>`__ + Note that some bugs may have been fixed since JSS 4.3 was released. + + -------------- + +`Compatibility <#compatibility>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS 4.3 is backwards compatible with JSS 4.2. Applications compiled against JSS 4.2 will work + with JSS 4.3. + - The 4.3 version of libjss4.so/jss4.dll must only be used with jss4.jar. In general, a JSS JAR + file must be used with the JSS shared library from the exact same release. + - To obtain the version info from the jar file use, + "System.out.println(org.mozilla.jss.CryptoManager.JAR_JSS_VERSION)" and to check the shared + library: strings libjss4.so \| grep -i header + + -------------- + +`Feedback <#feedback>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - Bugs discovered should be reported by filing a bug report with + `bugzilla <http://bugzilla.mozilla.org/enter_bug.cgi?product=JSS>`__. + - You can also give feedback directly to the developers on the Mozilla Cryptography forums... + + - `Mailing list <https://lists.mozilla.org/listinfo/dev-tech-crypto>`__ + - `Newsgroup <http://groups.google.com/group/mozilla.dev.tech.crypto>`__ + - `RSS feed <http://groups.google.com/group/mozilla.dev.tech.crypto/feeds>`__
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.3.x/index.rst b/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.3.x/index.rst new file mode 100644 index 0000000000..a864a452ee --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.3.x/index.rst @@ -0,0 +1,99 @@ +.. _mozilla_projects_nss_jss_build_instructions_for_jss_4_3_x: + +Build instructions for JSS 4.3.x +================================ + +.. _build_instructions_for_jss_4.3.x: + +`Build Instructions for JSS 4.3.x <#build_instructions_for_jss_4.3.x>`__ +------------------------------------------------------------------------ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + Before building JSS, you need to set up your system as follows: + + #. Build NSPR/NSS by following the + :ref:`mozilla_projects_nss_reference_building_and_installing_nss_build_instructions`, + #. To check that NSS built correctly, run ``all.sh`` (in ``mozilla/security/nss/tests``) and + examine the results (in + ``mozilla/test_results/security/``\ *computername*.#\ ``/results.html``. + #. Install a Java compiler and runtime. JSS supports Java version 1.5 or later. We suggest you + use the latest. + #. You must have Perl version 5.005 or later. + + Now you are ready to build JSS. Follow these steps: + + #. Switch to the appropriate directory and check out JSS from the root of your source tree. + + .. code:: + + cvs co -r JSS_4_3_1_RTM mozilla/security/jss + + or + + .. code:: + + cvs co -r JSS_4_3_RTM mozilla/security/jss + + #. Setup environment variables needed for compiling Java source. The ``JAVA_HOME`` variable + indicates the directory containing your Java SDK installation. Note, on Windows platforms it + is best to have JAVA_HOME set to a directory path that doest not have spaces. + + **Unix** + + .. code:: + + setenv JAVA_HOME /usr/local/jdk1.5.0 (or wherever your JDK is installed) + + **Windows** + + .. code:: + + set JAVA_HOME=c:\programs\jdk1.5.0 (or wherever your JDK is installed) + + **Windows (Cygnus)** + + .. code:: + + JAVA_HOME=/cygdrive/c/programs/jdk1.5.0 (or wherever your JDK is installed) + export JAVA_HOME + + | **Windows build Configurations WINNT vs WIN95** + + .. code:: + + As of NSS 3.15.4, NSPR/NSS/JSS build generates a "WIN95" configuration by default on Windows. + We recommend most applications use the "WIN95" configuration. If you want JSS to be used + with your applet and the Firefox browser than you must build WIN95. (See JSS FAQ) + The "WIN95" configuration supports all versions of Windows. The "WIN95" name is historical; + it should have been named "WIN32". + To generate a "WINNT" configuration, set OS_TARGET=WINNT and build NSPR/NSS/JSS WIN95. + + | Mac OS X + | It has been recently reported that special build instructions are necessary to succeed + building JSS on OSX. Please + see `HOWTO_successfully_compile_JSS_and_NSS_for_32_and_64_bits_on_OSX_10.6_(10.6.7) </HOWTO_successfully_compile_JSS_and_NSS_for_32_and_64_bits_on_OSX_10.6_(10.6.7)>`__ + for contributed instructions. + | + + #. Build JSS. + + .. code:: + + cd mozilla/security/jss + gmake + + #. Sign the JSS jar. + + .. code:: + + If you're intention is to modify and build the JSS source you + need to Apply for your own JCE code-signing certificate + + If you made no changes and your goal is to build JSS you can use the + signed binary release of the jss4.jar from ftp.mozilla.org. + with your built jss4 JNI shared library. + + Next, you should read the instructions on `using JSS <Using_JSS>`__.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.4.x/index.rst b/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.4.x/index.rst new file mode 100644 index 0000000000..bdbea81953 --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/build_instructions_for_jss_4.4.x/index.rst @@ -0,0 +1,19 @@ +.. _mozilla_projects_nss_jss_build_instructions_for_jss_4_4_x: + +Build instructions for JSS 4.4.x +================================ + +.. _build_instructions_for_jss_4.4.x: + +`Build Instructions for JSS 4.4.x <#build_instructions_for_jss_4.4.x>`__ +------------------------------------------------------------------------ + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + + To build JSS see `Upstream JSS Build/Test + Instructions <https://hg.mozilla.org/projects/jss/file/tip/README>`__ + + `Next, you should read the instructions + on <https://hg.mozilla.org/projects/jss/file/tip/README>`__ `using JSS <Using_JSS>`__.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/index.rst b/security/nss/doc/rst/legacy/jss/index.rst new file mode 100644 index 0000000000..c09374dbc6 --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/index.rst @@ -0,0 +1,165 @@ +.. _mozilla_projects_nss_jss: + +JSS +=== + +`Documentation <#documentation>`__ +---------------------------------- + +.. container:: + + .. warning:: + + **The JSS project has been relocated!** + + As of April 6, 2018, JSS has been migrated from Mercurial on Mozilla to Git on Github. + + JSS source should now be checked out from the Github: + + - git clone git@github.com:dogtagpki/jss.git + -- OR -- + - git clone https://github.com/dogtagpki/jss.git + + All future upstream enquiries to JSS should now use the Pagure Issue Tracker system: + + - https://pagure.io/jss/issues + + Documentation regarding the JSS project should now be viewed at: + + - http://www.dogtagpki.org/wiki/JSS + + **NOTE: As much of the JSS documentation is sorely out-of-date, updated information will be a + work in progress, and many portions of any legacy documentation will be re-written over the + course of time. Stay tuned!** + + Legacy JSS information can still be found at: + + - SOURCE: https://hg.mozilla.org/projects/jss + - ISSUES: https://bugzilla.mozilla.org/buglist.cgi?product=JSS + - WIKI: :ref:`mozilla_projects_nss_jss` + + Network Security Services for Java (JSS) is a Java interface to + `NSS <https://developer.mozilla.org/en-US/docs/NSS>`__. JSS supports most of the security + standards and encryption technologies supported by :ref:`mozilla_projects_nss_reference`. JSS + also provides a pure Java interface for ASN.1 types and BER/DER encoding. + + JSS offers a implementation of Java SSL sockets that uses NSS's SSL/TLS implementation rather + than Sun's JSSE implementation. You might want to use JSS's own `SSL + classes <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases>`__ if you want to use some + of the capabilities found in NSS's SSL/TLS library but not found in JSSE. + + NSS is the cryptographic module where all cryptographic operations are performed. JSS essentially + provides a Java JNI bridge to NSS C shared libraries. When NSS is put in FIPS mode, JSS ensures + FIPS compliance by ensuring that all cryptographic operations are performed by the NSS + cryptographic module. + + JSS offers a JCE provider, `"Mozilla-JSS" JCA Provider notes <JSS/JSS_Provider_Notes>`__. + + JSS, jss4.jar, is still built with JDK 1.4.2. While JDK 1.4.2 is EOL'd and all new product + development should be using the latest + `JavaSE <http://java.sun.com/javase/downloads/index.jsp>`__, legacy business products that must + use JDK 1.4 or 1.5 can continue to add NSS/JSS security fixes/enhancements. + + JSS is used by Red Hat and Sun products that do crypto in Java. JSS is available under the + Mozilla Public License, the GNU General Public License, and the GNU Lesser General Public + License. JSS requires `NSPR <https://developer.mozilla.org/en-US/docs/NSPR>`__ and + `NSS <https://developer.mozilla.org/en-US/docs/NSS>`__. + + Java provides a JCE provider called SunPKCS11 (see `Java PKCS#11 Reference + Guide <http://download.java.net/jdk7/docs/technotes/guides/security/p11guide.html>`__.) SunPKCS11 + can be configured to use the NSS module as the crytographic provider. If you are planning to just + use JSS JCE provider as a bridge to NSS's FIPS validated PKCS#11 module, then the SunPKCS11 JCE + provider may do all that you need. Note that Java 1.5 claimed no FIPS compliance, and `Java + 1.6 <http://java.sun.com/javase/6/docs/technotes/guides/security/enhancements.html>`__ or higher + needs to be used. A current limitation to the configured SunPKCS11-NSS bridge configuration is if + you add a PKCS#11 module to the NSS database such as for a smartcard, you won't be able to access + that smartcard through the SunPKCS11-NSS bridge. If you use JSS, you can easily get lists of + modules and tokens that are configured in the NSS DB and freely access all of it. + + +-------------------------------------------------+-------------------------------------------------+ + | Before you use JSS, you should have a good | .. rubric:: Community | + | understanding of the crypto technologies it | :name: Community | + | uses. You might want to read these documents: | | + | | - View Mozilla Cryptography forums... | + | - `Introduction to Public-Key | | + | Crypt | - `Mailing | + | ography <https://developer.mozilla.org/en-US/do | list <https:/ | + | cs/Introduction_to_Public-Key_Cryptography>`__. | /lists.mozilla.org/listinfo/dev-tech-crypto>`__ | + | Explains the basic concepts of public-key | - `Newsgroup <http://grou | + | cryptography that underlie NSS and JSS. | ps.google.com/group/mozilla.dev.tech.crypto>`__ | + | - `Introduction to | - `RSS | + | SSL <https://developer. | feed <http://groups.goo | + | mozilla.org/en-US/docs/Introduction_to_SSL>`__. | gle.com/group/mozilla.dev.tech.crypto/feeds>`__ | + | Introduces the SSL protocol, including | | + | information about cryptographic ciphers | .. rubric:: Related Topics | + | supported by SSL and the steps involved in | :name: Related_Topics | + | the SSL handshake. | | + | | - `Security <https: | + | For information on downloading NSS releases, | //developer.mozilla.org/en-US/docs/Security>`__ | + | see `NSS sources building | | + | testing <NSS_Sources_Building_Te | | + | sting>`__\ `. <NSS_Sources_Building_Testing>`__ | | + | | | + | Read `Using JSS <JSS/Using_JSS>`__ to get you | | + | started with development after you've built and | | + | downloaded it. | | + | | | + | .. rubric:: Release Notes | | + | :name: Release_Notes | | + | | | + | - `4.3.1 Release | | + | Notes </4.3.1_Release_Notes>`__ | | + | - `4.3 Release | | + | Notes <https://developer. | | + | mozilla.org/en-US/docs/JSS/4_3_ReleaseNotes>`__ | | + | - `Older Release | | + | Notes <http://www-archive.mozil | | + | la.org/projects/security/pki/jss/index.html>`__ | | + | | | + | .. rubric:: Build Instructions | | + | :name: Build_Instructions | | + | | | + | - :re | | + | f:`mozilla_projects_nss_jss_build_instructions_ | | + | for_jss_4_4_x#build_instructions_for_jss_4_4_x` | | + | - `Building JSS | | + | 4.3.x <https://developer.mozilla.org/en-U | | + | S/docs/JSS/Build_instructions_for_JSS_4.3.x>`__ | | + | - `Older Build | | + | Instructions <http://www-archive.mozil | | + | la.org/projects/security/pki/jss/index.html>`__ | | + | | | + | .. rubric:: Download or View Source | | + | :name: Download_or_View_Source | | + | | | + | - `Download binaries, source, and | | + | javadoc <ftp://ftp.mozilla | | + | .org/pub/mozilla.org/security/jss/releases/>`__ | | + | - `View the source | | + | online <http://m | | + | xr.mozilla.org/mozilla/source/security/jss/>`__ | | + | | | + | .. rubric:: Testing | | + | :name: Testing | | + | | | + | - `JSS | | + | tests <https:// | | + | hg.mozilla.org/projects/jss/file/tip/README>`__ | | + | | | + | .. rubric:: Frequently Asked Questions | | + | :name: Frequently_Asked_Questions | | + | | | + | - `JSS FAQ <JSS/JSS_FAQ>`__ | | + | | | + | Information on JSS planning can be found at | | + | `wik | | + | i.mozilla.org <http://wiki.mozilla.org/NSS>`__, | | + | including: | | + | | | + | - `NSS FIPS | | + | Validati | | + | on <http://wiki.mozilla.org/FIPS_Validation>`__ | | + | - `NSS Roadmap | | + | | | + | page <http://wiki.mozilla.org/NSS:Roadmap>`__ | | + +-------------------------------------------------+-------------------------------------------------+
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/jss_faq/index.rst b/security/nss/doc/rst/legacy/jss/jss_faq/index.rst new file mode 100644 index 0000000000..d419586452 --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/jss_faq/index.rst @@ -0,0 +1,217 @@ +.. _mozilla_projects_nss_jss_jss_faq: + +JSS FAQ +======= + +.. _jss_frequently_asked_questions: + +`JSS Frequently Asked Questions <#jss_frequently_asked_questions>`__ +-------------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org:119/mozilla.dev.tech.crypto>`__ + + **Content:** + + - `What versions of JDK and JCE do you suggest? <#jdkjce1>`__ + - `Does JSS have 64 bit support? <#64bit>`__ + - `Is JSS FIPS Compliant? <#fips>`__ + - `Is there any sample code and documentation? <#sample>`__ + - `If I don't call setCipherPolicy, is the DOMESTIC policy used by + default? <#setcipherpolicy>`__ + - `My SSL connection is hanging on Windows? <#ssl_hanging>`__ + - `How can I tell which SSL/TLS ciphers JSS supports? <#ssltls_cipher>`__ + - `How can I debug my SSL connection? <#ssl_debug>`__ + - `Can you explain JSS SSL certificate approval callbacks? <#ssl_callback>`__ + - `Can I have multiple JSS instances reading separate db's? <#jss_instance>`__ + - `Once JSS initialized, I can't get anymore instances with + CertificateFactory.getInstance(X.509)? <#jss_init>`__ + - `Is it possible to sign data in Java with JSS? <#sign_date>`__ + - `How do I convert org.mozilla.jss.crypto.X509Certificate to + org.mozilla.jss.pkix.cert.Certificate? <#convertx509>`__ + - `How do I convert org.mozilla.jss.pkix.cert to + org.mozilla.jss.crypto.X509Certificate? <#convertpkix>`__ + - `Is it possible to use JSS to access cipher functionality from pkcs11 modules? <#pkc11>`__ + - `Can you explain token names and keys with regards to JSS? <#token_name>`__ + - `JSS 3.2 has JCA support. When will JSS have JSSE support? <#jssjsse>`__ + + **What versions of JDK and JRE do you suggest?** + + - JSS 3.x works with JDK versions 1.2 or higher, except version 1.3.0. Most attention for future + development and bug fixing will go to JDK 1.4 and later, so use that if you can. If you are + using JDK 1.3.x, you will need to use at least version 1.3.1--see `bug + 113808 <http://bugzilla.mozilla.org/show_bug.cgi?id=113808>`__. JSS only supports the native + threading model (no green threads). For JSS 3.2 and higher, if you use JDK 1.4 or higher you + will not need to install the JCE, but if you using an earlier version of the JDK then you will + also have to install JCE 1.2.1. See also the document `Using JSS <Using_JSS>`__. + + **Does JSS have 64 bit support?** + + - Yes, JSS 3.2 and higher supports 64 bit. You will need JDK 1.4 or higher and all the 64 bit + versions of NSPR, and NSS. As well you must use the java flag -d64 to specify the 64-bit data + model. + + **Is JSS FIPS Compliant?** + + - NSS is a FIPS-certified software library. JSS is considered a FIPS-compliant software library + since it only uses NSS for any and all crypto routines. + + **Is there any sample code and documentation?** + + - The `Using JSS <Using_JSS>`__ document describes how to set up your environment to run JSS. + The only other documentation is the + `Javadoc <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_RTM/doc/JSS_4_3_RTM-doc.zip>`__. + + JSS example code is essentially developer test code; with that understanding, the best + directory to look for sample code is in the org/mozilla/jss/tests directory: + + http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/tests + + | `org/mozilla/jss/tests/CloseDBs.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/CloseDBs.java#47>`__ + | `org/mozilla/jss/tests/KeyFactoryTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/KeyFactoryTest.java#81>`__ + | `org/mozilla/jss/tests/DigestTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/DigestTest.java#44>`__ + | `org/mozilla/jss/tests/JCASigTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/JCASigTest.java#50>`__ + | `org/mozilla/jss/tests/KeyWrapping.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/KeyWrapping.java#45>`__ + | `org/mozilla/jss/tests/ListCerts.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/ListCerts.java#40>`__ + | `org/mozilla/jss/tests/PK10Gen.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/PK10Gen.java#43>`__ + | `org/mozilla/jss/tests/SDR.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SDR.java#47>`__ + | `org/mozilla/jss/tests/SelfTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SelfTest.java#46>`__ + | `org/mozilla/jss/tests/SetupDBs.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SetupDBs.java#42>`__ + | `org/mozilla/jss/tests/SigTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SigTest.java#64>`__ + | `org/mozilla/jss/tests/SymKeyGen.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SymKeyGen.java#44>`__ + | `org/mozilla/jss/tests/TestKeyGen.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/TestKeyGen.java#64>`__ + | `org/mozilla/jss/tests/SSLClientAuth.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/SSLClientAuth.java#99>`__ + | `org/mozilla/jss/tests/ListCACerts.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/ListCACerts.java#8>`__ + | `org/mozilla/jss/tests/KeyStoreTest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/KeyStoreTest.java#68>`__ + | `org/mozilla/jss/tests/VerifyCert.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/tests/VerifyCert.java#86>`__ + + SSL examples: + + | `org/mozilla/jss/tests/SSLClientAuth.java <http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/tests/SSLClientAuth.java>`__ + | `org/mozilla/jss/ssl/SSLClient.java <http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/ssl/SSLClient.java>`__ + | `org/mozilla/jss/ssl/SSLServer.java <http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/ssl/SSLServer.java>`__ + | `org/mozilla/jss/ssl/SSLTest.java <http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/ssl/SSLTest.java>`__ + + Other test code that may prove useful: + + | `org/mozilla/jss/asn1/INTEGER.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/asn1/INTEGER.java#131>`__ + | `org/mozilla/jss/asn1/SEQUENCE.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/asn1/SEQUENCE.java#574>`__ + | `org/mozilla/jss/asn1/SET.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/asn1/SET.java#876>`__ + | `org/mozilla/jss/pkcs10/CertificationRequest.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkcs10/CertificationRequest.java#269>`__ + | `org/mozilla/jss/pkcs12/PFX.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkcs12/PFX.java#329>`__ + | `org/mozilla/jss/pkix/cert/Certificate.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/cert/Certificate.java#279>`__ + | `org/mozilla/jss/pkix/cmmf/CertRepContent.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/cmmf/CertRepContent.java#148>`__ + | `org/mozilla/jss/pkix/crmf/CertReqMsg.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/crmf/CertReqMsg.java#265>`__ + | `org/mozilla/jss/pkix/crmf/CertTemplate.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/crmf/CertTemplate.java#530>`__ + | `org/mozilla/jss/pkix/primitive/Name.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/pkix/primitive/Name.java#276>`__ + | `org/mozilla/jss/provider/javax/crypto/JSSSecretKeyFactorySpi.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/provider/javax/crypto/JSSSecretKeyFactorySpi.java#287>`__ + | `org/mozilla/jss/util/UTF8Converter.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/util/UTF8Converter.java#302>`__ + | `org/mozilla/jss/util/Base64InputStream.java <http://lxr.mozilla.org/security/source/security/jss/org/mozilla/jss/util/Base64InputStream.java#237>`__ + | `jss/samples/PQGGen.java <http://lxr.mozilla.org/security/source/security/jss/samples/PQGGen.java#44>`__ + | `jss/samples/pkcs12.java <http://lxr.mozilla.org/security/source/security/jss/samples/pkcs12.java#57>`__ + + **If I don't call setCipherPolicy, is the DOMESTIC policy used by default?** + + - Yes, domestic is the default because we call NSS_SetDomesticPolicy() during + CryptoManager.initialize(). setCipherPolicy does not need to be called by a JSS app unless + that app wants to limit itself to export-allowed cipher suites. + + **My SSL connection is hanging on Windows?** + + - NSPR makes use of NT vs. Windows distinction and provides different NT and Windows builds. + Many Netscape products, including NSS, have NT and Windows builds that are essentially the + same except one difference: one is linked with the NT version of NSPR and the other is linked + with the Windows version of NSPR. The NT fiber problem affects applications that call blocking + system calls from the primordial thread. Either use the WIN 95 version of NSPR/NSS/JSS + components (essentially all non-fiber builds) or set the environment variable + NSPR_NATIVE_THREADS_ONLY=1. You can find more information in bugzilla bug + `102251 <http://bugzilla.mozilla.org/show_bug.cgi?id=102251>`__ SSL session cache locking + issue with NT fibers + + **How can I tell which SSL/TLS ciphers JSS supports?** + + - Check + http://lxr.mozilla.org/mozilla/source/security/jss/org/mozilla/jss/ssl/SSLSocket.java#730 + + **How can I debug my SSL connection?** + + - By using the NSS tool :ref:`mozilla_projects_nss_tools_ssltap` + + **Can you explain JSS SSL certificate approval callbacks?** + + - NSS has three callbacks related to certificates. JSS has two. But JSS combines two of the NSS + callbacks into one. + + - NSS's three SSL cert callbacks are: + + #. SSL_AuthCertificateHook sets a callback to authenticate the peer's certificate. It is + called instead of NSS's routine for authenticating certificates. + #. SSL_BadCertHook sets a callback that is called when NSS's routine fails to authenticate the + certificate. + #. SSL_GetClientAuthDataHook sets a callback to return the local certificate for SSL client + auth. + + JSS's two callbacks are: + + #. SSLCertificateApprovalCallback is a combination of SSL_AuthCertificateHook and + SSL_BadCertHook. It runs NSS's cert authentication check, then calls the callback + regardless of whether the cert passed or failed. The callback is told whether the cert + passed, and then can do anything extra that it wants to do before making a final decision. + #. SSLClientCertificateSelectionCallback is analogous to SSL_GetClientAuthDataHook. + + | + | **Can I have multiple JSS instances reading separate db's?** + + - No, you can only have one initialized instance of JSS for each database. + + **Once JSS initialized, I can't get anymore instances with + CertificateFactory.getInstance("X.509")?** + + - In version previous to JSS 3.1, JSS removes the default SUN provider on startup. Upgrade to + the latest JSS, or, in the ``CryptoManager.InitializationValues`` object you pass to + ``CryptoManager.initialize()``, set ``removeSunProivider=true``. + + **Is it possible to sign data in Java with JSS? What I am trying to do is write a Java applet + that will access the Netscape certificate store, retrieve a X509 certificate and then sign some + data.** + + - The best way to do this is with the PKCS #7 signedData type. Check out the + `javadoc <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_RTM/doc/JSS_4_3_RTM-doc.zip>`__. + + **How do I convert org.mozilla.jss.crypto.X509Certificate to + org.mozilla.jss.pkix.cert.Certificate?** + + - .. code:: + + import java.io.ByteArrayInputStream; + + [...] + + Certificate cert = (Certificate) ASN1Util.decode( + Certificate.getTemplate(),x509Cert.getEncoded() ); + + **How do I convert org.mozilla.jss.pkix.cert to org.mozilla.jss.crypto.X509Certificate?** + + - `Cryptomanager.importCertPackage() <ftp://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/JSS_4_3_RTM/doc/JSS_4_3_RTM-doc.zip>`__ + + **Is it possible to use JSS to acces cipher functionality from pkcs11 modules?** + + - Yes. Before JSS 3.2 you would use CryptoManager to obtain the CryptoToken you want to use, + then call CryptoToken.getCipherContext() to get an encryption engine. But as of JSS 3.2 you + would use the `JSS JCA provider <JSS_Provider_Notes>`__. + + **Can you explain token names and keys with regards to JSS?** + + - The token name is different depending on which application you are running. In JSS, the token + is called "Internal Key Storage Token". You can look it up by name using + CryptoManager.getTokenByName(), but a better way is to call + CryptoManager.getInternalKeyStorageToken(), which works no matter what the token is named. In + general, a key is a handle to an underlying object on a PKCS #11 token, not merely a Java + object residing in memory. Symmetric Key usage: basically encrypt/decrypt is for data and + wrap/unwrap is for keys. + + J\ **SS 3.2 has JCA support. When will JSS have JSSE support?** + + - Not in the near future due to pluggability is disabled in the JSSE version included in J2SE + 1.4.x for export control reasons.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/jss_provider_notes/index.rst b/security/nss/doc/rst/legacy/jss/jss_provider_notes/index.rst new file mode 100644 index 0000000000..9db0654c2c --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/jss_provider_notes/index.rst @@ -0,0 +1,489 @@ +.. _mozilla_projects_nss_jss_jss_provider_notes: + +JSS Provider Notes +================== + +.. container:: + + .. warning:: + + This page has been moved to http://www.dogtagpki.org/wiki/JSS_Provider. + +.. _the_mozilla-jss_jca_provider: + +`The Mozilla-JSS JCA Provider <#the_mozilla-jss_jca_provider>`__ +---------------------------------------------------------------- + +.. container:: + + Newsgroup: `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Overview <#overview>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This document describes the JCA Provider shipped with JSS. The provider's name is "Mozilla-JSS". + It implements cryptographic operations in native code using the `NSS <../nss>`__ libraries. + +`Contents <#contents>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Signed JAR file <#signed-jar>`__ + - `Installing the Provider <#installing-provider>`__ + - `Specifying the CryptoToken <#specifying-token>`__ + - `Supported Classes <#supported-classes>`__ + - `What's Not Supported <#not-supported>`__ + + -------------- + +.. _signed_jar_file: + +`Signed JAR file <#signed_jar_file>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - JSS 3.2 implements several JCE (Java Cryptography Extension) algorithms. These algorithms have + at various times been export-controlled by the US government. Sun therefore requires that JAR + files implementing JCE algorithms be digitally signed by an approved organization. Netscape + has this approval and signs the official builds of ``jss32.jar``. At runtime, the JRE + automatically verifies this signature whenever a JSS class is loaded that implements a JCE + algorithm. The verification is transparent to the application (unless it fails and throws an + exception). If you are curious, you can verify the signature on the JAR file using the + ``jarsigner`` tool, which is distributed with the JDK. + + If you build JSS yourself from source instead of using binaries downloaded from mozilla.org, + your JAR file will not have a valid signature. This means you will not be able to use the JSS + provider for JCE algorithms. You have two choices. + + #. Use the binary release of JSS from mozilla.org. + #. Apply for your own JCE code-signing certificate following the procedure at `How to + Implement a Provider for the Java\ TM Cryptography + Extension <http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/HowToImplAProvider.html#Step61>`__. + Then you can sign your own JSS JAR file. + +.. _installing_the_provider: + +`Installing the Provider <#installing_the_provider>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - In order to use any part of JSS, including the JCA provider, you must first call + ``CryptoManager.initialize()``. By default, the JCA provider will be installed in the list of + providers maintained by the ``java.security.Security`` class. If you do not wish the provider + to be installed, create a + :ref:`mozilla_projects_nss_jss_cryptomanager_cryptomanager_initializationvalues` object, set + its ``installJSSProvider`` field to ``false``, and pass the ``InitializationValues`` object to + ``CryptoManager.initialize()``. + +.. _specifying_the_cryptotoken: + +`Specifying the CryptoToken <#specifying_the_cryptotoken>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - All cryptographic operations in JSS and NSS occur on a particular PKCS #11 token, implemented + in software or hardware. There is no clean way to specify this token through the JCA API. By + default, the JSS provider carries out all operations except MessageDigest on the Internal Key + Storage Token, a software token included in JSS/NSS. MessageDigest operations take place by + default on the Internal Crypto Token, another internal software token in JSS/NSS. There is no + good design reason for this difference, but it is necessitated by a quirk in the NSS + implementation. + + In order to use a different token, use ``CryptoManager.setThreadToken()``. This sets the token + to be used by the JSS JCA provider in the current thread. When you call ``getInstance()`` on a + JCA class, the JSS provider checks the current per-thread default token (by calling + ``CryptoManager.getThreadToken()``) and instructs the new object to use that token for + cryptographic operations. The per-thread default token setting is only consulted inside + ``getInstance()``. Once a JCA object has been created it will continue to use the same token, + even if the application later changes the per-thread default token. + + Whenever a new thread is created, its token is initialized to the default, the Internal Key + Storage Token. Thus, the thread token is not inherited from the parent thread. + + The following example shows how you can specify which token is used for various JCA + operations: + + .. code:: + + // Lookup PKCS #11 tokens + CryptoManager manager = CryptoManager.getInstance(); + CryptoToken tokenA = manager.getTokenByName("TokenA"); + CryptoToken tokenB = manager.getTokenByName("TokenB"); + + // Create an RSA KeyPairGenerator using TokenA + manager.setThreadToken(tokenA); + KeyPairGenerator rsaKpg = KeyPairGenerator.getInstance("RSA", "Mozilla-JSS"); + + // Create a DSA KeyPairGenerator using TokenB + manager.setThreadToken(tokenB); + KeyPairGenerator dsaKpg = KeyPairGenerator.getInstance("DSA", "Mozilla-JSS"); + + // Generate an RSA KeyPair. This will happen on TokenA because TokenA + // was the per-thread default token when rsaKpg was created. + rsaKpg.initialize(1024); + KeyPair rsaPair = rsaKpg.generateKeyPair(); + + // Generate a DSA KeyPair. This will happen on TokenB because TokenB + // was the per-thread default token when dsaKpg was created. + dsaKpg.initialize(1024); + KeyPair dsaPair = dsaKpg.generateKeyPair(); + +.. _supported_classes: + +`Supported Classes <#supported_classes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Cipher <#cipher>`__ + + - `DSAPrivateKey <#dsaprivatekey>`__ + + - DSAPublicKey + + - `KeyFactory <#keyfactory>`__ + + - `KeyGenerator <#keygenerator>`__ + + - `KeyPairGenerator <#keypairgenerator>`__ + + - `Mac <#mac>`__ + + - `MessageDigest <#messagedigest>`__ + + - `RSAPrivateKey <#rsaprivatekey>`__ + + - RSAPublicKey + + - `SecretKeyFactory <#secretkeyfactory>`__ + + - `SecretKey <#secretkey>`__ + + - `SecureRandom <#securerandom>`__ + + - `Signature <#signature>`__ + + .. rubric:: What's Not Supported + :name: What's_Not_Supported + + - The following classes don't work very well: + + - **KeyStore:** There are many serious problems mapping the JCA keystore interface onto + NSS's model of PKCS #11 modules. The current implementation is almost useless. Since + these problems lie deep in the NSS design and implementation, there is no clear + timeframe for fixing them. Meanwhile, the ``org.mozilla.jss.crypto.CryptoStore`` class + can be used for some of this functionality. + +.. rubric:: Cipher + :name: Cipher_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms + +.. rubric:: Notes + :name: notes + +- + + - AES + - DES + - DESede (*DES3* ) + - RC2 + - RC4 + - RSA + + - The following modes and padding schemes are supported: + + + +------------------------------+------------------------------+------------------------------+ + | Algorithm | Mode | Padding | + +------------------------------+------------------------------+------------------------------+ + | DES | ECB | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | CBC | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | | PKCS5 Padding | + +------------------------------+------------------------------+------------------------------+ + | DESede | ECB | NoPadding | + | *DES3* | | | + +------------------------------+------------------------------+------------------------------+ + | | CBC | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | | PKCS5 Padding | + +------------------------------+------------------------------+------------------------------+ + | AES | ECB | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | CBC | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | | PKCS5 Padding | + +------------------------------+------------------------------+------------------------------+ + | RC4 | *None* | *None* | + +------------------------------+------------------------------+------------------------------+ + | RC2 | CBC | NoPadding | + +------------------------------+------------------------------+------------------------------+ + | | | PKCS5Padding | + +------------------------------+------------------------------+------------------------------+ + + - The SecureRandom argument passed to ``initSign()`` and ``initVerify()`` is ignored, because + NSS does not support specifying an external source of randomness. + +.. rubric:: DSAPrivateKey + :name: DSAPrivateKey_2 + +- ``getX()`` is not supported because NSS does not support extracting data from private keys. + +.. rubric:: KeyFactory + :name: KeyFactory_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_2 + +.. rubric:: Notes + :name: notes_2 + +- + + - DSA + - RSA + + - The following transformations are supported for ``generatePublic()`` and + ``generatePrivate()``: + + + +----------------------------------------------+----------------------------------------------+ + | From | To | + +----------------------------------------------+----------------------------------------------+ + | ``RSAPublicKeySpec`` | ``RSAPublicKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``DSAPublicKeySpec`` | ``DSAPublicKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``X509EncodedKeySpec`` | ``RSAPublicKey`` | + | | ``DSAPublicKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``RSAPrivateCrtKeySpec`` | ``RSAPrivateKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``DSAPrivateKeySpec`` | ``DSAPrivateKey`` | + +----------------------------------------------+----------------------------------------------+ + | ``PKCS8EncodedKeySpec`` | ``RSAPrivateKey`` | + | | ``DSAPrivateKey`` | + +----------------------------------------------+----------------------------------------------+ + + - ``getKeySpec()`` is not supported. This method exports key material in plaintext and is + therefore insecure. Note that a public key's data can be accessed directly from the key. + - ``translateKey()`` simply gets the encoded form of the given key and then tries to import + it by calling ``generatePublic()`` or ``generatePrivate()``. Only ``X509EncodedKeySpec`` is + supported for public keys, and only ``PKCS8EncodedKeySpec`` is supported for private keys. + +.. rubric:: KeyGenerator + :name: KeyGenerator_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_3 + +.. rubric:: Notes + :name: notes_3 + +- + + - AES + - DES + - DESede (*DES3* ) + - RC4 + + - The SecureRandom argument passed to ``init()`` is ignored, because NSS does not support + specifying an external source of randomness. + - None of the key generation algorithms accepts an ``AlgorithmParameterSpec``. + +.. rubric:: KeyPairGenerator + :name: KeyPairGenerator_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_4 + +.. rubric:: Notes + :name: notes_4 + +- + + - DSA + - RSA + + - The SecureRandom argument passed to initialize() is ignored, because NSS does not support + specifying an external source of randomness. + +.. rubric:: Mac + :name: Mac_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_5 + +.. rubric:: Notes + :name: notes_5 + +- + + - HmacSHA1 (*Hmac-SHA1* ) + + - Any secret key type (AES, DES, etc.) can be used as the MAC key, but it must be a JSS key. + That is, it must be an ``instanceof org.mozilla.jss.crypto.SecretKeyFacade``. + - The params passed to ``init()`` are ignored. + +.. rubric:: MessageDigest + :name: MessageDigest_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_6 + +- + + - MD5 + - MD2 + - SHA-1 (*SHA1, SHA* ) + +.. rubric:: RSAPrivateKey + :name: RSAPrivateKey_2 + +.. rubric:: Notes + :name: notes_6 + +- + + - ``getModulus()`` is not supported because NSS does not support extracting data from private + keys. + - ``getPrivateExponent()`` is not supported because NSS does not support extracting data from + private keys. + +.. rubric:: SecretKeyFactory + :name: SecretKeyFactory_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_7 + +.. rubric:: Notes + :name: notes_7 + +- + + - AES + - DES + - DESede (*DES3* ) + - PBAHmacSHA1 + - PBEWithMD5AndDES + - PBEWithSHA1AndDES + - PBEWithSHA1AndDESede (*PBEWithSHA1AndDES3* ) + - PBEWithSHA1And128RC4 + - RC4 + + - ``generateSecret`` supports the following transformations: + + + +----------------------------------------------+----------------------------------------------+ + | KeySpec Class | Key Algorithm | + +----------------------------------------------+----------------------------------------------+ + | PBEKeySpec | *Using the appropriate PBE algorithm:* | + | org.mozilla.jss.crypto.PBEKeyGenParams | DES | + | | DESede | + | | RC4 | + +----------------------------------------------+----------------------------------------------+ + | DESedeKeySpec | DESede | + +----------------------------------------------+----------------------------------------------+ + | DESKeySpec | DES | + +----------------------------------------------+----------------------------------------------+ + | SecretKeySpec | AES | + | | DES | + | | DESede | + | | RC4 | + +----------------------------------------------+----------------------------------------------+ + + - ``getKeySpec`` supports the following transformations: + + + +----------------------------------------------+----------------------------------------------+ + | Key Algorithm | KeySpec Class | + +----------------------------------------------+----------------------------------------------+ + | DESede | DESedeKeySpec | + +----------------------------------------------+----------------------------------------------+ + | DES | DESKeySpec | + +----------------------------------------------+----------------------------------------------+ + | DESede | SecretKeySpec | + | DES | | + | AES | | + | RC4 | | + +----------------------------------------------+----------------------------------------------+ + + - For increased security, some SecretKeys may not be extractable from their PKCS #11 token. + In this case, the key should be wrapped (encrypted with another key), and then the + encrypted key might be extractable from the token. This policy varies across PKCS #11 + tokens. + - ``translateKey`` tries two approaches to copying keys. First, it tries to copy the key + material directly using NSS calls to PKCS #11. If that fails, it calls ``getEncoded()`` on + the source key, and then tries to create a new key on the target token from the encoded + bits. Both of these operations will fail if the source key is not extractable. + - The class ``java.security.spec.PBEKeySpec`` in JDK versions earlier than 1.4 does not + contain the salt and iteration fields, which are necessary for PBE key generation. These + fields were added in JDK 1.4. If you are using a JDK (or JRE) version earlier than 1.4, you + cannot use class ``java.security.spec.PBEKeySpec``. Instead, you can use + ``org.mozilla.jss.crypto.PBEKeyGenParams``. If you are using JDK (or JRE) 1.4 or later, you + can use ``java.security.spec.PBEKeySpec`` or ``org.mozilla.jss.crypto.PBEKeyGenParams``. + +.. rubric:: SecretKey + :name: SecretKey_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_8 + +.. rubric:: Notes + :name: notes_8 + +- + + - AES + - DES + - DESede (*DES3* ) + - HmacSHA1 + - RC2 + - RC4 + + - ``SecretKey`` is implemented by the class ``org.mozilla.jss.crypto.SecretKeyFacade``, which + acts as a wrapper around the JSS class ``SymmetricKey``. Any ``SecretKeys`` handled by JSS + will actually be ``SecretKeyFacades``. This should usually be transparent. + +.. rubric:: SecureRandom + :name: SecureRandom_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_9 + +.. rubric:: Notes + :name: notes_9 + +- + + - pkcs11prng + + - This invokes the NSS internal pseudorandom number generator. + +.. rubric:: Signature + :name: Signature_2 + +.. rubric:: Supported Algorithms + :name: supported_algorithms_10 + +.. rubric:: Notes + :name: notes_10 + +- + + - SHA1withDSA (*DSA, DSS, SHA/DSA, SHA-1/DSA, SHA1/DSA, DSAWithSHA1, SHAwithDSA* ) + - SHA-1/RSA (*SHA1/RSA, SHA1withRSA* ) + - MD5/RSA (*MD5withRSA* ) + - MD2/RSA + + - The ``SecureRandom`` argument passed to ``initSign()`` and ``initVerify()`` is ignored, + because NSS does not support specifying an external source of randomness. diff --git a/security/nss/doc/rst/legacy/jss/mozilla-jss_jca_provider_notes/index.rst b/security/nss/doc/rst/legacy/jss/mozilla-jss_jca_provider_notes/index.rst new file mode 100644 index 0000000000..f8edb0953c --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/mozilla-jss_jca_provider_notes/index.rst @@ -0,0 +1,472 @@ +.. _mozilla_projects_nss_jss_mozilla-jss_jca_provider_notes: + +Mozilla-JSS JCA Provider notes +============================== + +.. _the_mozilla-jss_jca_provider: + +`The Mozilla-JSS JCA Provider <#the_mozilla-jss_jca_provider>`__ +---------------------------------------------------------------- + +.. container:: + + *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org/mozilla.dev.tech.crypto>`__ + +`Overview <#overview>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + This document describes the JCA Provider shipped with JSS. The provider's name is "Mozilla-JSS". + It implements cryptographic operations in native code using the + `NSS <https://www.mozilla.org/projects/security/pki/nss>`__ libraries. + +`Contents <#contents>`__ +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Signed JAR + file <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#signed-jar>`__ + - `Installing the + Provider <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#installing-provider>`__ + - `Specifying the + CryptoToken <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#specifying-token>`__ + - `Supported + Classes <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#supported-classes>`__ + - `What's Not + Supported <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#not-supported>`__ + +.. _signed_jar_file: + +`Signed JAR file <#signed_jar_file>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + JSS implements several JCE (Java Cryptography Extension) algorithms. These algorithms have at + various times been export-controlled by the US government. JRE therefore requires that JAR files + implementing JCE algorithms be digitally signed by an approved organization. The maintainers of + JSS, Sun, Red Hat, and Mozilla, have this approval and signs the official builds of ``jss4.jar``. + At runtime, the JRE automatically verifies this signature whenever a JSS class is loaded that + implements a JCE algorithm. The verification is transparent to the application (unless it fails + and throws an exception). If you are curious, you can verify the signature on the JAR file using + the ``jarsigner`` tool, which is distributed with the JDK. + + If you build JSS yourself from source instead of using binaries downloaded from mozilla.org, your + JAR file will not have a valid signature. This means you will not be able to use the JSS provider + for JCE algorithms. You have two choices. + + #. Use the binary release of JSS from mozilla.org. + #. Apply for your own JCE code-signing certificate following the procedure at `How to Implement a + Provider for the Java\ TM Cryptography + Extension <http://java.sun.com/javase/6/docs/technotes/guides/security/crypto/HowToImplAProvider.html#Step61>`__. + Then you can sign your own JSS JAR file. + +.. _installing_the_provider: + +`Installing the Provider <#installing_the_provider>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + In order to use any part of JSS, including the JCA provider, you must first call + ``CryptoManager.initialize()``. By default, the JCA provider will be installed in the list of + providers maintained by the ``java.security.Security`` class. If you do not wish the provider to + be installed, create a + ```CryptoManager.InitializationValues`` <https://www.mozilla.org/projects/security/pki/jss/javadoc/org/mozilla/jss/CryptoManager.InitializationValues.html>`__ + object, set its ``installJSSProvider`` field to ``false``, and pass the ``InitializationValues`` + object to ``CryptoManager.initialize()``. + +.. _specifying_the_cryptotoken: + +`Specifying the CryptoToken <#specifying_the_cryptotoken>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + All cryptographic operations in JSS and NSS occur on a particular PKCS #11 token, implemented in + software or hardware. There is no clean way to specify this token through the JCA API. By + default, the JSS provider carries out all operations except MessageDigest on the Internal Key + Storage Token, a software token included in JSS/NSS. MessageDigest operations take place by + default on the Internal Crypto Token, another internal software token in JSS/NSS. There is no + good design reason for this difference, but it is necessitated by a quirk in the NSS + implementation. + + In order to use a different token, use ``CryptoManager.setThreadToken()``. This sets the token to + be used by the JSS JCA provider in the current thread. When you call ``getInstance()`` on a JCA + class, the JSS provider checks the current per-thread default token (by calling + ``CryptoManager.getThreadToken()``) and instructs the new object to use that token for + cryptographic operations. The per-thread default token setting is only consulted inside + ``getInstance()``. Once a JCA object has been created it will continue to use the same token, + even if the application later changes the per-thread default token. + + Whenever a new thread is created, its token is initialized to the default, the Internal Key + Storage Token. Thus, the thread token is not inherited from the parent thread. + + The following example shows how you can specify which token is used for various JCA operations: + + .. code:: + + // Lookup PKCS #11 tokens + CryptoManager manager = CryptoManager.getInstance(); + CryptoToken tokenA = manager.getTokenByName("TokenA"); + CryptoToken tokenB = manager.getTokenByName("TokenB"); + + // Create an RSA KeyPairGenerator using TokenA + manager.setThreadToken(tokenA); + KeyPairGenerator rsaKpg = KeyPairGenerator.getInstance("Mozilla-JSS", "RSA"); + + // Create a DSA KeyPairGenerator using TokenB + manager.setThreadToken(tokenB); + KeyPairGenerator dsaKpg = KeyPairGenerator.getInstance("Mozilla-JSS", "DSA"); + + // Generate an RSA KeyPair. This will happen on TokenA because TokenA + // was the per-thread default token when rsaKpg was created. + rsaKpg.initialize(1024); + KeyPair rsaPair = rsaKpg.generateKeyPair(); + + // Generate a DSA KeyPair. This will happen on TokenB because TokenB + // was the per-thread default token when dsaKpg was created. + dsaKpg.initialize(1024); + KeyPair dsaPair = dsaKpg.generateKeyPair(); + +.. _supported_classes: + +`Supported Classes <#supported_classes>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - `Cipher <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#Cipher>`__ + - `DSAPrivateKey <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#DSAPrivateKey>`__ + - DSAPublicKey + - `KeyFactory <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#KeyFactory>`__ + - `KeyGenerator <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#KeyGenerator>`__ + - `KeyPairGenerator <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#KeyPairGenerator>`__ + - `Mac <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#Mac>`__ + - `MessageDigest <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#MessageDigest>`__ + - `RSAPrivateKey <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#RSAPrivateKey>`__ + - RSAPublicKey + - `SecretKeyFactory <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#SecretKeyFactory>`__ + - `SecretKey <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#SecretKey>`__ + - `SecureRandom <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#SecureRandom>`__ + - `Signature <https://www.mozilla.org/projects/security/pki/jss/provider_notes.html#Signature>`__ + +`Cipher <#cipher>`__ +~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms + + .. rubric:: Notes + :name: notes + + - AES + - DES + - DESede (*DES3*) + - RC2 + - RC4 + - RSA + + - The following modes and padding schemes are supported: + + +--------------------------------+--------------------------------+--------------------------------+ + | Algorithm | Mode | Padding | + +--------------------------------+--------------------------------+--------------------------------+ + | DES | ECB | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | CBC | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | | PKCS5 Padding | + +--------------------------------+--------------------------------+--------------------------------+ + | DESede | ECB | NoPadding | + | *DES3* | | | + +--------------------------------+--------------------------------+--------------------------------+ + | | CBC | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | | PKCS5 Padding | + +--------------------------------+--------------------------------+--------------------------------+ + | AES | ECB | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | CBC | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | | PKCS5 Padding | + +--------------------------------+--------------------------------+--------------------------------+ + | RC4 | *None* | *None* | + +--------------------------------+--------------------------------+--------------------------------+ + | RC2 | CBC | NoPadding | + +--------------------------------+--------------------------------+--------------------------------+ + | | | PKCS5Padding | + +--------------------------------+--------------------------------+--------------------------------+ + + - The SecureRandom argument passed to ``initSign()`` and ``initVerify()`` is ignored, because + NSS does not support specifying an external source of randomness. + +`DSAPrivateKey <#dsaprivatekey>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + - ``getX()`` is not supported because NSS does not support extracting data from private keys. + +`KeyFactory <#keyfactory>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_2 + + .. rubric:: Notes + :name: notes_2 + + - DSA + - RSA + - The following transformations are supported for ``generatePublic()`` and + ``generatePrivate()``: + + +-------------------------------------------------+-------------------------------------------------+ + | From | To | + +-------------------------------------------------+-------------------------------------------------+ + | ``RSAPublicKeySpec`` | ``RSAPublicKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``DSAPublicKeySpec`` | ``DSAPublicKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``X509EncodedKeySpec`` | ``RSAPublicKey`` | + | | ``DSAPublicKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``RSAPrivateCrtKeySpec`` | ``RSAPrivateKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``DSAPrivateKeySpec`` | ``DSAPrivateKey`` | + +-------------------------------------------------+-------------------------------------------------+ + | ``PKCS8EncodedKeySpec`` | ``RSAPrivateKey`` | + | | ``DSAPrivateKey`` | + +-------------------------------------------------+-------------------------------------------------+ + + - ``getKeySpec()`` is not supported. This method exports key material in plaintext and is + therefore insecure. Note that a public key's data can be accessed directly from the key. + - ``translateKey()`` simply gets the encoded form of the given key and then tries to import it + by calling ``generatePublic()`` or ``generatePrivate()``. Only ``X509EncodedKeySpec`` is + supported for public keys, and only ``PKCS8EncodedKeySpec`` is supported for private keys. + +`KeyGenerator <#keygenerator>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_3 + + .. rubric:: Notes + :name: notes_3 + + - AES + - DES + - DESede (*DES3*) + - RC4 + - The SecureRandom argument passed to ``init()`` is ignored, because NSS does not support + specifying an external source of randomness. + - None of the key generation algorithms accepts an ``AlgorithmParameterSpec``. + +`KeyPairGenerator <#keypairgenerator>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_4 + + .. rubric:: Notes + :name: notes_4 + + - DSA + - RSA + + - The SecureRandom argument passed to initialize() is ignored, because NSS does not support + specifying an external source of randomness. + +`Mac <#mac>`__ +~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_5 + + .. rubric:: Notes + :name: notes_5 + + - HmacSHA1 (*Hmac-SHA1*) + + - Any secret key type (AES, DES, etc.) can be used as the MAC key, but it must be a JSS key. + That is, it must be an ``instanceof org.mozilla.jss.crypto.SecretKeyFacade``. + - The params passed to ``init()`` are ignored. + +`MessageDigest <#messagedigest>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_6 + + - MD5 + - MD2 + - SHA-1 (*SHA1, SHA*) + +`RSAPrivateKey <#rsaprivatekey>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Notes + :name: notes_6 + + - ``getModulus()`` is not supported because NSS does not support extracting data from private + keys. + - ``getPrivateExponent()`` is not supported because NSS does not support extracting data from + private keys. + +`SecretKeyFactory <#secretkeyfactory>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_7 + + .. rubric:: Notes + :name: notes_7 + + - AES + - DES + - DESede (*DES3*) + - PBAHmacSHA1 + - PBEWithMD5AndDES + - PBEWithSHA1AndDES + - PBEWithSHA1AndDESede (*PBEWithSHA1AndDES3*) + - PBEWithSHA1And128RC4 + - RC4 + + - ``generateSecret`` supports the following transformations: + + +-------------------------------------------------+-------------------------------------------------+ + | KeySpec Class | Key Algorithm | + +-------------------------------------------------+-------------------------------------------------+ + | PBEKeySpec | *Using the appropriate PBE algorithm:* | + | org.mozilla.jss.crypto.PBEKeyGenParams | DES | + | | DESede | + | | RC4 | + +-------------------------------------------------+-------------------------------------------------+ + | DESedeKeySpec | DESede | + +-------------------------------------------------+-------------------------------------------------+ + | DESKeySpec | DES | + +-------------------------------------------------+-------------------------------------------------+ + | SecretKeySpec | AES | + | | DES | + | | DESede | + | | RC4 | + +-------------------------------------------------+-------------------------------------------------+ + + - ``getKeySpec`` supports the following transformations: + + +-------------------------------------------------+-------------------------------------------------+ + | Key Algorithm | KeySpec Class | + +-------------------------------------------------+-------------------------------------------------+ + | DESede | DESedeKeySpec | + +-------------------------------------------------+-------------------------------------------------+ + | DES | DESKeySpec | + +-------------------------------------------------+-------------------------------------------------+ + | DESede | SecretKeySpec | + | DES | | + | AES | | + | RC4 | | + +-------------------------------------------------+-------------------------------------------------+ + + - For increased security, some SecretKeys may not be extractable from their PKCS #11 token. In + this case, the key should be wrapped (encrypted with another key), and then the encrypted key + might be extractable from the token. This policy varies across PKCS #11 tokens. + - ``translateKey`` tries two approaches to copying keys. First, it tries to copy the key + material directly using NSS calls to PKCS #11. If that fails, it calls ``getEncoded()`` on the + source key, and then tries to create a new key on the target token from the encoded bits. Both + of these operations will fail if the source key is not extractable. + - The class ``java.security.spec.PBEKeySpec`` in JDK versions earlier than 1.4 does not contain + the salt and iteration fields, which are necessary for PBE key generation. These fields were + added in JDK 1.4. If you are using a JDK (or JRE) version earlier than 1.4, you cannot use + class ``java.security.spec.PBEKeySpec``. Instead, you can use + ``org.mozilla.jss.crypto.PBEKeyGenParams``. If you are using JDK (or JRE) 1.4 or later, you + can use ``java.security.spec.PBEKeySpec`` or ``org.mozilla.jss.crypto.PBEKeyGenParams``. + +`SecretKey <#secretkey>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_8 + + .. rubric:: Notes + :name: notes_8 + + - AES + - DES + - DESede (*DES3*) + - HmacSHA1 + - RC2 + - RC4 + + - ``SecretKey`` is implemented by the class ``org.mozilla.jss.crypto.SecretKeyFacade``, which + acts as a wrapper around the JSS class ``SymmetricKey``. Any ``SecretKeys`` handled by JSS + will actually be ``SecretKeyFacades``. This should usually be transparent. + +`SecureRandom <#securerandom>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_9 + + .. rubric:: Notes + :name: notes_9 + + - pkcs11prng + + - This invokes the NSS internal pseudorandom number generator. + +`Signature <#signature>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + .. rubric:: Supported Algorithms + :name: supported_algorithms_10 + + .. rubric:: Notes + :name: notes_10 + + - SHA1withDSA (*DSA, DSS, SHA/DSA, SHA-1/DSA, SHA1/DSA, DSAWithSHA1, SHAwithDSA*) + - SHA-1/RSA (*SHA1/RSA, SHA1withRSA*) + - MD5/RSA (*MD5withRSA*) + - MD2/RSA + + - The SecureRandom argument passed to ``initSign()`` and ``initVerify()`` is ignored, because + NSS does not support specifying an external source of randomness. + +.. _what's_not_supported: + +`What's Not Supported <#what's_not_supported>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + The following classes don't work very well: + + - **KeyStore:** There are many serious problems mapping the JCA keystore interface onto NSS's + model of PKCS #11 modules. The current implementation is almost useless. Since these problems + lie deep in the NSS design and implementation, there is no clear timeframe for fixing them. + Meanwhile, the ``org.mozilla.jss.crypto.CryptoStore`` class can be used for some of this + functionality.
\ No newline at end of file diff --git a/security/nss/doc/rst/legacy/jss/using_jss/index.rst b/security/nss/doc/rst/legacy/jss/using_jss/index.rst new file mode 100644 index 0000000000..3a5f19f9c7 --- /dev/null +++ b/security/nss/doc/rst/legacy/jss/using_jss/index.rst @@ -0,0 +1,152 @@ +.. _mozilla_projects_nss_jss_using_jss: + +Using JSS +========= + +.. _using_jss: + +`Using JSS <#using_jss>`__ +-------------------------- + +.. container:: + + *Newsgroup:*\ `mozilla.dev.tech.crypto <news://news.mozilla.org:119/mozilla.dev.tech.crypto>`__ + + If you have already `built + JSS <https://developer.mozilla.org/en-US/docs/JSS/Build_instructions_for_JSS_4.3.x>`__, or if you + are planning to use a binary release of JSS, here's how to get JSS working with your code. + + | `Gather Components <#components>`__ + | `Setup your runtime environment <#runtime>`__ + | `Initialize JSS in your application <#init>`__ + +.. _gather_components: + +`Gather components <#gather_components>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + #. You need the JSS classes and the NSPR, NSS, and JSS shared libraries. + + #. **NSPR and NSS Shared Libraries** + + JSS uses the NSPR and NSS libraries for I/O and crypto. JSS version 3.0 linked statically with + NSS, so it only required NSPR. JSS versions 3.1 and later link dynamically with NSS, so they + also require the NSS shared libraries. + + The exact library names vary according to the convention for each platform. For example, the + NSPR library is called ``nspr4.dll`` or ``libnspr4.dll`` on Windows and ``libnspr4.so`` on + Solaris. The following table gives the core names of the libraries, omitting the + platform-specific prefix and suffix. + + +-------------------+-------------------------------------+--------------------------------------+ + | JSS Dependencies | | | + +-------------------+-------------------------------------+--------------------------------------+ + | Core Library Name | Description | Binary Release Location | + +-------------------+-------------------------------------+--------------------------------------+ + | nspr4 | NSPR OS abstraction layer | `htt | + | | | p://ftp.mozilla.org/pub/mozilla.org/ | + | | | nspr/releases <http://ftp.mozilla.or | + | | | g/pub/mozilla.org/nspr/releases/>`__ | + +-------------------+-------------------------------------+--------------------------------------+ + | plc4 | | NSPR standard C library replacement | + | | | functions | + +-------------------+-------------------------------------+--------------------------------------+ + | plds4 | | NSPR data structure types | + +-------------------+-------------------------------------+--------------------------------------+ + | nss3 | NSS crypto, PKCS #11, and utilities | `http://ftp.mozilla. | + | | | org/pub/mozilla.org/security/nss/rel | + | | | eases <http://ftp.mozilla.org/pub/mo | + | | | zilla.org/security/nss/releases/>`__ | + +-------------------+-------------------------------------+--------------------------------------+ + | ssl3 | | NSS SSL library | + +-------------------+-------------------------------------+--------------------------------------+ + | smime3 | | NSS S/MIME functions and types | + +-------------------+-------------------------------------+--------------------------------------+ + | nssckbi | | PKCS #11 module containing built-in | + | | | root CA certificates. Optional. | + +-------------------+-------------------------------------+--------------------------------------+ + | freebl_\* | | Processor-specific optimized | + | | | big-number arithmetic library. Not | + | | | present on all platforms. | + | | | :ref:`mozilla_projects_nss_introd | + | | | uction_to_network_security_services` | + +-------------------+-------------------------------------+--------------------------------------+ + | fort | | FORTEZZA support. Optional | + +-------------------+-------------------------------------+--------------------------------------+ + | swft | | PKCS #11 module implementing | + | | | FORTEZZA in software. Optional. | + +-------------------+-------------------------------------+--------------------------------------+ + + If you built JSS from source, you have these libraries in the ``mozilla/dist/<platform>/lib`` + directory of your build tree. If you are downloading binaries, get them from the binary + release locations in the above table. You need to select the right version of the components, + based on the version of JSS you are using. Generally, it is safe to use a later version of a + component than what JSS was tested with. For example, although JSS 4.2 was tested with NSS + 3.11. + + ================== ========= ============== + Component Versions + JSS Version Component Tested Version + JSS 4.2 NSPR 4.6.4 + \ NSS 3.11.4 + JSS 3.4 NSPR 4.2.2 + \ NSS 3.7.3 + JSS 3.3 NSPR 4.2.2 + \ NSS 3.6.1 or 3.7 + JSS 3.2 NSPR 4.2 or 4.1.2 + \ NSS 3.4.2 + JSS 3.1.1 NSPR 4.1.2 + \ NSS 3.3.1 + JSS 3.1 NSPR 4.1.2 + \ NSS 3.3 + JSS 3.0 NSPR 3.5.1 + ================== ========= ============== + + #. **JSS Shared Library** + + The JSS shared library is ``jss4.dll`` (Windows) or ``libjss4.so`` (Unix). If you built JSS + from source, it is in ``mozilla/dist/<platform>/lib``. If you are downloading binaries, get it + from http://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/. + + #. **JSS classes** + + If you built JSS from source, the compiled JSS classes are in ``mozilla/dist/classes[_dbg]``. + You can put this directory in your classpath to run applications locally; or, you can package + the class files into a JAR file for easier distribution: + + .. code:: + + cd mozilla/dist/classes[_dbg] + zip -r ../jss42.jar . + + If you are downloading binaries, get jss42.jar + from http://ftp.mozilla.org/pub/mozilla.org/security/jss/releases/. + +.. _setup_your_runtime_environment: + +`Setup your runtime environment <#setup_your_runtime_environment>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + You need to set some environment variables before building and running Java applications with + JSS. + + ``CLASSPATH`` + Include the path containing the JSS classes you built, or the path to ``jss42.jar``. (The path + to ``jss34.jar`` ends with the string "/jss42.jar". It is not just the directory that contains + ``jss42.jar``.) + ``LD_LIBRARY_PATH`` (Unix) / ``PATH`` (Windows) + Include the path to the NSPR, NSS, and JSS shared libraries. + +.. _initialize_jss_in_your_application: + +`Initialize JSS in your application <#initialize_jss_in_your_application>`__ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: + + Before calling any JSS methods, you must initialize JSS by calling one of the + ``CryptoManager.initialize`` methods. See the `javadoc <javadoc>`__ for more details.
\ No newline at end of file |