JSS Frequently Asked Questions

Newsgroup: mozilla.dev.tech.crypto

Content:

• What versions of JDK and JCE do you suggest?
• Does JSS have 64 bit support?
• Is JSS FIPS Compliant?
• Is there any sample code and documentation?
• If I don't call setCipherPolicy, is the DOMESTIC policy used by default?
• My SSL connection is hanging on Windows?
• How can I tell which SSL/TLS ciphers JSS supports?
• How can I debug my SSL connection?
• Can you explain JSS SSL certificate approval callbacks?
• Can I have multiple JSS instances reading separate db's?
• Once JSS initialized, I can't get anymore instances with CertificateFactory.getInstance(X.509)?
• Is it possible to sign data in Java with JSS?
• How do I convert org.mozilla.jss.crypto.X509Certificate to org.mozilla.jss.pkix.cert.Certificate?
• How do I convert org.mozilla.jss.pkix.cert to org.mozilla.jss.crypto.X509Certificate?
• Is it possible to use JSS to access cipher functionality from pkcs11 modules?
• Can you explain token names and keys with regards to JSS?
• JSS 3.2 has JCA support. When will JSS have JSSE support?

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. 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.

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 document describes how to set up your environment to run JSS. The only other documentation is the Javadoc.

  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
  org/mozilla/jss/tests/KeyFactoryTest.java
  org/mozilla/jss/tests/DigestTest.java
  org/mozilla/jss/tests/JCASigTest.java
  org/mozilla/jss/tests/KeyWrapping.java
  org/mozilla/jss/tests/ListCerts.java
  org/mozilla/jss/tests/PK10Gen.java
  org/mozilla/jss/tests/SDR.java
  org/mozilla/jss/tests/SelfTest.java
  org/mozilla/jss/tests/SetupDBs.java
  org/mozilla/jss/tests/SigTest.java
  org/mozilla/jss/tests/SymKeyGen.java
  org/mozilla/jss/tests/TestKeyGen.java
  org/mozilla/jss/tests/SSLClientAuth.java
  org/mozilla/jss/tests/ListCACerts.java
  org/mozilla/jss/tests/KeyStoreTest.java
  org/mozilla/jss/tests/VerifyCert.java

  SSL examples:

  org/mozilla/jss/tests/SSLClientAuth.java
  org/mozilla/jss/ssl/SSLClient.java
  org/mozilla/jss/ssl/SSLServer.java
  org/mozilla/jss/ssl/SSLTest.java

  Other test code that may prove useful:

  org/mozilla/jss/asn1/INTEGER.java
  org/mozilla/jss/asn1/SEQUENCE.java
  org/mozilla/jss/asn1/SET.java
  org/mozilla/jss/pkcs10/CertificationRequest.java
  org/mozilla/jss/pkcs12/PFX.java
  org/mozilla/jss/pkix/cert/Certificate.java
  org/mozilla/jss/pkix/cmmf/CertRepContent.java
  org/mozilla/jss/pkix/crmf/CertReqMsg.java
  org/mozilla/jss/pkix/crmf/CertTemplate.java
  org/mozilla/jss/pkix/primitive/Name.java
  org/mozilla/jss/provider/javax/crypto/JSSSecretKeyFactorySpi.java
  org/mozilla/jss/util/UTF8Converter.java
  org/mozilla/jss/util/Base64InputStream.java
  jss/samples/PQGGen.java
  jss/samples/pkcs12.java

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 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 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:
  1. SSL_AuthCertificateHook sets a callback to authenticate the peer's certificate. It is called instead of NSS's routine for authenticating certificates.
  2. SSL_BadCertHook sets a callback that is called when NSS's routine fails to authenticate the certificate.
  3. SSL_GetClientAuthDataHook sets a callback to return the local certificate for SSL client auth.

  JSS's two callbacks are:

  1. 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.
  2. 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.

How do I convert org.mozilla.jss.crypto.X509Certificate to org.mozilla.jss.pkix.cert.Certificate?

• 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()

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.

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.

JSS 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.