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.
FIPSEnabled
public boolean FIPSEnabled()
Determines whether FIPS-140-2 compliance is active.
- true if the security library is in FIPS-140-2 compliant mode.
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.
leaf
- The certificate that is the starting point of the chain.
- An array of certificates, starting at the leaf and ending
with the highest certificate on the chain that was found.
configureOCSP
public void configureOCSP(boolean ocspCheckingEnabled,
String ocspResponderURL,
String ocspResponderCertNickname)
throws GeneralSecurityException
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.
- A JSS SecureRandom implemented with FIPS-validated NSS.
exportCertsToPKCS7
public byte[] exportCertsToPKCS7(X509Certificate[] certs)
throws 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.
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.
- A byte array containing a PKCS #7 SignedData object.
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.
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.
findCertByNickname
public X509Certificate findCertByNickname(String nickname)
throws ObjectNotFoundException,
TokenException
Looks up a certificate given its nickname.
nickname
- The nickname of the certificate to look for.
- The certificate matching this nickname, if one is found.
findCertsByNickname
public X509Certificate[] findCertsByNickname(String nickname)
throws TokenException
Returns all certificates with the given nickname.
nickname
- The nickname of the certificate to look for.
- The certificates matching this nickname. The array may be empty
if no matching certs were found.
getAllTokens
public Enumeration getAllTokens()
Retrieves all tokens. This is an enumeration of all tokens on all
modules.
- All tokens accessible from JSS. Each item of the enumeration
is a
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.
- 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).
- All tokens accessible from JSS, except for the built-in
internal tokens.
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.
- getInternalCryptoToken in interface TokenSupplier
- 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.
- The internal key storage token.
getModules
public Enumeration getModules()
Retrieves all installed cryptographic modules.
- An enumeration of all installed PKCS #11 modules. Each
item in the enumeration is a
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.
- An array of all certificates stored permanently
in the trust database.
getSecureRNG
public JSSSecureRandom getSecureRNG()
Retrieves a FIPS-140-2 validated random number generator.
- getSecureRNG in interface TokenSupplier
- 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.
- getThreadToken in interface TokenSupplier
- The default token for this thread. If it has not been specified,
it will be the InternalKeyStorageToken.
getTokenByName
public CryptoToken getTokenByName(String name)
throws NoSuchTokenException
Looks up the CryptoToken with the given name. Searches all
loaded cryptographic modules for the token.
name
- The name of the token.
getTokensSupportingAlgorithm
public Enumeration getTokensSupportingAlgorithm(Algorithm alg)
Retrieves all tokens that support the given algorithm.
importCACertPackage
public X509Certificate importCACertPackage(byte[] certPackage)
throws CertificateEncodingException,
TokenException
Imports a chain of certificates, none of which is a user certificate.
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-----
".
- The leaf certificate from the chain.
TokenException
- If an error occurs importing a leaf
certificate into a token.
importCRL
public void importCRL(byte[] crl,
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.
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
importCertPackage
public X509Certificate importCertPackage(byte[] certPackage,
String nickname)
throws 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.
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.
- The leaf certificate from the chain.
importUserCACertPackage
public X509Certificate importUserCACertPackage(byte[] certPackage,
String nickname)
throws 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).
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.
- The leaf certificate from the chain.
initialize
public static void initialize(String configDir)
throws KeyDatabaseException,
CertDatabaseException,
AlreadyInitializedException,
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()
.
configDir
- The directory containing the security databases.
initialize
public static void initialize(CryptoManager.InitializationValues values)
throws KeyDatabaseException,
CertDatabaseException,
AlreadyInitializedException,
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()
.
values
- The options with which to initialize CryptoManager.
isCertValid
public boolean isCertValid(String nickname,
boolean checkSig,
CryptoManager.CertUsage certUsage)
throws ObjectNotFoundException,
InvalidNicknameException
Verify a certificate that exists in the given cert database,
check if is valid and that we trust the issuer. Verify time
against Now.
nickname
- The nickname of the certificate to verify.checkSig
- verify the signature of the certificatecertUsage
- see exposed certUsage defines to verify Certificate
- true for success; false otherwise
isCertValid
public boolean isCertValid(byte[] certPackage,
boolean checkSig,
CryptoManager.CertUsage certUsage)
throws TokenException,
CertificateEncodingException
Verify a certificate in memory. Check if
valid and that we trust the issuer. Verify time
against Now.
checkSig
- verify the signature of the certificatecertUsage
- see exposed certUsage defines to verify Certificate
- true for success; false otherwise
TokenException
- unable to insert temporary certificate
into database.
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.
- setThreadToken in interface TokenSupplier