JSS 3.1.1

org.mozilla.jss
Class CryptoManager

java.lang.Object
  |
  +--org.mozilla.jss.CryptoManager
All Implemented Interfaces:
TokenSupplier

public final class CryptoManager
extends java.lang.Object
implements TokenSupplier

This class is the starting poing for the crypto package. Use it to initialize the subsystem and to lookup certs, keys, and tokens. Initialization is done with static methods, and must be done before an instance can be created. All other operations are done with instance methods.


Inner Class Summary
static class CryptoManager.InitializationValues
          The various options that can be used to initialize CryptoManager.
static class CryptoManager.InvalidLengthException
           
static class CryptoManager.NicknameConflictException
           
static class CryptoManager.NotInitializedException
           
static class CryptoManager.UserCertConflictException
           
 
Field Summary
static int DOMESTIC_POLICY
           
static int EXPORT_POLICY
           
static int FRANCE_POLICY
           
private static CryptoManager instance
          The singleton instance, and a static initializer to create it.
private  CryptoToken internalCryptoToken
          The internal cryptographic services token.
private  CryptoToken internalKeyStorageToken
          The internal key storage token.
static java.lang.String JAR_DBM_VERSION
           
static java.lang.String JAR_JDK_VERSION
           
static java.lang.String JAR_JSS_VERSION
           
static java.lang.String JAR_NSPR_VERSION
           
static java.lang.String JAR_NSS_VERSION
           
private static boolean mNativeLibrariesLoaded
           
private  java.util.Vector moduleVector
          The list of modules.
static int NULL_POLICY
           
private  PasswordCallback passwordCallback
           
private static int TYPE_CRL
           
private static int TYPE_KRL
           
 
Constructor Summary
protected CryptoManager()
          Constructor, for internal use only.
 
Method Summary
 X509Certificate[] buildCertificateChain(X509Certificate leaf)
          Given a certificate, constructs its certificate chain.
(package private)  X509Certificate[] buildCertificateChainNative(PK11Cert leaf)
           
 JSSSecureRandom createPseudoRandomNumberGenerator()
          Retrieves a FIPS-140-1 validated random number generator.
private static boolean enableFIPS(boolean fips)
          Enables or disables FIPS-140-1 compliant mode.
 byte[] exportCertsToPKCS7(X509Certificate[] certs)
          Exports one or more certificates into a PKCS #7 certificate container.
 X509Certificate findCertByIssuerAndSerialNumber(byte[] derIssuer, INTEGER serialNumber)
          Looks up a certificate by issuer and serial number.
private  X509Certificate findCertByIssuerAndSerialNumberNative(byte[] derIssuer, byte[] serialNumber)
           
 X509Certificate findCertByNickname(java.lang.String nickname)
          Looks up a certificate given its nickname.
protected  X509Certificate findCertByNicknameNative(java.lang.String nickname)
           
 X509Certificate[] findCertsByNickname(java.lang.String nickname)
          Returns all certificates with the given nickname.
protected  X509Certificate[] findCertsByNicknameNative(java.lang.String nickname)
           
 PrivateKey findPrivKeyByCert(X509Certificate cert)
          Looks up the PrivateKey matching the given certificate.
protected  PrivateKey findPrivKeyByCertNative(X509Certificate cert)
           
 boolean FIPSEnabled()
          Determines whether FIPS-140-1 compliance is active.
 java.util.Enumeration getAllTokens()
          Retrieves all tokens.
 X509Certificate[] getCACerts()
          Retrieves all CA certificates in the trust database.
 java.util.Enumeration getExternalTokens()
          Retrieves all tokens except those built into NSS.
