org.mozilla.jss.crypto

Interface CryptoToken

All Known Implementing Classes:

PK11Token

public interface CryptoToken

A CryptoToken performs cryptographic operations and stores cryptographic items, such as keys and certs. It corresponds to a Cryptographic Service Provider (CSP) in CDSA, and to a PKCS #11 token.

Instances of CryptoToken are obtained from CryptoManager.

See Also:

CryptoManager

Field Summary

Fields

Modifier and Type	Field and Description
static int	EVERY_TIME Need to provide a password before each crypto operation.
static int	ONE_TIME Login once, never need to re-enter the password until you log out.
static int	TIMEOUT Need to re-login after a period of time.

Method Summary

Methods

Modifier and Type	Method and Description
void	changePassword(PasswordCallback oldpw, PasswordCallback newpw) Change the password of this token.
SymmetricKey	cloneKey(SymmetricKey key) Clones a SymmetricKey from a different token onto this token.
boolean	doesAlgorithm(Algorithm alg) Determines whether this token supports the given algorithm.
boolean	equals(java.lang.Object object) Deep comparison operation.
java.lang.String	generateCertRequest(java.lang.String subject, int keysize, java.lang.String keyType, byte[] P, byte[] Q, byte[] G) Generates a b64 encoded PKCS10 blob used for making cert request.
Cipher	getCipherContext(EncryptionAlgorithm algorithm) Creates a Cipher object, which can be used for encryption and decryption.
CryptoStore	getCryptoStore() Get the CryptoStore interface to this token's objects.
JSSMessageDigest	getDigestContext(DigestAlgorithm algorithm) Creates a Digest object.
KeyGenerator	getKeyGenerator(KeyGenAlgorithm algorithm) Creates a KeyGenerator object, which can be used to generate symmetric encryption keys.
KeyPairGenerator	getKeyPairGenerator(KeyPairAlgorithm algorithm) Creates a KeyPairGenerator object, which can be used to generate key pairs.
KeyWrapper	getKeyWrapper(KeyWrapAlgorithm algorithm)
int	getLoginMode() Returns the login mode of this token: ONE_TIME, TIMEOUT, or EVERY_TIME.
int	getLoginTimeoutMinutes() Returns the login timeout period.
java.lang.String	getName() Obtain the nickname, or label, of this token.
Signature	getSignatureContext(SignatureAlgorithm algorithm) Creates a Signature object, which can perform signing and signature verification.
void	initPassword(PasswordCallback securityOfficerPW, PasswordCallback userPW) Initialize the password of this token.
boolean	isLoggedIn() Find out if the token is currently logged in.
boolean	isPresent() Determines whether this token is currently present.
void	login(PasswordCallback pwcb) Login to the token.
void	logout() Logout of the token.
boolean	needsLogin() returns true if this token needs to be logged into before it can be used.
boolean	passwordIsInitialized() Determine whether the password has been initialized yet.
void	setLoginMode(int mode) Sets the login mode of this token.
void	setLoginTimeoutMinutes(int timeoutMinutes) Sets the timeout period for logging in.

Field Detail

ONE_TIME

static final int ONE_TIME

Login once, never need to re-enter the password until you log out.

See Also:

Constant Field Values

TIMEOUT

static final int TIMEOUT

Need to re-login after a period of time.

See Also:

setLoginTimeoutMinutes(int), Constant Field Values

EVERY_TIME

static final int EVERY_TIME

Need to provide a password before each crypto operation.

See Also:

Constant Field Values

Method Detail

getSignatureContext

Signature getSignatureContext(SignatureAlgorithm algorithm)
                              throws java.security.NoSuchAlgorithmException,
                                     TokenException

Creates a Signature object, which can perform signing and signature verification. Signing and verification cryptographic operations will take place on this token. The signing key must be located on this token.

Parameters:

algorithm - The algorithm used for the signing/verification.

Throws:

java.security.NoSuchAlgorithmException - If the given algorithm is not supported by this provider.

