Package org.mozilla.jss.pkcs11

Class PK11Token

java.lang.Object

org.mozilla.jss.pkcs11.PK11Token

All Implemented Interfaces:

CryptoToken

public final class PK11Token
extends Object
implements CryptoToken

A PKCS #11 token. Currently, these can only be obtained from the CryptoManager class.

Version:

$Revision$ $Date$

See Also:

• CryptoManager

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	PK11Token.NotInitializedException	Thrown if the operation requires that the token be logged in, and it isn't.

Field Summary

Fields

Modifier and Type	Field	Description
protected PK11Store	cryptoStore
protected boolean	mIsInternalCryptoToken
protected boolean	mIsInternalKeyStorageToken
protected TokenProxy	tokenProxy

Fields inherited from interface org.mozilla.jss.crypto.CryptoToken

EVERY_TIME, ONE_TIME, TIMEOUT

Constructor Summary

Constructors

Modifier	Constructor	Description
protected	PK11Token()
protected	PK11Token(byte[] pointer, boolean internal, boolean keyStorage)	Creates a new PK11Token.

Method Summary

Modifier and Type	Method	Description
protected void	changePassword(byte[] oldPIN, byte[] newPIN)	Change the password on the token from the old one to the new one.
void	changePassword(PasswordCallback oldPINcb, PasswordCallback newPINcb)	Change password.
SymmetricKey	cloneKey(SymmetricKey key)	Allows a SymmetricKey to be cloned on a different token.
boolean	doesAlgorithm(Algorithm alg)	Determines whether this token is capable of performing the given algorithm.
boolean	equals(Object obj)	Deep-comparison operator.
String	generateCertRequest(String subject, int keysize, String keyType, byte[] prime, byte[] subPrime, byte[] base)	Generates a PKCS#10 certificate request including Begin/End brackets
protected String	generatePK10(String subject, int keysize, String keyType, byte[] P, byte[] Q, byte[] G)
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.
String	getName()	Obtain the nickname, or label, of this token.
Provider	getProvider()
TokenProxy	getProxy()
SecureRandom	getRandomGenerator()
Signature	getSignatureContext(SignatureAlgorithm algorithm)	Creates a Signature object, which can perform signing and signature verification.
PK11SymmetricKeyDeriver	getSymmetricKeyDeriver()
int	hashCode()	HashCode from underline token.
void	importPublicKey(PublicKey pubKey, boolean permanent)
protected void	initPassword(byte[] ssopw, byte[] userpw)
void	initPassword(PasswordCallback ssopwcb, PasswordCallback userpwcb)	Initialize PIN.
boolean	isInternalCryptoToken()
boolean	isInternalKeyStorageToken()
boolean	isLoggedIn()	Find out if the token is currently logged in.
boolean	isPresent()	Determines if the given token is present on the system.
boolean	isWritable()
void	login(PasswordCallback callback)	Log into the token.
void	logout()	Log out of the token.
protected PasswordCallbackInfo	makePWCBInfo()
protected void	nativeLogin(PasswordCallback callback)
boolean	needsLogin()	returns true if this token needs to be logged into before it can be used.
boolean	passwordIsInitialized()	Determine whether the token has been initialized yet.
protected boolean	PWInitable()	Make sure the PIN can be initialized.
void	setLoginMode(int mode)	Sets the login mode of this token.
void	setLoginTimeoutMinutes(int timeoutMinutes)	Sets the timeout period for logging in.
protected boolean	SSOPasswordIsCorrect(byte[] ssopw)
protected boolean	userPasswordIsCorrect(byte[] pw)	Check the given password, return true if it's right, false if it's wrong.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Field Details

tokenProxy

protected TokenProxy tokenProxy

cryptoStore

protected PK11Store cryptoStore

mIsInternalCryptoToken

protected boolean mIsInternalCryptoToken

mIsInternalKeyStorageToken

protected boolean mIsInternalKeyStorageToken

Constructor Details

PK11Token

protected PK11Token()

PK11Token

protected PK11Token(byte[] pointer,
 boolean internal,
 boolean keyStorage)

Creates a new PK11Token. Should only be called from PK11Token's native code.

Parameters:

pointer - A byte array containing a pointer to a PKCS #11 slot.

Method Details

getSignatureContext

public Signature getSignatureContext(SignatureAlgorithm algorithm)
                              throws NoSuchAlgorithmException,
TokenException

Description copied from interface: CryptoToken

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.

Specified by:

getSignatureContext in interface CryptoToken

Parameters:

algorithm - The algorithm used for the signing/verification.

Throws:

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

TokenException

getDigestContext

public JSSMessageDigest getDigestContext(DigestAlgorithm algorithm)
                                  throws NoSuchAlgorithmException,
DigestException

Description copied from interface: CryptoToken

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

Specified by:

getDigestContext in interface CryptoToken

Parameters:

algorithm - The algorithm used for digesting.

Throws:

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

DigestException

getCipherContext

