(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:

  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](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.
:::
