org.dvb.security.pkcs11
Class DVBPKCS11Provider

java.lang.Object
  extended by java.util.Dictionary<K,V>
      extended by java.util.Hashtable<java.lang.Object,java.lang.Object>
          extended by java.util.Properties
              extended by java.security.Provider
                  extended by org.dvb.security.AuthProvider
                      extended by org.dvb.security.pkcs11.DVBPKCS11Provider
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.util.Map<java.lang.Object,java.lang.Object>

public abstract class DVBPKCS11Provider
extends AuthProvider

This class implements a PKCS11 security provider. It can be used in the following security related packages:

Providers have a slot identifier associated with them identifying each smart card reader slot. These are numbered starting from zero. For details, see the PKCS 11 specification.

See Also:
Serialized Form

Nested Class Summary
 
Nested classes/interfaces inherited from class java.security.Provider
java.security.Provider.Service
 
Method Summary
abstract  int getSlotId()
          This method returns the PKCS11 slot identifier currently associated with this provider.
 SlotInfo[] getSlotList(boolean tokenPresent)
          This method is used to get the list of PKCS11 Slot available for this provider.
abstract  TokenInfo getTokenInfo(int slotId)
          This method is used to retreive information about a PKCS11 token in a given slot.
abstract  void login(java.security.Principal identity, CallbackHandler handler)
          This method is used to explicitly log into a PKCS11 token.
abstract  void logout()
          This method is called to explicitly log out from a PKCS11 token.
abstract  void setCallbackHandler(CallbackHandler handler)
          This method is used to set a default callback handler for the provider.
abstract  void setSlotId(int slotId)
          This method can be used to change the slot identifier used by the provider.
 
Methods inherited from class java.security.Provider
clear, entrySet, getInfo, getName, getService, getServices, getVersion, keySet, load, put, putAll, remove, toString, values
 
Methods inherited from class java.util.Properties
getProperty, getProperty, list, list, loadFromXML, propertyNames, save, setProperty, store, storeToXML, storeToXML
 
Methods inherited from class java.util.Hashtable
clone, contains, containsKey, containsValue, elements, equals, get, hashCode, isEmpty, keys, size
 
Methods inherited from class java.lang.Object
getClass, notify, notifyAll, wait, wait, wait
 

Method Detail

getSlotId

public abstract int getSlotId()
This method returns the PKCS11 slot identifier currently associated with this provider. By default the slot identifier is defined by the property "dvb.security.pkcs11.defaultSlotId" It can be changed by calling setSlotId.

Returns:
a slot identifier.

setSlotId

public abstract void setSlotId(int slotId)
                        throws java.io.IOException,
                               java.lang.IllegalArgumentException
This method can be used to change the slot identifier used by the provider. The slot can only be changed when the provider is not logged into the token.

Parameters:
slotId - a slot identifier.
Throws:
java.io.IOException - this exception is thrown if this method is called when the provider is logged into the token.
java.lang.IllegalArgumentException - if the slot does not exist

getSlotList

public SlotInfo[] getSlotList(boolean tokenPresent)
This method is used to get the list of PKCS11 Slot available for this provider. It is equivalent to the PKCS11 C_GetSlotList function to get the list of slot and C_GetSlotInfo to retreive slot information.

Parameters:
tokenPresent - boolean indicating if the returned list includes only the slots with a token present or all slots.
Returns:
the list of slot.

getTokenInfo

public abstract TokenInfo getTokenInfo(int slotId)
                                throws java.lang.IllegalArgumentException
This method is used to retreive information about a PKCS11 token in a given slot. It is equivalent to the PKCS11 C_GetTokenInfo function to get this information.

Returns:
a TokenInfo object which gives a subset of the PKCS11 CK_TOKEN_INFO.
Throws:
java.lang.IllegalArgumentException - if the slot does not exist or there is no token in the slot

login

public abstract void login(java.security.Principal identity,
                           CallbackHandler handler)
                    throws LoginException,
                           java.lang.NullPointerException
This method is used to explicitly log into a PKCS11 token. A call to this method will be equivalent to a call to the PKCS11 function C_Login. The PKCS11 user type will always be CKU_USER.

Specified by:
login in class AuthProvider
Parameters:
identity - This parameter is not used. It is kept to be compatible with the J2SE 5.0
handler - This parameter is used to get the pin code needed to login. The callbackHandler will get a PasswordCallback in which it should put the pin code. This parameter may be null in which case the handler that was previously set by setCallbackHandler is used.
Throws:
LoginException - This exception is under the conditions when C_Login would return an error return an error.
java.lang.NullPointerException - if the CallbackHandler parameter is null and either no previous call to setCallbackHandler has occurred or the last call to that method set the handler to null.

logout

public abstract void logout()
                     throws LoginException
This method is called to explicitly log out from a PKCS11 token. A call to this method will be equivalent to a call to the PKCS11 funtion C_Logout.

Specified by:
logout in class AuthProvider
Throws:
LoginException - This exception is thrown under the conditions when C_Logout would return an error.

setCallbackHandler

public abstract void setCallbackHandler(CallbackHandler handler)
This method is used to set a default callback handler for the provider.

Specified by:
setCallbackHandler in class AuthProvider
Parameters:
handler - a Callback handler that will be used to get the pin code when the login method is called with a null handler.