iaik.pkcs.pkcs11.me
Class Token

java.lang.Object
  iaik.pkcs.pkcs11.me.Token

public class Token

extends java.lang.Object

An object of this class represents of token. This can be a smart card, a hardware security module (HSM), a software token or just a logical token. It depends on the underlying PKCS#11 module.

The application can get a token object from a Module object. Having a token, a typical workflow for signing looks like the following:

  Token token = ... // get it from a Module object
 
  // login user first to be able to see private key objects on the token
  char[] pin = ... // e.g. prompt the PIN from the user
  token.loginUser(pin);
 
  // get a key store view of the keys and certificates on the token
  KeyStore keyStore = token.getKeyStore();
  String alias = ... // select a key from the key store
  Key key = keyStore.getKey(alias); 
  // also get the DER encoded certificate for the key 
  byte[] certificate = keyStore.getCertificate(alias);
 
  // now create the signature value
  long algorithm = Signature.ALGORITHM_SHA1WithRSA;
  if (!token.supportsAlgorithm(algorithm, Token.HARDWARE_OR_SOFTWARE)) {
    ... // token does not support this signature algorithm
  }
  Signature signature = token.getSignature(algorithm);
  signature.initSign(key);
  byte[] dataToBeSigned = ... // assign data
  signature.update(dataToBeSigned);
  byte[] signatureValue = signature.sign();
 

If the token has a protected authentication path—e.g. a card reader with a secure PIN-pad—the method hashProtectedAuthenticationPath() will return true. In this case, the application can pass null as PIN to the loginUser(char[]) method, and the user can enter PIN on the PIN pad.

The application can use getLabel() and getSerialNumber() to identify a token.

See Also:

Module, KeyStore, Cipher, MessageDigest, SecureRandom, Signature

Field Summary

static int	HARDWARE This constant specifies that an algorithm must be implemented in hardware.
static int	HARDWARE_OR_SOFTWARE This constant specifies that an algorithm can be implemented in software or in hardware.
static int	SOFTWARE This constant specifies that an algorithm must be implemented in software.

Method Summary

void	clearCache() Closes all sessions and empties the session cache.
Cipher	getCipher(long algorithm) Get a cipher object which operates with this token.
KeyGenerator	getKeyGenerator(long algorithm) Get a key generator which generates keys on this token.
KeyPairGenerator	getKeyPairGenerator(long algorithm) Get a key-pair generator which generates key-pairs on this token.
KeyStore	getKeyStore() Get a key store representation of this token.
java.lang.String	getLabel() Get the label of this token.
MessageDigest	getMessageDigest(long algorithm) Get a message digest which operates with this token.
SecureRandom	getSecureRandom() Get a secure random which gets random data from this token.
java.lang.String	getSerialNumber() Get the serial number of this token.
Signature	getSignature(long algorithm) Get a signature which operates with this token.
boolean	hashProtectedAuthenticationPath() Checks if this token has a protected authentication path; for example a PIN-pad reader for entering a PIN.
void	init(char[] soPin, java.lang.String label) Initialize this token.
void	initPIN(char[] soPin, char[] newUserPin) Initialize the user PIN after a call to init(char[], String).
boolean	loginRequired() Check if this token requires a login for certain operations.
void	loginUser(char[] pin) Login the user with the PIN.
void	logout() Logout the user.
void	setUserPIN(char[] oldPin, char[] newPin) Set the user PIN to a new value.
boolean	supportsAlgorithm(long algorithm, int implementation) Check if the token supports a certain algorithm.
boolean	supportsSecureRandom() Check, if the token has a random generator.
boolean	userLoggedIn() Check if the user is currently logged in to this token.
boolean	userPinInitialized() Checks if the user PIN of this token has already been initialized.

Methods inherited from class java.lang.Object

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

Field Detail

SOFTWARE

public static final int SOFTWARE

This constant specifies that an algorithm must be implemented in software.

See Also:

Constant Field Values

HARDWARE

public static final int HARDWARE

This constant specifies that an algorithm must be implemented in hardware.

See Also:

Constant Field Values

HARDWARE_OR_SOFTWARE

public static final int HARDWARE_OR_SOFTWARE

This constant specifies that an algorithm can be implemented in software or in hardware.

See Also:

Constant Field Values

Method Detail

clearCache

public void clearCache()
                throws PKCS11RuntimeException

Closes all sessions and empties the session cache.

Throws:

PKCS11RuntimeException - If closing all sessions fails.

getCipher

public Cipher getCipher(long algorithm)
                 throws PKCS11Exception,
                        PKCS11RuntimeException

Get a cipher object which operates with this token.

Parameters:

algorithm - The algorithm code for the cipher; e.g. a constant starting with Cipher.ALGORITHM_.

Returns:

The cipher object.

Throws:

PKCS11Exception - If the token does not support the algorithm.