public Cipher getCipherContext(EncryptionAlgorithm algorithm)
                        throws NoSuchAlgorithmException,
TokenException

Description copied from interface: CryptoToken

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.

Specified by:

getCipherContext in interface CryptoToken

Parameters:

algorithm - The algorithm used for encryption/decryption.

Throws:

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

TokenException

getKeyGenerator

public KeyGenerator getKeyGenerator(KeyGenAlgorithm algorithm)
                             throws NoSuchAlgorithmException,
TokenException

Description copied from interface: CryptoToken

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.

Specified by:

getKeyGenerator in interface CryptoToken

Parameters:

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

Throws:

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

TokenException

cloneKey

public SymmetricKey cloneKey(SymmetricKey key)
                      throws SymmetricKey.NotExtractableException,
InvalidKeyException,
TokenException

Allows a SymmetricKey to be cloned on a different token.

Specified by:

cloneKey in interface CryptoToken

Throws:

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

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

TokenException

getSymmetricKeyDeriver

public PK11SymmetricKeyDeriver getSymmetricKeyDeriver()

Specified by:

getSymmetricKeyDeriver in interface CryptoToken

getKeyWrapper

public KeyWrapper getKeyWrapper(KeyWrapAlgorithm algorithm)
                         throws NoSuchAlgorithmException,
TokenException

Specified by:

getKeyWrapper in interface CryptoToken

Throws:

NoSuchAlgorithmException

TokenException

getRandomGenerator

public SecureRandom getRandomGenerator()
                                throws NotImplementedException,
TokenException

Throws:

NotImplementedException

TokenException

getKeyPairGenerator

public KeyPairGenerator getKeyPairGenerator(KeyPairAlgorithm algorithm)
                                     throws NoSuchAlgorithmException,
TokenException

Description copied from interface: CryptoToken

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

Specified by:

getKeyPairGenerator in interface CryptoToken

Parameters:

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

Throws:

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

TokenException

isLoggedIn

public boolean isLoggedIn()
                   throws TokenException

Description copied from interface: CryptoToken

Find out if the token is currently logged in.

Specified by:

isLoggedIn in interface CryptoToken

Throws:

TokenException

See Also:

• CryptoToken.login(org.mozilla.jss.util.PasswordCallback)
• CryptoToken.logout()

needsLogin

public boolean needsLogin()
                   throws TokenException

Description copied from interface: CryptoToken

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

Specified by:

needsLogin in interface CryptoToken

Throws:

TokenException

See Also:

• CryptoToken.login(org.mozilla.jss.util.PasswordCallback)
• CryptoToken.logout()

login

public void login(PasswordCallback callback)
           throws IncorrectPasswordException,
TokenException

Log into the token. If you are already logged in, this method has no effect, even if the PIN is wrong.

Specified by:

login in interface CryptoToken

Parameters:

callback - A callback to use to obtain the password, or a Password object.

Throws:

PK11Token.NotInitializedException - The token has not yet been initialized.

IncorrectPasswordException - The specified password was incorrect.

TokenException

See Also:

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

nativeLogin

protected void nativeLogin(PasswordCallback callback)
                    throws IncorrectPasswordException,
TokenException

Throws:

IncorrectPasswordException

TokenException

isWritable

public boolean isWritable()

Returns:

true if the token is writable, false if it is read-only. Writable tokens can have their keys generated on the internal token and then moved out.

isPresent

public boolean isPresent()

Determines if the given token is present on the system. This would return false, for example, for a smart card reader that didn't have a card inserted.

Specified by:

isPresent in interface CryptoToken

logout

public void logout()
            throws TokenException

Log out of the token.

Specified by:

logout in interface CryptoToken

Throws:

TokenException - If you are already logged in, or an unspecified error occurs.

getLoginMode

public int getLoginMode()
                 throws TokenException

Description copied from interface: CryptoToken

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

Specified by:

getLoginMode in interface CryptoToken

Throws:

TokenException - If an error occurs on the token.

See Also:

• CryptoToken.getLoginTimeoutMinutes()

setLoginMode

public void setLoginMode(int mode)
                  throws TokenException

Description copied from interface: CryptoToken

Sets the login mode of this token.

Specified by:

setLoginMode in interface CryptoToken

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:

• CryptoToken.login(org.mozilla.jss.util.PasswordCallback)
• CryptoToken.setLoginTimeoutMinutes(int)

getLoginTimeoutMinutes

public int getLoginTimeoutMinutes()
                           throws TokenException

Description copied from interface: CryptoToken

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

Specified by:

getLoginTimeoutMinutes in interface CryptoToken

Throws:

TokenException - If an error occurs on the token.

See Also:

• CryptoToken.getLoginMode()

setLoginTimeoutMinutes

public void setLoginTimeoutMinutes(int timeoutMinutes)
                            throws TokenException

Description copied from interface: CryptoToken

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

Specified by:

setLoginTimeoutMinutes in interface CryptoToken

Throws:

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

See Also:

• CryptoToken.setLoginMode(int)

