org.mozilla.jss

Class CryptoManager

public final class CryptoManager extends 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.
Nested Class Summary
static classCryptoManager.CertUsage
CertUsage options for validation
static classCryptoManager.InitializationValues
The various options that can be used to initialize CryptoManager.
static classCryptoManager.InvalidLengthException
static classCryptoManager.NicknameConflictException
static classCryptoManager.NotInitializedException
static classCryptoManager.UserCertConflictException
Field Summary
static StringJAR_DBM_VERSION
static StringJAR_JDK_VERSION
static StringJAR_JSS_VERSION
static StringJAR_NSPR_VERSION
static StringJAR_NSS_VERSION
Constructor Summary
protected CryptoManager()
Constructor, for internal use only.
Method Summary
X509Certificate[]buildCertificateChain(X509Certificate leaf)
Given a certificate, constructs its certificate chain.
voidconfigureOCSP(boolean ocspCheckingEnabled, String ocspResponderURL, String ocspResponderCertNickname)
Enables OCSP, note when you Initialize JSS for the first time, for backwards compatibility, the initialize will enable OCSP if you previously set values.ocspCheckingEnabled and values.ocspResponderURL/values.ocspResponderCertNickname configureOCSP will allow changing of the the OCSPResponder at runtime.
JSSSecureRandomcreatePseudoRandomNumberGenerator()
Retrieves a FIPS-140-2 validated random number generator.
byte[]exportCertsToPKCS7(X509Certificate[] certs)
Exports one or more certificates into a PKCS #7 certificate container.
X509CertificatefindCertByIssuerAndSerialNumber(byte[] derIssuer, INTEGER serialNumber)
Looks up a certificate by issuer and serial number.
X509CertificatefindCertByNickname(String nickname)
Looks up a certificate given its nickname.
protected X509CertificatefindCertByNicknameNative(String nickname)
X509Certificate[]findCertsByNickname(String nickname)
Returns all certificates with the given nickname.
protected X509Certificate[]findCertsByNicknameNative(String nickname)
PrivateKeyfindPrivKeyByCert(X509Certificate cert)
Looks up the PrivateKey matching the given certificate.
protected PrivateKeyfindPrivKeyByCertNative(X509Certificate cert)
booleanFIPSEnabled()
Determines whether FIPS-140-2 compliance is active.
EnumerationgetAllTokens()
Retrieves all tokens.
X509Certificate[]getCACerts()
Retrieves all CA certificates in the trust database.
EnumerationgetExternalTokens()
Retrieves all tokens except those built into NSS.
static CryptoManagergetInstance()
Retrieve the single instance of CryptoManager.
CryptoTokengetInternalCryptoToken()
Retrieves the internal cryptographic services token.
CryptoTokengetInternalKeyStorageToken()
Retrieves the internal key storage token.
EnumerationgetModules()
Retrieves all installed cryptographic modules.
PasswordCallbackgetPasswordCallback()
Returns the currently registered password callback.
X509Certificate[]getPermCerts()
Retrieves all certificates in the trust database.
JSSSecureRandomgetSecureRNG()
Retrieves a FIPS-140-2 validated random number generator.
CryptoTokengetThreadToken()
Returns the default token for the current thread.
CryptoTokengetTokenByName(String name)
Looks up the CryptoToken with the given name.
EnumerationgetTokensSupportingAlgorithm(Algorithm alg)
Retrieves all tokens that support the given algorithm.
X509CertificateimportCACertPackage(byte[] certPackage)
Imports a chain of certificates, none of which is a user certificate.
X509CertificateimportCertPackage(byte[] certPackage, String nickname)
Imports a chain of certificates.
InternalCertificateimportCertToPerm(X509Certificate cert, String nickname)
Imports a single certificate into the permanent certificate database.
voidimportCRL(byte[] crl, String url)
Imports a CRL, and stores it into the cert7.db Validate CRL then import it to the dbase.
X509CertificateimportUserCACertPackage(byte[] certPackage, String nickname)
Imports a chain of certificates.
static voidinitialize(String configDir)
Initialize the security subsystem.
static voidinitialize(CryptoManager.InitializationValues values)
Initialize the security subsystem.
booleanisCertValid(String nickname, boolean checkSig, CryptoManager.CertUsage certUsage)
Verify a certificate that exists in the given cert database, check if is valid and that we trust the issuer.
booleanisCertValid(byte[] certPackage, boolean checkSig, CryptoManager.CertUsage certUsage)
Verify a certificate in memory.
voidsetPasswordCallback(PasswordCallback pwcb)
This function sets the global password callback.
voidsetThreadToken(CryptoToken token)
Sets the default token for the current thread.

Field Detail

JAR_DBM_VERSION

public static final String JAR_DBM_VERSION

JAR_JDK_VERSION

public static final String JAR_JDK_VERSION

JAR_JSS_VERSION

public static final String JAR_JSS_VERSION

JAR_NSPR_VERSION

public static final String JAR_NSPR_VERSION

JAR_NSS_VERSION

public static final String JAR_NSS_VERSION

Constructor Detail

CryptoManager

protected CryptoManager()
Constructor, for internal use only.

Method Detail

buildCertificateChain

public X509Certificate[] buildCertificateChain(X509Certificate leaf)
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: CertificateException If the certificate is not recognized by the underlying provider.

configureOCSP