PKCS11RuntimeException - If creating the cipher object fails.

See Also:

supportsAlgorithm(long, int)

getKeyGenerator

public KeyGenerator getKeyGenerator(long algorithm)
                             throws PKCS11Exception,
                                    PKCS11RuntimeException

Get a key generator which generates keys on this token.

Parameters:

algorithm - The algorithm code for the key generator; e.g. a constant starting with KeyGenerator.ALGORITHM_.

Returns:

The key generator.

Throws:

PKCS11Exception - If the token does not support the algorithm.

PKCS11RuntimeException - If creating the key generator fails.

See Also:

supportsAlgorithm(long, int)

getKeyPairGenerator

public KeyPairGenerator getKeyPairGenerator(long algorithm)
                                     throws PKCS11Exception,
                                            PKCS11RuntimeException

Get a key-pair generator which generates key-pairs on this token.

Parameters:

algorithm - The algorithm code for the key-pair generator; e.g. a constant starting with KeyPairGenerator.ALGORITHM_.

Returns:

The key-pair generator.

Throws:

PKCS11Exception - If the token does not support the algorithm.

PKCS11RuntimeException - If creating the key-pair generator fails.

See Also:

supportsAlgorithm(long, int)

getKeyStore

public KeyStore getKeyStore()
                     throws PKCS11RuntimeException

Get a key store representation of this token.

Returns:

The key store object that contains keys and certificates.

Throws:

PKCS11RuntimeException - If creating the key store fails.

getLabel

public java.lang.String getLabel()
                          throws PKCS11RuntimeException

Get the label of this token.

Returns:

The label of the token.

Throws:

PKCS11RuntimeException - If getting the token info fails

getMessageDigest

public MessageDigest getMessageDigest(long algorithm)
                               throws PKCS11Exception,
                                      PKCS11RuntimeException

Get a message digest which operates with this token.

Parameters:

algorithm - The algorithm code for the message digest; e.g. a constant starting with MessageDigest.ALGORITHM_.

Returns:

The message digest.

Throws:

PKCS11Exception - If the token does not support the algorithm.

PKCS11RuntimeException - If creating the message digest fails.

See Also:

supportsAlgorithm(long, int)

getSerialNumber

public java.lang.String getSerialNumber()
                                 throws PKCS11RuntimeException

Get the serial number of this token. This is a string consisting of 16 characters. It may be padded with blanks at the end.

Returns:

The serial number of the token.

Throws:

PKCS11RuntimeException - If getting the token info fails

getSecureRandom

public SecureRandom getSecureRandom()
                             throws PKCS11Exception,
                                    PKCS11RuntimeException

Get a secure random which gets random data from this token.

Returns:

The secure random.

Throws:

PKCS11Exception - If the token does not have a random generator.

PKCS11RuntimeException - If creating the secure random fails.

See Also:

supportsSecureRandom()

getSignature

public Signature getSignature(long algorithm)
                       throws PKCS11Exception,
                              PKCS11RuntimeException

Get a signature which operates with this token.

Parameters:

algorithm - The algorithm code for the signature; e.g. a constant starting with Signature.ALGORITHM_.

Returns:

The signature.

Throws:

PKCS11Exception - If the token does not support the algorithm.

PKCS11RuntimeException - If creating the signature fails.

See Also:

supportsAlgorithm(long, int)

hashProtectedAuthenticationPath

public boolean hashProtectedAuthenticationPath()
                                        throws PKCS11RuntimeException

Checks if this token has a protected authentication path; for example a PIN-pad reader for entering a PIN.
If this returns true, the PIN may be null for the methods that accept a PIN.

Returns:

true if it hash a protected authentication path.

Throws:

PKCS11RuntimeException - If getting the token info fails.

See Also:

init(char[], String), initPIN(char[], char[]), loginUser(char[])

init

public void init(char[] soPin,
                 java.lang.String label)
          throws PKCS11RuntimeException

Initialize this token. Note that this closes all sessions, deletes all objects on the token (including keys), set the token's label and sets the user PIN.

The user PIN may be uninitialized or set to a default value which depends on the underlying PKCS#11 module.

The soPin may be null, if the token hash a protected authentication path.

Parameters:

soPin - The security-officer PIN. Sometimes it is also called admin PIN or password, or as PUK.

label - The new label of the token.

Throws:

PKCS11RuntimeException - If initializing the token fails.

See Also:

hashProtectedAuthenticationPath(), initPIN(char[], char[])

initPIN

public void initPIN(char[] soPin,
                    char[] newUserPin)
             throws PKCS11RuntimeException

Initialize the user PIN after a call to init(char[], String). Note that this operations closes all sessions.

The soPin and the newUserPin may be null, if the token hash a protected authentication path.

To succeed, the application must verify that the user PIN has not been initialized before. See userPinInitialized().

Parameters:

soPin - The security-officer PIN. Sometimes it is also called admin PIN or password, or as PUK. Provide null to use an available protected authentication path.

newUserPin - The new user PIN. Provide null to use an available protected authentication path.

Throws:

PKCS11RuntimeException - If initializing the user PIN fails.

See Also:

hashProtectedAuthenticationPath(), init(char[], String), userPinInitialized()

loginRequired

public boolean loginRequired()
                      throws PKCS11RuntimeException

Check if this token requires a login for certain operations. Please refer to the specification of the CKF_LOGIN_REQUIRED flag in the PKCS#11 specification for further details.

Returns:

true if a login is required for certain operations.

Throws:

PKCS11RuntimeException - If getting the token info fails.

loginUser

public void loginUser(char[] pin)
               throws PKCS11RuntimeException

Login the user with the PIN. The pin may be null, if the token has a protected authentication path (see hashProtectedAuthenticationPath()).

Note that this logs in all sessions, because all sessions share the same login state.

Parameters:

pin - The user PIN or null.

Throws:

PKCS11RuntimeException - If the login fails.

See Also:

hashProtectedAuthenticationPath(), loginRequired(), logout()

logout

public void logout()
            throws PKCS11RuntimeException

Logout the user.

Note that this logs out all sessions, because all sessions share the same login state.

Throws:

PKCS11RuntimeException

See Also:

loginRequired(), loginUser(char[])

setUserPIN

public void setUserPIN(char[] oldPin,
                       char[] newPin)
                throws PKCS11RuntimeException

Set the user PIN to a new value. The provided PINs oldPin and newPin may be null if the token has a protected authentication path.

Note that the user PIN must have been initialized before. To set the initial user PIN after token initialization, please use initPIN(char[], char[]).

Parameters:

oldPin - The current user PIN or null.

newPin - The new user PIN or null.

Throws:

PKCS11RuntimeException - If setting the PIN to the new value fails.

See Also:

hashProtectedAuthenticationPath()

supportsAlgorithm

public boolean supportsAlgorithm(long algorithm,
                                 int implementation)
                          throws PKCS11RuntimeException

Check if the token supports a certain algorithm.

  if (token.supportsAlgorithm(Signature.ALGORITHM_SHA1WithRSA, Token.HARDWARE)) {
    ... // create signature value with the token
  }
 

The algorithm code can be any constant starting with ALGORITHM_ which are defined in the respective provider class; e.g. Signature.ALGORITHM_SHA1WithRSA, MessageDigest.ALGORITHM_SHA_1, KeyPairGenerator.ALGORITHM_RSA or Cipher.ALGORITHM_RSA_PKCS1PADDING.

The implementation parameter determines if a mechanism shall be reported as supported if it is implemented in hardware, in software, or if it does not matter. It is very common that token support algorithms which are not implemented on the token, but rather in software on the host. If this parameter is HARDWARE, the method will only return true if the token supports this algorithm and implements it in hardware. For SOFTWARE it is similar. If this parameter is HARDWARE_OR_SOFTWARE, this method will return true if this token implements the specified algorithm in hardware or in software.

Parameters:

algorithm - The algorithm code.

implementation - Specifies which types of implementations shall be considered:

• SOFTWARE
• HARDWARE
• HARDWARE_OR_SOFTWARE

Returns:

true if the token supports the algorithm.

Throws:

PKCS11RuntimeException - If getting the supported algorithms fails.

See Also:

supportsSecureRandom(), Signature.ALGORITHM_MD2WithRSA, MessageDigest.ALGORITHM_MD2, Cipher.ALGORITHM_RSA_OAEPPADDING, KeyPairGenerator.ALGORITHM_RSA, SOFTWARE, HARDWARE, HARDWARE_OR_SOFTWARE

supportsSecureRandom

public boolean supportsSecureRandom()
                             throws PKCS11RuntimeException

Check, if the token has a random generator. If this method returns true, the getSecureRandom() method will return a working random generator object.

Returns:

true if the token has a random generator.

Throws:

PKCS11RuntimeException - If getting the token info fails.

See Also:

getSecureRandom()

userLoggedIn

public boolean userLoggedIn()
                     throws PKCS11RuntimeException

Check if the user is currently logged in to this token.

Returns:

true if the user is logged in.

Throws:

PKCS11RuntimeException - If determining the login state fails.

userPinInitialized

public boolean userPinInitialized()
                           throws PKCS11RuntimeException

Checks if the user PIN of this token has already been initialized. This method can be used after a call to init(char[], String) to check if the user PIN has been set to a default value. If not, the application may initialize the user PIN with initPIN(char[], char[]);

Returns:

true if it hash a protected authentication path.

Throws:

PKCS11RuntimeException - If getting the token info fails.

See Also:

init(char[], String), initPIN(char[], char[]), loginUser(char[])