TokenException

getDigestContext

JSSMessageDigest getDigestContext(DigestAlgorithm algorithm)
                                  throws java.security.NoSuchAlgorithmException,
                                         java.security.DigestException

Creates a Digest object. Digesting cryptographic operations will take place on this token.

Parameters:

algorithm - The algorithm used for digesting.

Throws:

java.security.NoSuchAlgorithmException - If this provider does not support the given algorithm.

java.security.DigestException

getCipherContext

Cipher getCipherContext(EncryptionAlgorithm algorithm)
                        throws java.security.NoSuchAlgorithmException,
                               TokenException

Creates a Cipher object, which can be used for encryption and decryption. Cryptographic operations will take place on this token. The keys used in the operations must be located on this token.

Parameters:

algorithm - The algorithm used for encryption/decryption.

Throws:

java.security.NoSuchAlgorithmException - If this provider does not support the given algorithm.

TokenException

getKeyWrapper

KeyWrapper getKeyWrapper(KeyWrapAlgorithm algorithm)
                         throws java.security.NoSuchAlgorithmException,
                                TokenException

Throws:

java.security.NoSuchAlgorithmException

TokenException

getKeyGenerator

KeyGenerator getKeyGenerator(KeyGenAlgorithm algorithm)
                             throws java.security.NoSuchAlgorithmException,
                                    TokenException

Creates a KeyGenerator object, which can be used to generate symmetric encryption keys. Any keys generated with this KeyGenerator will be generated on this token.

Parameters:

algorithm - The algorithm that the keys will be used with.

Throws:

java.security.NoSuchAlgorithmException - If this token does not support the given algorithm.

TokenException

cloneKey

SymmetricKey cloneKey(SymmetricKey key)
                      throws SymmetricKey.NotExtractableException,
                             java.security.InvalidKeyException,
                             TokenException

Clones a SymmetricKey from a different token onto this token.

Throws:

SymmetricKey.NotExtractableException - If the key material cannot be extracted from the current token.

java.security.InvalidKeyException - If the owning token cannot process the key to be cloned.

TokenException

getKeyPairGenerator

KeyPairGenerator getKeyPairGenerator(KeyPairAlgorithm algorithm)
                                     throws java.security.NoSuchAlgorithmException,
                                            TokenException

Creates a KeyPairGenerator object, which can be used to generate key pairs. Any keypairs generated with this generator will be generated on this token.

Parameters:

algorithm - The algorithm that the keys will be used with (RSA, DSA, EC, etc.)

Throws:

java.security.NoSuchAlgorithmException - If this token does not support the given algorithm.

TokenException

generateCertRequest

java.lang.String generateCertRequest(java.lang.String subject,
                                   int keysize,
                                   java.lang.String keyType,
                                   byte[] P,
                                   byte[] Q,
                                   byte[] G)
                                     throws TokenException,
                                            java.security.InvalidParameterException,
                                            PQGParamGenException

Generates a b64 encoded PKCS10 blob used for making cert request. Begin/End brackets included.

Parameters:

subject - subject dn of the certificate

keysize - size of the key

keyType - "rsa" or "dsa"

P - The DSA prime parameter

Q - The DSA sub-prime parameter

G - The DSA base parameter

Returns:

base64 encoded pkcs10 certificate request with Begin/end brackets

Throws:

TokenException

java.security.InvalidParameterException

PQGParamGenException

doesAlgorithm

boolean doesAlgorithm(Algorithm alg)

Determines whether this token supports the given algorithm.

Parameters:

alg - A JSS algorithm. Note that for Signature, a token may fail to support a specific SignatureAlgorithm (such as RSASignatureWithMD5Digest) even though it does support the generic algorithm (RSASignature). In this case, the signature operation will be performed on that token, but the digest operation will be performed on the internal token.

Returns:

true if the token supports the algorithm.

login

void login(PasswordCallback pwcb)
           throws IncorrectPasswordException,
                  TokenException

Login to the token. If a token is logged in, it will not trigger password callbacks.

