org.dvb.security.pkcs11

Class DVBPKCS11Provider

java.lang.Object

java.util.Dictionary

java.util.Hashtable

java.util.Properties

java.security.Provider

org.dvb.security.AuthProvider

org.dvb.security.pkcs11.DVBPKCS11Provider

All Implemented Interfaces:

Serializable, Cloneable, Map

public abstract class DVBPKCS11Provider
extends AuthProvider

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

• In java.security for MessageDigest, SecureRandom, Signature, KeyPairGenerator and KeyStore related classes.
• In javax.crypto (JCE) for encryption and decryption.

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

Provider.Service

Field Summary

Fields inherited from class java.util.Properties

defaults

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	DVBPKCS11Provider(String name, double version, String info, AppID appID) Creates a new instance of DVBPKCS11Provider

Method Summary

Methods

Modifier and Type	Method and Description
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(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, elements, entrySet, get, getInfo, getName, getProperty, getService, getServices, getVersion, keys, keySet, load, put, putAll, putService, remove, removeService, toString, values

Methods inherited from class java.util.Properties

getProperty, list, list, load, loadFromXML, propertyNames, save, setProperty, store, store, storeToXML, storeToXML, stringPropertyNames

Methods inherited from class java.util.Hashtable

clone, contains, containsKey, containsValue, equals, hashCode, isEmpty, rehash, size

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

DVBPKCS11Provider

protected DVBPKCS11Provider(String name,
                 double version,
                 String info,
                 AppID appID)
                     throws SecurityException

Creates a new instance of DVBPKCS11Provider

Throws:

SecurityException - when called with an appID not allowed by the DVBPKCS11 implementation

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 IOException,
                               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:

IOException - this exception is thrown if this method is called when the provider is logged into the token.

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 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:

IllegalArgumentException - if the slot does not exist or there is no token in the slot

login

public abstract void login(Principal identity,
         CallbackHandler handler)
                    throws LoginException,
                           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.

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.