static CryptoManager getInstance()
          Retrieve the single instance of CryptoManager.
 CryptoToken getInternalCryptoToken()
          Retrieves the internal cryptographic services token.
 CryptoToken getInternalKeyStorageToken()
          Retrieves the internal key storage token.
 java.util.Enumeration getModules()
          Retrieves all installed cryptographic modules.
 PasswordCallback getPasswordCallback()
          Returns the currently registered password callback.
 X509Certificate[] getPermCerts()
          Retrieves all certificates in the trust database.
 JSSSecureRandom getSecureRNG()
          Retrieves a FIPS-140-1 validated random number generator.
 CryptoToken getTokenByName(java.lang.String name)
          Looks up the CryptoToken with the given name.
 java.util.Enumeration getTokensSupportingAlgorithm(Algorithm alg)
          Retrieves all tokens that support the given algorithm.
 X509Certificate importCACertPackage(byte[] certPackage)
          Imports a chain of certificates, none of which is a user certificate.
 X509Certificate importCertPackage(byte[] certPackage, java.lang.String nickname)
          Imports a chain of certificates.
private  X509Certificate importCertPackageNative(byte[] certPackage, java.lang.String nickname, boolean noUser, boolean leafIsCA)
           
 InternalCertificate importCertToPerm(X509Certificate cert, java.lang.String nickname)
          Imports a single certificate into the permanent certificate database.
private  InternalCertificate importCertToPermNative(X509Certificate cert, java.lang.String nickname)
           
 void importCRL(byte[] crl, java.lang.String url)
          Imports a CRL, and stores it into the cert7.db Validate CRL then import it to the dbase.
private  void importCRLNative(byte[] crl, java.lang.String url, int rl_type)
          Imports a CRL, and stores it into the cert7.db
 X509Certificate importUserCACertPackage(byte[] certPackage, java.lang.String nickname)
          Imports a chain of certificates.
static void initialize(CryptoManager.InitializationValues values)
          Initialize the security subsystem.
static void initialize(java.lang.String configDir)
          Initialize the security subsystem.
private static void initializeAllNative(java.lang.String configDir, java.lang.String certPrefix, java.lang.String keyPrefix, java.lang.String secmodName, boolean readOnly, java.lang.String manufacturerID, java.lang.String libraryDescription, java.lang.String internalTokenDescription, java.lang.String internalKeyStorageTokenDescription, java.lang.String internalSlotDescription, java.lang.String internalKeyStorageSlotDescription, java.lang.String fipsSlotDescription, java.lang.String fipsKeyStorageSlotDescription, boolean ocspCheckingEnabled, java.lang.String ocspResponderURL, java.lang.String ocspResponderCertNickname)
           
(package private) static void loadNativeLibraries()
          Loads the JSS dynamic library if necessary.
private  void putModulesInVector(java.util.Vector vector)
          Native code to traverse all PKCS #11 modules, wrap each one in a PK11Module, and insert each PK11Module into the given vector.
private  void reloadModules()
          Re-creates the Vector of modules that is stored by CryptoManager.
private  void setNativePasswordCallback(PasswordCallback cb)
           
 void setPasswordCallback(PasswordCallback pwcb)
          This function sets the global password callback.
 
Methods inherited from class java.lang.Object
, clone, equals, finalize, getClass, hashCode, notify, notifyAll, registerNatives, toString, wait, wait, wait
 

Field Detail

moduleVector

private java.util.Vector moduleVector
The list of modules. This should be initialized by the constructor and updated whenever 1) a new module is added, 2) a module is deleted, or 3) FIPS mode is switched.

internalCryptoToken

private CryptoToken internalCryptoToken
The internal cryptographic services token.

internalKeyStorageToken

private CryptoToken internalKeyStorageToken
The internal key storage token.

instance

private static CryptoManager instance
The singleton instance, and a static initializer to create it.

passwordCallback

private PasswordCallback passwordCallback

TYPE_KRL

private static int TYPE_KRL

TYPE_CRL

private static int TYPE_CRL

NULL_POLICY

public static final int NULL_POLICY

DOMESTIC_POLICY

public static final int DOMESTIC_POLICY

EXPORT_POLICY

public static final int EXPORT_POLICY

FRANCE_POLICY

public static final int FRANCE_POLICY

JAR_JSS_VERSION

public static final java.lang.String JAR_JSS_VERSION

JAR_JDK_VERSION

public static final java.lang.String JAR_JDK_VERSION

JAR_NSS_VERSION

public static final java.lang.String JAR_NSS_VERSION

JAR_DBM_VERSION

public static final java.lang.String JAR_DBM_VERSION

JAR_NSPR_VERSION

public static final java.lang.String JAR_NSPR_VERSION