Parameters:

pwcb - The password callback for this token.

Throws:

IncorrectPasswordException - If the supplied password is incorrect.

TokenException

See Also:

setLoginMode(int), CryptoManager.setPasswordCallback(org.mozilla.jss.util.PasswordCallback)

logout

void logout()
            throws TokenException

Logout of the token.

Throws:

TokenException

getLoginMode

int getLoginMode()
                 throws TokenException

Returns the login mode of this token: ONE_TIME, TIMEOUT, or EVERY_TIME. The default is ONE_TIME.

Throws:

TokenException - If an error occurs on the token.

See Also:

getLoginTimeoutMinutes()

setLoginMode

void setLoginMode(int mode)
                  throws TokenException

Sets the login mode of this token.

Parameters:

mode - ONE_TIME, TIMEOUT, or EVERY_TIME

Throws:

TokenException - If this mode is not supported by this token, or an error occurs on the token.

See Also:

login(org.mozilla.jss.util.PasswordCallback), setLoginTimeoutMinutes(int)

getLoginTimeoutMinutes

int getLoginTimeoutMinutes()
                           throws TokenException

Returns the login timeout period. The timeout is only used if the login mode is TIMEOUT.

Throws:

TokenException - If an error occurs on the token.

See Also:

getLoginMode()

setLoginTimeoutMinutes

void setLoginTimeoutMinutes(int timeoutMinutes)
                            throws TokenException

Sets the timeout period for logging in. This will only be used if the login mode is TIMEOUT.

Throws:

TokenException - If timeouts are not supported by this token, or an error occurs on the token.

See Also:

setLoginMode(int)

isLoggedIn

boolean isLoggedIn()
                   throws TokenException

Find out if the token is currently logged in.

Throws:

TokenException

See Also:

login(org.mozilla.jss.util.PasswordCallback), logout()

needsLogin

boolean needsLogin()
                   throws TokenException

returns true if this token needs to be logged into before it can be used.

Throws:

TokenException

See Also:

login(org.mozilla.jss.util.PasswordCallback), logout()

initPassword

void initPassword(PasswordCallback securityOfficerPW,
                PasswordCallback userPW)
                  throws IncorrectPasswordException,
                         AlreadyInitializedException,
                         TokenException

Initialize the password of this token.

Parameters:

securityOfficerPW - A callback to obtain the password of the SecurityOfficer. Pass in a NullPasswordCallback if there is no security officer password. Must not be null.

userPW - A callback to obtain the new password for this token. Must not be null.

Throws:

IncorrectPasswordException - If the supplied security officer password is incorrect.

AlreadyInitializedException - If the token only allows one password initialization, and it has already occurred.

TokenException - If an error occurs on the token.

passwordIsInitialized

boolean passwordIsInitialized()
                              throws TokenException

Determine whether the password has been initialized yet. Some tokens (such as the Netscape Internal Key Token) don't allow initializing the PIN more than once.

Throws:

TokenException - If an error occurs on the token.

changePassword

void changePassword(PasswordCallback oldpw,
                  PasswordCallback newpw)
                    throws IncorrectPasswordException,
                           TokenException

Change the password of this token.

Parameters:

oldpw - A callback (which could be just a Password) to retrieve the current password.

newpw - A callback (which could be just a Password) to retrieve the new password.

Throws:

IncorrectPasswordException - If the supplied old password is incorrect.

TokenException

getName

java.lang.String getName()
                         throws TokenException

Obtain the nickname, or label, of this token.

Throws:

TokenException - If an error occurs on the token.

getCryptoStore

CryptoStore getCryptoStore()

Get the CryptoStore interface to this token's objects.

equals

boolean equals(java.lang.Object object)

Deep comparison operation. Use this, rather than ==, to determine whether two CryptoTokens are the same.

Overrides:

equals in class java.lang.Object

isPresent

boolean isPresent()

Determines whether this token is currently present. This could return false if the token is a smart card that was removed from its slot.