org.mozilla.jss.crypto

Interface CryptoToken

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
static intEVERY_TIME
Need to provide a password before each crypto operation.
static intONE_TIME
Login once, never need to re-enter the password until you log out.
static intTIMEOUT
Need to re-login after a period of time.
Method Summary
abstract voidchangePassword(PasswordCallback oldpw, PasswordCallback newpw)
Change the password of this token.
SymmetricKeycloneKey(SymmetricKey key)
Clones a SymmetricKey from a different token onto this token.
booleandoesAlgorithm(Algorithm alg)
Determines whether this token supports the given algorithm.
booleanequals(Object object)
Deep comparison operation.
abstract StringgenerateCertRequest(String subject, int keysize, String keyType, byte[] P, byte[] Q, byte[] G)
Generates a b64 encoded PKCS10 blob used for making cert request.
abstract CiphergetCipherContext(EncryptionAlgorithm algorithm)
Creates a Cipher object, which can be used for encryption and decryption.
abstract CryptoStoregetCryptoStore()
Get the CryptoStore interface to this token's objects.
abstract JSSMessageDigestgetDigestContext(DigestAlgorithm algorithm)
Creates a Digest object.
abstract KeyGeneratorgetKeyGenerator(KeyGenAlgorithm algorithm)
Creates a KeyGenerator object, which can be used to generate symmetric encryption keys.
abstract KeyPairGeneratorgetKeyPairGenerator(KeyPairAlgorithm algorithm)
Creates a KeyPairGenerator object, which can be used to generate key pairs.
abstract KeyWrappergetKeyWrapper(KeyWrapAlgorithm algorithm)
abstract intgetLoginMode()
Returns the login mode of this token: ONE_TIME, TIMEOUT, or EVERY_TIME.
abstract intgetLoginTimeoutMinutes()
Returns the login timeout period.
abstract StringgetName()
Obtain the nickname, or label, of this token.
abstract SignaturegetSignatureContext(SignatureAlgorithm algorithm)
Creates a Signature object, which can perform signing and signature verification.
abstract voidinitPassword(PasswordCallback securityOfficerPW, PasswordCallback userPW)
Initialize the password of this token.
booleanisLoggedIn()
Find out if the token is currently logged in.
booleanisPresent()
Determines whether this token is currently present.
abstract voidlogin(PasswordCallback pwcb)
Login to the token.
abstract voidlogout()
Logout of the token.
booleanneedsLogin()
returns true if this token needs to be logged into before it can be used.
abstract booleanpasswordIsInitialized()
Determine whether the password has been initialized yet.
abstract voidsetLoginMode(int mode)
Sets the login mode of this token.
abstract voidsetLoginTimeoutMinutes(int timeoutMinutes)
Sets the timeout period for logging in.

Field Detail

EVERY_TIME

public static final int EVERY_TIME
Need to provide a password before each crypto operation.

ONE_TIME

public static final int ONE_TIME
Login once, never need to re-enter the password until you log out.

TIMEOUT

public static final int TIMEOUT
Need to re-login after a period of time.

See Also: CryptoToken

Method Detail

changePassword

public abstract void changePassword(PasswordCallback oldpw, PasswordCallback newpw)
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.

cloneKey

public SymmetricKey cloneKey(SymmetricKey key)

Deprecated: Use the JCA interface instead (javax.crypto.SecretKeyFactory)

Clones a SymmetricKey from a different token onto this token.

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.

doesAlgorithm

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

equals

public boolean equals(Object object)
Deep comparison operation. Use this, rather than ==, to determine whether two CryptoTokens are the same.

generateCertRequest

public abstract String generateCertRequest(String subject, int keysize, String keyType, byte[] P, byte[] Q, byte[] G)
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

getCipherContext

public abstract Cipher getCipherContext(EncryptionAlgorithm algorithm)

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.

Parameters: algorithm The algorithm used for encryption/decryption.

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

getCryptoStore

public abstract CryptoStore getCryptoStore()
Get the CryptoStore interface to this token's objects.

getDigestContext

public abstract JSSMessageDigest getDigestContext(DigestAlgorithm algorithm)

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

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.

getKeyGenerator

public abstract KeyGenerator getKeyGenerator(KeyGenAlgorithm algorithm)

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.

Parameters: algorithm The algorithm that the keys will be used with.

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

getKeyPairGenerator

public abstract KeyPairGenerator getKeyPairGenerator(KeyPairAlgorithm algorithm)

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.

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.

getKeyWrapper

public abstract KeyWrapper getKeyWrapper(KeyWrapAlgorithm algorithm)

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

getLoginMode

public abstract int getLoginMode()
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: CryptoToken

getLoginTimeoutMinutes

public abstract int getLoginTimeoutMinutes()
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: CryptoToken

getName

public abstract String getName()
Obtain the nickname, or label, of this token.

Throws: TokenException If an error occurs on the token.

getSignatureContext

public abstract Signature getSignatureContext(SignatureAlgorithm algorithm)

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.

Parameters: algorithm The algorithm used for the signing/verification.

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

initPassword

public abstract void initPassword(PasswordCallback securityOfficerPW, PasswordCallback userPW)
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.

isLoggedIn

public boolean isLoggedIn()
Find out if the token is currently logged in.

See Also: CryptoToken CryptoToken

isPresent

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

login

public abstract void login(PasswordCallback pwcb)
Login to the token. If a token is logged in, it will not trigger password callbacks.

Parameters: password The password for this token.

Throws: IncorrectPasswordException If the supplied password is incorrect.

See Also: CryptoToken CryptoManager

logout

public abstract void logout()
Logout of the token.

needsLogin

public boolean needsLogin()
returns true if this token needs to be logged into before it can be used.

See Also: CryptoToken CryptoToken

passwordIsInitialized

public abstract boolean passwordIsInitialized()
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.

setLoginMode

public abstract void setLoginMode(int mode)
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: CryptoToken CryptoToken

setLoginTimeoutMinutes

public abstract void setLoginTimeoutMinutes(int timeoutMinutes)
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: CryptoToken