initPassword

public void initPassword(PasswordCallback ssopwcb,
 PasswordCallback userpwcb)
                  throws IncorrectPasswordException,
AlreadyInitializedException,
TokenException

Initialize PIN. This sets the user's new PIN, using the current security officer PIN for authentication.

Specified by:

initPassword in interface CryptoToken

Parameters:

ssopwcb - The security officer's current password callback.

userpwcb - The user's new password callback.

Throws:

IncorrectPasswordException - If the security officer PIN is incorrect.

AlreadyInitializedException - If the password hasn't already been set.

TokenException - If the PIN was already initialized, or there was an unspecified error in the token.

PWInitable

protected boolean PWInitable()
                      throws TokenException

Make sure the PIN can be initialized. This is mainly to check the internal module.

Throws:

TokenException

SSOPasswordIsCorrect

protected boolean SSOPasswordIsCorrect(byte[] ssopw)
                                throws TokenException,
AlreadyInitializedException

Throws:

TokenException

AlreadyInitializedException

initPassword

protected void initPassword(byte[] ssopw,
 byte[] userpw)
                     throws IncorrectPasswordException,
AlreadyInitializedException,
TokenException

Throws:

IncorrectPasswordException

AlreadyInitializedException

TokenException

passwordIsInitialized

public boolean passwordIsInitialized()
                              throws TokenException

Determine whether the token has been initialized yet.

Specified by:

passwordIsInitialized in interface CryptoToken

Throws:

TokenException - If an error occurs on the token.

changePassword

public void changePassword(PasswordCallback oldPINcb,
 PasswordCallback newPINcb)
                    throws IncorrectPasswordException,
TokenException

Change password. This changes the user's PIN after it has already been initialized.

Specified by:

changePassword in interface CryptoToken

Parameters:

oldPINcb - The user's old PIN callback.

newPINcb - The new PIN callback.

Throws:

IncorrectPasswordException - If the old PIN is incorrect.

TokenException - If some other error occurs on the token.

makePWCBInfo

protected PasswordCallbackInfo makePWCBInfo()

userPasswordIsCorrect

protected boolean userPasswordIsCorrect(byte[] pw)
                                 throws TokenException

Check the given password, return true if it's right, false if it's wrong.

Throws:

TokenException

changePassword

protected void changePassword(byte[] oldPIN,
 byte[] newPIN)
                       throws IncorrectPasswordException,
TokenException

Change the password on the token from the old one to the new one.

Throws:

IncorrectPasswordException

TokenException

getName

public String getName()

Description copied from interface: CryptoToken

Obtain the nickname, or label, of this token.

Specified by:

getName in interface CryptoToken

getProvider

public Provider getProvider()

getCryptoStore

public CryptoStore getCryptoStore()

Description copied from interface: CryptoToken

Get the CryptoStore interface to this token's objects.

Specified by:

getCryptoStore in interface CryptoToken

equals

public boolean equals(Object obj)

Deep-comparison operator.

Specified by:

equals in interface CryptoToken

Overrides:

equals in class Object

Returns:

true if these tokens point to the same underlying native token. false otherwise, or if compare is null.

hashCode

public int hashCode()

HashCode from underline token. Two token are equals if they have the same underline native token so they should return the same hash code

Overrides:

hashCode in class Object

Returns:

The hash code of the underlying token.

doesAlgorithm

public boolean doesAlgorithm(Algorithm alg)

Determines whether this token is capable of performing the given algorithm.

Specified by:

doesAlgorithm in interface CryptoToken

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.

generateCertRequest

public String generateCertRequest(String subject,
 int keysize,
 String keyType,
 byte[] prime,
 byte[] subPrime,
 byte[] base)
                           throws TokenException,
InvalidParameterException,
PQGParamGenException

Generates a PKCS#10 certificate request including Begin/End brackets

Specified by:

generateCertRequest in interface CryptoToken

Parameters:

subject - subject dn of the certificate

keysize - size of the key

keyType - "rsa" or "dsa"

prime - The DSA prime parameter

subPrime - The DSA sub-prime parameter

base - The DSA base parameter

Returns:

String that represents a PKCS#10 b64 encoded blob with begin/end brackets

Throws:

TokenException

InvalidParameterException

PQGParamGenException

generatePK10

protected String generatePK10(String subject,
 int keysize,
 String keyType,
 byte[] P,
 byte[] Q,
 byte[] G)
                       throws TokenException,
InvalidParameterException

Throws:

TokenException

InvalidParameterException

getProxy

public TokenProxy getProxy()

isInternalCryptoToken

public boolean isInternalCryptoToken()

Returns:

true if this is the internal token used for bulk crypto.

isInternalKeyStorageToken

public boolean isInternalKeyStorageToken()

Returns:

true if this is the internal key storage token.

importPublicKey

public void importPublicKey(PublicKey pubKey,
 boolean permanent)
                     throws TokenException

Specified by:

importPublicKey in interface CryptoToken

Throws:

TokenException