org.mozilla.jss.pkcs11

Class PK11Token

Implemented Interfaces:
CryptoToken

public final class PK11Token
extends java.lang.Object
implements CryptoToken

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

Nested Class Summary

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

Field Summary

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

PK11Token()
PK11Token(byte[] pointer, boolean internal, boolean keyStorage)
Creates a new PK11Token.

Method Summary

protected boolean
PWInitable()
Make sure the PIN can be initialized.
protected boolean
SSOPasswordIsCorrect(byte[] ssopw)
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[] P, byte[] Q, byte[] G)
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)
Deprecated. Use the JCA interface instead (javax.crypto.Cipher)
CryptoStore
getCryptoStore()
Get the CryptoStore interface to this token's objects.
JSSMessageDigest
getDigestContext(DigestAlgorithm algorithm)
Deprecated. Use the JCA interface instead (java.security.MessageDigest)
KeyGenerator
getKeyGenerator(KeyGenAlgorithm algorithm)
Deprecated. Use the JCA interface instead (javax.crypto.KeyGenerator)
KeyPairGenerator
getKeyPairGenerator(KeyPairAlgorithm algorithm)
Deprecated. Use the JCA interface instead (java.security.KeyPairGenerator)
KeyWrapper
getKeyWrapper(KeyWrapAlgorithm algorithm)
Deprecated. Use the JCA interface instead (javax.crypto.Cipher)
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.
java.security.Provider
getProvider()
TokenProxy
getProxy()
java.security.SecureRandom
getRandomGenerator()
Signature
getSignatureContext(SignatureAlgorithm algorithm)
Deprecated. Use the JCA interface instead (java.security.Signature)
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.
void
setLoginMode(int mode)
Sets the login mode of this token.
void
setLoginTimeoutMinutes(int timeoutMinutes)
Sets the timeout period for logging in.
protected boolean
userPasswordIsCorrect(byte[] pw)
Check the given password, return true if it's right, false if it's wrong.

Field Details

cryptoStore

protected PK11Store cryptoStore

mIsInternalCryptoToken

protected boolean mIsInternalCryptoToken

mIsInternalKeyStorageToken

protected boolean mIsInternalKeyStorageToken

tokenProxy

protected TokenProxy tokenProxy

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

PWInitable

protected boolean PWInitable()
            throws TokenException
Make sure the PIN can be initialized. This is mainly to check the internal module.

SSOPasswordIsCorrect

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

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.

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:
Throws:
IncorrectPasswordException - If the old PIN is incorrect.
TokenException - If some other error occurs on the token.

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.

doesAlgorithm

public boolean doesAlgorithm(Algorithm alg)
Determines whether this token is capable of performing the given algorithm.
Specified by:
doesAlgorithm in interface CryptoToken

equals

public boolean equals(Object obj)
Deep-comparison operator.
Specified by:
equals in interface CryptoToken
Returns:
true if these tokens point to the same underlying native token. false otherwise, or if compare is null.

generateCertRequest

public String generateCertRequest(String subject,
                                  int keysize,
                                  String keyType,
                                  byte[] P,
                                  byte[] Q,
                                  byte[] G)
            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"
P - The DSA prime parameter
Q - The DSA sub-prime parameter
G - The DSA base parameter
Returns:
String that represents a PKCS#10 b64 encoded blob with begin/end brackets

generatePK10

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

getCipherContext

public Cipher getCipherContext(EncryptionAlgorithm algorithm)
            throws NoSuchAlgorithmException,
                   TokenException

Deprecated. Use the JCA interface instead (javax.crypto.Cipher)

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.

getCryptoStore

public CryptoStore getCryptoStore()
Get the CryptoStore interface to this token's objects.
Specified by:
getCryptoStore in interface CryptoToken

getDigestContext

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

Deprecated. Use the JCA interface instead (java.security.MessageDigest)

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.

getKeyGenerator

public KeyGenerator getKeyGenerator(KeyGenAlgorithm algorithm)
            throws NoSuchAlgorithmException,
                   TokenException

Deprecated. Use the JCA interface instead (javax.crypto.KeyGenerator)

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.

getKeyPairGenerator

public KeyPairGenerator getKeyPairGenerator(KeyPairAlgorithm algorithm)
            throws NoSuchAlgorithmException,
                   TokenException

Deprecated. Use the JCA interface instead (java.security.KeyPairGenerator)

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

getKeyWrapper

public KeyWrapper getKeyWrapper(KeyWrapAlgorithm algorithm)
            throws NoSuchAlgorithmException,
                   TokenException

Deprecated. Use the JCA interface instead (javax.crypto.Cipher)

Specified by:
getKeyWrapper in interface CryptoToken

getLoginMode

public int getLoginMode()
            throws TokenException
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.

getLoginTimeoutMinutes

public int getLoginTimeoutMinutes()
            throws TokenException
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.

getName

public String getName()
Obtain the nickname, or label, of this token.
Specified by:
getName in interface CryptoToken

getProvider

public java.security.Provider getProvider()

getProxy

public TokenProxy getProxy()

getRandomGenerator

public java.security.SecureRandom getRandomGenerator()
            throws NotImplementedException,
                   TokenException

getSignatureContext

public Signature getSignatureContext(SignatureAlgorithm algorithm)
            throws NoSuchAlgorithmException,
                   TokenException

Deprecated. Use the JCA interface instead (java.security.Signature)

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.

initPassword

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

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:
Throws:
TokenException - If the PIN was already initialized, or there was an unspecified error in the token.

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.

isLoggedIn

public boolean isLoggedIn()
            throws TokenException
Find out if the token is currently logged in.
Specified by:
isLoggedIn in interface CryptoToken

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

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.

login

public void login(PasswordCallback callback)
            throws PK11Token.NotInitializedException,
                   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.

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.

makePWCBInfo

protected PasswordCallbackInfo makePWCBInfo()

nativeLogin

protected void nativeLogin(PasswordCallback callback)
            throws PK11Token.NotInitializedException,
                   IncorrectPasswordException,
                   TokenException

needsLogin

public boolean needsLogin()
            throws TokenException
returns true if this token needs to be logged into before it can be used.
Specified by:
needsLogin in interface CryptoToken

passwordIsInitialized

public boolean passwordIsInitialized()
            throws TokenException
Determine whether the token has been initialized yet.
Specified by:
passwordIsInitialized in interface CryptoToken

setLoginMode

public void setLoginMode(int mode)
            throws TokenException
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.

setLoginTimeoutMinutes

public void setLoginTimeoutMinutes(int timeoutMinutes)
            throws TokenException
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.

userPasswordIsCorrect

protected boolean userPasswordIsCorrect(byte[] pw)
            throws TokenException
Check the given password, return true if it's right, false if it's wrong.