public void configureOCSP(boolean ocspCheckingEnabled, String ocspResponderURL, String ocspResponderCertNickname)
Enables OCSP, note when you Initialize JSS for the first time, for backwards compatibility, the initialize will enable OCSP if you previously set values.ocspCheckingEnabled and values.ocspResponderURL/values.ocspResponderCertNickname configureOCSP will allow changing of the the OCSPResponder at runtime. * @param ocspChecking true or false to enable/disable OCSP * @param ocspResponderURL - url of the OCSP responder * @param ocspResponderCertNickname - the nickname of the OCSP signer certificate or the CA certificate found in the cert DB

createPseudoRandomNumberGenerator

public JSSSecureRandom createPseudoRandomNumberGenerator()
Retrieves a FIPS-140-2 validated random number generator.

Returns: A JSS SecureRandom implemented with FIPS-validated NSS.

exportCertsToPKCS7

public byte[] exportCertsToPKCS7(X509Certificate[] certs)
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: CertificateEncodingException If the array is empty, or an error occurred encoding the certificates.

See Also: CryptoManager

findCertByIssuerAndSerialNumber

public X509Certificate findCertByIssuerAndSerialNumber(byte[] derIssuer, INTEGER serialNumber)
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.

findCertByNickname

public X509Certificate findCertByNickname(String nickname)
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.

findCertByNicknameNative

protected X509Certificate findCertByNicknameNative(String nickname)

findCertsByNickname

public X509Certificate[] findCertsByNickname(String nickname)
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.

findCertsByNicknameNative

protected X509Certificate[] findCertsByNicknameNative(String nickname)

findPrivKeyByCert

public PrivateKey findPrivKeyByCert(X509Certificate cert)
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)

FIPSEnabled

public boolean FIPSEnabled()
Determines whether FIPS-140-2 compliance is active.

Returns: true if the security library is in FIPS-140-2 compliant mode.

getAllTokens

public 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

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.

getExternalTokens

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

getInstance

public static CryptoManager getInstance()
Retrieve the single instance of CryptoManager. This cannot be called before initialization.

Throws: NotInitializedException If initialize(InitializationValues has not yet been called.

See Also: initialize

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.

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.

getModules

public 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

getPasswordCallback

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

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.

getSecureRNG

public JSSSecureRandom getSecureRNG()
Retrieves a FIPS-140-2 validated random number generator.

Returns: A JSS SecureRandom implemented with FIPS-validated NSS.

getThreadToken

public CryptoToken getThreadToken()
Returns the default token for the current thread. This token will be used when JSS is called through the JCA interface, which has no means of specifying which token to use.

If no token is set, the InternalKeyStorageToken will be used. Setting this thread's token to null will also cause the InternalKeyStorageToken to be used.

Returns: The default token for this thread. If it has not been specified, it will be the InternalKeyStorageToken.

getTokenByName

public CryptoToken getTokenByName(String name)
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 Enumeration getTokensSupportingAlgorithm(Algorithm alg)
Retrieves all tokens that support the given algorithm.

importCACertPackage

public X509Certificate importCACertPackage(byte[] certPackage)
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: CertificateEncodingException If the package encoding was not recognized. TokenException If an error occurs importing a leaf certificate into a token.

importCertPackage

public X509Certificate importCertPackage(byte[] certPackage, String nickname)
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: 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. 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.

importCertToPerm

public InternalCertificate importCertToPerm(X509Certificate cert, String nickname)
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)

importCRL

public void importCRL(byte[] crl, String url)
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.

importUserCACertPackage

public X509Certificate importUserCACertPackage(byte[] certPackage, String nickname)
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: CertificateEncodingException If the package encoding was not recognized. CertificateNicknameConflictException If the leaf certificate another certificate already has the given nickname. 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.

initialize

public static void initialize(String configDir)
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)
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.

isCertValid

public boolean isCertValid(String nickname, boolean checkSig, CryptoManager.CertUsage certUsage)
Verify a certificate that exists in the given cert database, check if is valid and that we trust the issuer. Verify time against Now.

Parameters: nickname The nickname of the certificate to verify. checkSig verify the signature of the certificate certUsage see exposed certUsage defines to verify Certificate

Returns: true for success; false otherwise

Throws: InvalidNicknameException If the nickname is null ObjectNotFoundException If no certificate could be found with the given nickname.

isCertValid

public boolean isCertValid(byte[] certPackage, boolean checkSig, CryptoManager.CertUsage certUsage)
Verify a certificate in memory. Check if valid and that we trust the issuer. Verify time against Now.

Parameters: certificate in memory checkSig verify the signature of the certificate certUsage see exposed certUsage defines to verify Certificate

Returns: true for success; false otherwise

Throws: TokenException unable to insert temporary certificate into database. CertificateEncodingException If the package encoding was not recognized.

setPasswordCallback

public void setPasswordCallback(PasswordCallback pwcb)
This function sets the global password callback. It is not thread-safe to change this.

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

setThreadToken

public void setThreadToken(CryptoToken token)
Sets the default token for the current thread. This token will be used when JSS is called through the JCA interface, which has no means of specifying which token to use.

If no token is set, the InternalKeyStorageToken will be used. Setting this thread's token to null will also cause the InternalKeyStorageToken to be used.

Parameters: The token to use for crypto operations. Specifying null will cause the InternalKeyStorageToken to be used.