mNativeLibrariesLoaded

private static boolean mNativeLibrariesLoaded
Constructor Detail

CryptoManager

protected CryptoManager()
Constructor, for internal use only.
Method Detail

getInternalCryptoToken

public CryptoToken getInternalCryptoToken()
Retrieves the internal cryptographic services token. This is the token built into NSS that performs bulk cryptographic operations.

In FIPS mode, the internal cryptographic services token is the same as the internal key storage token.

Specified by:
getInternalCryptoToken in interface TokenSupplier
Returns:
The internal cryptographic services token.

getInternalKeyStorageToken

public CryptoToken getInternalKeyStorageToken()
Retrieves the internal key storage token. This is the token provided by NSS to store private keys. The keys stored in this token are stored in an encrypted key database.

In FIPS mode, the internal key storage token is the same as the internal cryptographic services token.

Returns:
The internal key storage token.

getTokenByName

public CryptoToken getTokenByName(java.lang.String name)
                           throws NoSuchTokenException
Looks up the CryptoToken with the given name. Searches all loaded cryptographic modules for the token.
Parameters:
name - The name of the token.
Throws:
org.mozilla.jss.crypto.NoSuchTokenException - If no token is found with the given name.

getTokensSupportingAlgorithm

public java.util.Enumeration getTokensSupportingAlgorithm(Algorithm alg)
Retrieves all tokens that support the given algorithm.

getAllTokens

public java.util.Enumeration getAllTokens()
Retrieves all tokens. This is an enumeration of all tokens on all modules.
Returns:
All tokens accessible from JSS. Each item of the enumeration is a CryptoToken
See Also:
CryptoToken

getExternalTokens

public java.util.Enumeration getExternalTokens()
Retrieves all tokens except those built into NSS. This excludes the internal token and the internal key storage token (which are one and the same in FIPS mode).
Returns:
All tokens accessible from JSS, except for the built-in internal tokens.

getModules

public java.util.Enumeration getModules()
Retrieves all installed cryptographic modules.
Returns:
An enumeration of all installed PKCS #11 modules. Each item in the enumeration is a PK11Module.
See Also:
PK11Module

reloadModules

private void reloadModules()
Re-creates the Vector of modules that is stored by CryptoManager. This entails going into native code to enumerate all modules, wrap each one in a PK11Module, and storing the PK11Module in the vector.

putModulesInVector

private void putModulesInVector(java.util.Vector vector)
Native code to traverse all PKCS #11 modules, wrap each one in a PK11Module, and insert each PK11Module into the given vector.

getInstance

public static CryptoManager getInstance()
                                 throws CryptoManager.NotInitializedException
