You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.




org.mozilla.jss.pkcs11
Class PK11Token

java.lang.Object
  extended by org.mozilla.jss.pkcs11.PK11Token
All 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
protected PK11Token()
           
protected PK11Token(byte[] pointer, boolean internal, boolean keyStorage)
          Creates a new PK11Token.
 
Method Summary
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(java.lang.Object obj)
          Deep-comparison operator.
 java.lang.String generateCertRequest(java.lang.String subject, int keysize, java.lang.String keyType, byte[] P, byte[] Q, byte[] G)
          Generates a PKCS#10 certificate request including Begin/End brackets
protected  java.lang.String generatePK10(java.lang.String subject, int keysize, java.lang.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.
 java.lang.String getName()
          Obtain the nickname, or label, of this token.
 java.security.Provider getProvider()
           
 TokenProxy getProxy()
           
 java.security.SecureRandom getRandomGenerator()
           
 Signature getSignatureContext(SignatureAlgorithm algorithm)
          Creates a Signature object, which can perform signing and signature verification.
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 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, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

mIsInternalCryptoToken

protected boolean mIsInternalCryptoToken

mIsInternalKeyStorageToken

protected boolean mIsInternalKeyStorageToken

tokenProxy

protected TokenProxy tokenProxy

cryptoStore

protected PK11Store cryptoStore
Constructor Detail

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 Detail

getSignatureContext

public Signature getSignatureContext(SignatureAlgorithm algorithm)
                              throws java.security.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:
java.security.NoSuchAlgorithmException - If the given algorithm is not supported by this provider.
TokenException

getDigestContext

public JSSMessageDigest getDigestContext(DigestAlgorithm algorithm)
                                  throws java.security.NoSuchAlgorithmException,
                                         java.security.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:
java.security.NoSuchAlgorithmException - If this provider does not support the given algorithm.
java.security.DigestException

getCipherContext

public Cipher getCipherContext(EncryptionAlgorithm algorithm)
                        throws java.security.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:
java.security.NoSuchAlgorithmException - If this provider does not support the given algorithm.
TokenException

getKeyGenerator

public KeyGenerator getKeyGenerator(KeyGenAlgorithm algorithm)
                             throws java.security.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:
java.security.NoSuchAlgorithmException - If this token does not support the given algorithm.
TokenException

cloneKey

public SymmetricKey cloneKey(SymmetricKey key)
                      throws SymmetricKey.NotExtractableException,
                             java.security.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.
java.security.InvalidKeyException - If the owning token cannot process the key to be cloned.
TokenException

getKeyWrapper

public KeyWrapper getKeyWrapper(KeyWrapAlgorithm algorithm)
                         throws java.security.NoSuchAlgorithmException,
                                TokenException
Specified by:
getKeyWrapper in interface CryptoToken
Throws:
java.security.NoSuchAlgorithmException
TokenException

getRandomGenerator

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

getKeyPairGenerator

public KeyPairGenerator getKeyPairGenerator(KeyPairAlgorithm algorithm)
                                     throws java.security.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:
java.security.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()

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.
TokenException
See Also:
CryptoToken.setLoginMode(int), CryptoManager.setPasswordCallback(org.mozilla.jss.util.PasswordCallback)

nativeLogin

protected void nativeLogin(PasswordCallback callback)
                    throws PK11Token.NotInitializedException,
                           IncorrectPasswordException,
                           TokenException
Throws:
PK11Token.NotInitializedException
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:
ssopw - The security officer's current password.
userpw - The user's new password.
Throws:
IncorrectPinException - If the security officer PIN is incorrect.
TokenException - If the PIN was already initialized, or there was an unspecified error in the token.
IncorrectPasswordException - If the supplied security officer password is incorrect.
AlreadyInitializedException - If the token only allows one password initialization, and it has already occurred.

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:
oldPIN - The user's old PIN.
newPIN - The new PIN.
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 java.lang.String getName()
Description copied from interface: CryptoToken
Obtain the nickname, or label, of this token.

Specified by:
getName in interface CryptoToken

getProvider

public java.security.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(java.lang.Object obj)
Deep-comparison operator.

Specified by:
equals in interface CryptoToken
Overrides:
equals in class java.lang.Object
Returns:
true if these tokens point to the same underlying native token. false otherwise, or if compare is null.

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 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 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
Throws:
TokenException
java.security.InvalidParameterException
PQGParamGenException

generatePK10

protected java.lang.String generatePK10(java.lang.String subject,
                                        int keysize,
                                        java.lang.String keyType,
                                        byte[] P,
                                        byte[] Q,
                                        byte[] G)
                                 throws TokenException,
                                        java.security.InvalidParameterException
Throws:
TokenException
java.security.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.