Retrieve the single instance of CryptoManager. This cannot be called before initialization.
Throws:
CryptoManager.NotInitializedException - If initialize(InitializationValues has not yet been called.
See Also:
initialize(CryptoManager.InitializationValues)

enableFIPS

private static boolean enableFIPS(boolean fips)
                           throws java.security.GeneralSecurityException
Enables or disables FIPS-140-1 compliant mode. If this returns true, you must reloadModules(). This should only be called once in a program, at the beginning, because it invalidates tokens and modules.
Parameters:
fips - true to turn FIPS compliant mode on, false to turn it off.

FIPSEnabled

public boolean FIPSEnabled()
Determines whether FIPS-140-1 compliance is active.
Returns:
true if the security library is in FIPS-140-1 compliant mode.

setPasswordCallback

public void setPasswordCallback(PasswordCallback pwcb)
This function sets the global password callback. It is not thread-safe to change this. A better strategy than using callbacks is to explicitly login to the tokens you need to use. Password callbacks are then only used as a last resort.

The callback may be NULL, in which case password callbacks will fail gracefully.


setNativePasswordCallback

private void setNativePasswordCallback(PasswordCallback cb)

getPasswordCallback

public PasswordCallback getPasswordCallback()
Returns the currently registered password callback.

initialize

public static void initialize(java.lang.String configDir)
                       throws KeyDatabaseException,
                              CertDatabaseException,
                              AlreadyInitializedException,
                              java.security.GeneralSecurityException
Initialize the security subsystem. Opens the databases, loads all PKCS #11 modules, initializes the internal random number generator. The initialize methods that take arguments should be called only once, otherwise they will throw an exception. It is OK to call them after calling initialize().
Parameters:
configDir - The directory containing the security databases.
Throws:
org.mozilla.jss.util.KeyDatabaseException - Unable to open the key database, or it was currupted.
org.mozilla.jss.util.CertDatabaseException - Unable to open the certificate database, or it was currupted.

initialize

public static void initialize(CryptoManager.InitializationValues values)
                       throws KeyDatabaseException,
                              CertDatabaseException,
                              AlreadyInitializedException,
                              java.security.GeneralSecurityException
Initialize the security subsystem. Opens the databases, loads all PKCS #11 modules, initializes the internal random number generator. The initialize methods that take arguments should be called only once, otherwise they will throw an exception. It is OK to call them after calling initialize().
Parameters:
values - The options with which to initialize CryptoManager.
Throws:
org.mozilla.jss.util.KeyDatabaseException - Unable to open the key database, or it was currupted.
org.mozilla.jss.util.CertDatabaseException - Unable to open the certificate database, or it was currupted.

initializeAllNative

private static void initializeAllNative(java.lang.String configDir,
                                        java.lang.String certPrefix,
                                        java.lang.String keyPrefix,
                                        java.lang.String secmodName,
                                        boolean readOnly,
                                        java.lang.String manufacturerID,
                                        java.lang.String libraryDescription,
                                        java.lang.String internalTokenDescription,
                                        java.lang.String internalKeyStorageTokenDescription,
                                        java.lang.String internalSlotDescription,
                                        java.lang.String internalKeyStorageSlotDescription,
                                        java.lang.String fipsSlotDescription,
                                        java.lang.String fipsKeyStorageSlotDescription,
                                        boolean ocspCheckingEnabled,
                                        java.lang.String ocspResponderURL,
                                        java.lang.String ocspResponderCertNickname)
                                 throws KeyDatabaseException,
                                        CertDatabaseException,
                                        AlreadyInitializedException

getCACerts

public X509Certificate[] getCACerts()
Retrieves all CA certificates in the trust database. This is a fairly expensive operation in that it involves traversing the entire certificate database.
Returns:
An array of all CA certificates stored permanently in the trust database.

getPermCerts

public X509Certificate[] getPermCerts()
Retrieves all certificates in the trust database. This is a fairly expensive operation in that it involves traversing the entire certificate database.
Returns:
An array of all certificates stored permanently in the trust database.

importCertPackage

public X509Certificate importCertPackage(byte[] certPackage,
                                         java.lang.String nickname)
                                  throws java.security.cert.CertificateEncodingException,
                                         CryptoManager.NicknameConflictException,
                                         CryptoManager.UserCertConflictException,
                                         NoSuchItemOnTokenException,
                                         TokenException
Imports a chain of certificates. The leaf certificate may be a a user certificate, that is, a certificate that belongs to the current user and whose private key is available for use. If the leaf certificate is a user certificate, it is stored on the token that contains the corresponding private key, and is assigned the given nickname.
Parameters:
certPackage - An encoded certificate or certificate chain. Acceptable encodings are binary PKCS #7 SignedData objects and DER-encoded certificates, which may or may not be wrapped in a Base-64 encoding package surrounded by "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----".
nickname - The nickname for the user certificate. It must be unique. It is ignored if there is no user certificate.
Returns:
The leaf certificate from the chain.
Throws:
java.security.cert.CertificateEncodingException - If the package encoding was not recognized.
CertificateNicknameConflictException - If the leaf certificate is a user certificate, and another certificate already has the given nickname.
CryptoManager.UserCertConflictException - If the leaf certificate is a user certificate, but it has already been imported.
NoSuchItemOnTokenException - If the leaf certificate is a user certificate, but the matching private key cannot be found.
TokenException - If an error occurs importing a leaf certificate into a token.

importUserCACertPackage

public X509Certificate importUserCACertPackage(byte[] certPackage,
                                               java.lang.String nickname)
                                        throws java.security.cert.CertificateEncodingException,
                                               CryptoManager.NicknameConflictException,
                                               CryptoManager.UserCertConflictException,
                                               NoSuchItemOnTokenException,
                                               TokenException
Imports a chain of certificates. The leaf of the chain is a CA certificate AND a user certificate (this would only be called by a CA installing its own certificate).
Parameters:
certPackage - An encoded certificate or certificate chain. Acceptable encodings are binary PKCS #7 SignedData objects and DER-encoded certificates, which may or may not be wrapped in a Base-64 encoding package surrounded by "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----".
nickname - The nickname for the user certificate. It must be unique.
Returns:
The leaf certificate from the chain.
Throws:
java.security.cert.CertificateEncodingException - If the package encoding was not recognized.
CertificateNicknameConflictException - If the leaf certificate another certificate already has the given nickname.
CryptoManager.UserCertConflictException - If the leaf certificate has already been imported.
NoSuchItemOnTokenException - If the the private key matching the leaf certificate cannot be found.
TokenException - If an error occurs importing the leaf certificate into a token.

importCACertPackage

public X509Certificate importCACertPackage(byte[] certPackage)
                                    throws java.security.cert.CertificateEncodingException,
                                           TokenException
Imports a chain of certificates, none of which is a user certificate.
Parameters:
certPackage - An encoded certificate or certificate chain. Acceptable encodings are binary PKCS #7 SignedData objects and DER-encoded certificates, which may or may not be wrapped in a Base-64 encoding package surrounded by "-----BEGIN CERTIFICATE-----" and "-----END CERTIFICATE-----".
Returns:
The leaf certificate from the chain.
Throws:
java.security.cert.CertificateEncodingException - If the package encoding was not recognized.
TokenException - If an error occurs importing a leaf certificate into a token.

importCertToPerm

public InternalCertificate importCertToPerm(X509Certificate cert,
                                            java.lang.String nickname)
                                     throws TokenException,
                                            InvalidNicknameException
Imports a single certificate into the permanent certificate database.
Parameters:
derCert - the certificate you want to add
nickname - the nickname you want to refer to the certificate as (must not be null)

importCertToPermNative

private InternalCertificate importCertToPermNative(X509Certificate cert,
                                                   java.lang.String nickname)
                                            throws TokenException

importCertPackageNative

private X509Certificate importCertPackageNative(byte[] certPackage,
                                                java.lang.String nickname,
                                                boolean noUser,
                                                boolean leafIsCA)
                                         throws java.security.cert.CertificateEncodingException,
                                                CryptoManager.NicknameConflictException,
                                                CryptoManager.UserCertConflictException,
                                                NoSuchItemOnTokenException,
                                                TokenException
Parameters:
noUser - true if we know that none of the certs are user certs. In this case, no attempt will be made to find a matching private key for the leaf certificate.

importCRL

public void importCRL(byte[] crl,
                      java.lang.String url)
               throws CRLImportException,
                      TokenException
Imports a CRL, and stores it into the cert7.db Validate CRL then import it to the dbase. If there is already a CRL with the same CA in the dbase, it will be replaced if derCRL is more up to date.
Parameters:
crl - the DER-encoded CRL.
url - the URL where this CRL can be retrieved from (for future updates). [ note that CRLs are not retrieved automatically ]. Can be null
Throws:
CRLImportException - If the package encoding was not recognized.

importCRLNative

private void importCRLNative(byte[] crl,
                             java.lang.String url,
                             int rl_type)
                      throws CRLImportException,
                             TokenException
Imports a CRL, and stores it into the cert7.db
Parameters:
the - DER-encoded CRL.

exportCertsToPKCS7

public byte[] exportCertsToPKCS7(X509Certificate[] certs)
                          throws java.security.cert.CertificateEncodingException
Exports one or more certificates into a PKCS #7 certificate container. This is just a SignedData object whose certificates field contains the given certificates but whose content field is empty.
Parameters:
certs - One or more certificates that should be exported into the PKCS #7 object. The leaf certificate should be the first in the chain. The output of buildCertificateChain would be appropriate here.
Returns:
A byte array containing a PKCS #7 SignedData object.
Throws:
java.security.cert.CertificateEncodingException - If the array is empty, or an error occurred encoding the certificates.
See Also:
buildCertificateChain(org.mozilla.jss.crypto.X509Certificate)

findCertByNickname

public X509Certificate findCertByNickname(java.lang.String nickname)
                                   throws ObjectNotFoundException,
                                          TokenException
Looks up a certificate given its nickname.
Parameters:
nickname - The nickname of the certificate to look for.
Returns:
The certificate matching this nickname, if one is found.
Throws:
ObjectNotFoundException - If no certificate could be found with the given nickname.
TokenException - If an error occurs in the security library.

findCertsByNickname

public X509Certificate[] findCertsByNickname(java.lang.String nickname)
                                      throws TokenException
Returns all certificates with the given nickname.
Parameters:
nickname - The nickname of the certificate to look for.
Returns:
The certificates matching this nickname. The array may be empty if no matching certs were found.
Throws:
TokenException - If an error occurs in the security library.

findCertByIssuerAndSerialNumber

public X509Certificate findCertByIssuerAndSerialNumber(byte[] derIssuer,
                                                       INTEGER serialNumber)
                                                throws ObjectNotFoundException,
                                                       TokenException
Looks up a certificate by issuer and serial number. The internal database and all PKCS #11 modules are searched.
Parameters:
derIssuer - The DER encoding of the certificate issuer name. The issuer name has ASN.1 type Name, which is defined in X.501.
serialNumber - The certificate serial number.
Throws:
ObjectNotFoundException - If the certificate is not found in the internal certificate database or on any PKCS #11 token.
TokenException - If an error occurs in the security library.

findCertByIssuerAndSerialNumberNative

private X509Certificate findCertByIssuerAndSerialNumberNative(byte[] derIssuer,
                                                              byte[] serialNumber)
                                                       throws ObjectNotFoundException,
                                                              TokenException
Parameters:
serialNumber - The contents octets of a DER-encoding of the certificate serial number.

findCertByNicknameNative

protected X509Certificate findCertByNicknameNative(java.lang.String nickname)
                                            throws ObjectNotFoundException,
                                                   TokenException

findCertsByNicknameNative

protected X509Certificate[] findCertsByNicknameNative(java.lang.String nickname)
                                               throws TokenException

buildCertificateChain

public X509Certificate[] buildCertificateChain(X509Certificate leaf)
                                        throws java.security.cert.CertificateException,
                                               TokenException
Given a certificate, constructs its certificate chain. It may or may not chain up to a trusted root.
Parameters:
leaf - The certificate that is the starting point of the chain.
Returns:
An array of certificates, starting at the leaf and ending with the highest certificate on the chain that was found.
Throws:
java.security.cert.CertificateException - If the certificate is not recognized by the underlying provider.

buildCertificateChainNative

X509Certificate[] buildCertificateChainNative(PK11Cert leaf)
                                        throws java.security.cert.CertificateException,
                                               TokenException

findPrivKeyByCert

public PrivateKey findPrivKeyByCert(X509Certificate cert)
                             throws ObjectNotFoundException,
                                    TokenException
Looks up the PrivateKey matching the given certificate.
Throws:
ObjectNotFoundException - If no private key can be found matching the given certificate.
TokenException - If an error occurs in the security library.

findPrivKeyByCertNative

protected PrivateKey findPrivKeyByCertNative(X509Certificate cert)
                                      throws ObjectNotFoundException,
                                             TokenException

createPseudoRandomNumberGenerator

public JSSSecureRandom createPseudoRandomNumberGenerator()
Retrieves a FIPS-140-1 validated random number generator.
Returns:
A JSS SecureRandom implemented with FIPS-validated NSS.

getSecureRNG

public JSSSecureRandom getSecureRNG()
Retrieves a FIPS-140-1 validated random number generator.
Specified by:
getSecureRNG in interface TokenSupplier
Returns:
A JSS SecureRandom implemented with FIPS-validated NSS.

loadNativeLibraries

static void loadNativeLibraries()
Loads the JSS dynamic library if necessary. The system property "jss.load" will be set to "no" by jssjava because it is statically linked to the jss libraries. If this property is not set, that means we are not running jssjava and need to dynamically load the library.

This method is idempotent.


JSS 3.1.1