com.ibm.opencard.service
Class MFCCardService
java.lang.Object
|
+--opencard.core.service.CardService
|
+--com.ibm.opencard.service.MFCCardService
- Direct Known Subclasses:
- MFCFileAccess, MFCScriptService, MFCSignatureService
- public abstract class MFCCardService
- extends CardService
- implements SecureService
The base class for all MFC card services.
It provides channel allocation and key information handling,
both not directly related to but required by card services.
The only card service actually provided in this class is the
select command, which is protected and will be used
by derived services. The rest defines the infrastructure for
card services.
The select command implemented by MFC smartcards is rather tricky.
The implementation of the select command in MFC35CardServiceImpl
makes some assumptions on the card layout. These are common sense
assumptions that should not affect existing or future layouts. They
are mentioned here anyway, to save the time of those people that like
to check the behaviour of programs under strange circumstances.
A file ID that has to be interpreted by the select command of an MFC
smartcard will be checked to be an EF or DF within the current DF, to
be the parent DF, or the current DF itself. The MFC card services
assume that the file ID of the parent DF, the current DF, and all EFs
and DFs within the current directory are distinct.
For MFC smartcards that support selection by application names, it is
further assumed that application names and the location of the respective
files are defined only in the MF. Subapplications are not supported.
- Version:
- $Id: MFCCardService.java,v 1.1 1999/12/02 16:06:07 damke Exp $
|
Field Summary |
protected int |
card_type
Type of card for which this service is customized |
|
Constructor Summary |
protected |
MFCCardService()
Creates a new MFC card service.
|
| Methods inherited from class java.lang.Object |
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait |
card_type
protected int card_type
- Type of card for which this service is customized
MFCCardService
protected MFCCardService()
- Creates a new MFC card service.
The service cannot be used immediately. The actual initialization
is triggered by an invocation of initialize.
initialize
protected void initialize(CardServiceScheduler scheduler,
SmartCard smartcard,
boolean blocking)
throws CardServiceException
- Does not initialize this service.
In the base class CardService, this method is provided as
an entry point for extended initializations. For MFC card services,
initialization is done in hierachically invoked methods named
initXXX, where XXX indicates the service class. The
initialization method for this class is initGeneric.
Every MFC card service class has to override this method. The
implementation creates a parameter object suitable for the derived
class and invokes the single-argument initialization method for
that class. That method will initialize the local class attributes
from the parameter and invoke the single-argument initialization
method for the base class.
Since this class is abstract, the initialization method here cannot
create an appropriate parameter object. Instead, it throws an
exception indicating that the developer of the derived service
made a programming error.
- Parameters:
scheduler - where to allocate channelssmartcard - which smartcard to contactblocking - whether operation shall be blocking- Throws:
- CardServiceException - if this method is invoked
- Overrides:
- initialize in class CardService
- See Also:
CardService,
CardService.initialize(opencard.core.service.CardServiceScheduler, opencard.core.service.SmartCard, boolean),
initGeneric(com.ibm.opencard.service.MFCCardServiceParameter)
initGeneric
protected final void initGeneric(MFCCardServiceParameter parameter)
throws CardServiceException
- Initializes this service from encapsulated parameters.
This method initializes the local attributes and invokes
initialize in the base class. It has to be invoked
by each MFC card service. The parameters are encapsulated
in an object of class MFCCardServiceParameter.
Derived services should derive their own parameter classes
from that to add more initialization arguments.
- Parameters:
parameter - an object encapsulating the parameters to this service- Throws:
- CardServiceException - if the initialization failed.
With the current implementation, this cannot happen.
- See Also:
MFCCardServiceParameter
setParentChannel
public final void setParentChannel(MFCCardChannel channel)
- Provides a channel to use, without setting the accessor.
This method is invoked by meta services, that is services that use
other services to do their job. A meta service will want to provide
a channel with the meta service's accessor. Unlike with the method
setCardChannel, the card service will not store it's own
accessor into the channel provided here. To unset the parent channel,
invoke this method with argument null.
This method may be used simultaneously with setCardChannel,
which is invoked by SmartCard.beginMutex and
SmartCard.endMutex. The channel provided here will take
precedence over the channel provided with setCardChannel.
Typically, the channels will be the same anyway, but a channel
provided via setCardChannel will be instrumented with the
service's own accessor.
Neither the use of setCardChannel nor the use of this method
relief a card service from using the allocation methods embracing
card accesses, as described in CardService. By convention,
this method is invoked only from outside the service it is invoked
on. This implies that no channel is currently explicitly allocated
by the service.
- See Also:
CardService.setCardChannel(opencard.core.service.CardChannel),
SmartCard.beginMutex(),
SmartCard.endMutex(),
allocateCardChannel(),
releaseCardChannel(),
CardService
getMFCChannel
protected final MFCCardChannel getMFCChannel()
- Returns the MFC channel to use.
This method usually returns the same channel as getCardChannel
in the base class, but the type of the channel is more specific, thus
saving downcasts.
- Returns:
- the card channel that has been allocated
- See Also:
CardService.getCardChannel()
setCHVDialog
public final void setCHVDialog(CHVDialog dialog)
- Sets an application-defined CHV dialog.
- Parameters:
dialog - the dialog to use for CHV input- Overrides:
- setCHVDialog in class CardService
getRoot
public final CardFilePath getRoot()
- Returns a path to the master file of the smartcard.
This method is required by the interface FileAccessCardService.
Since paths are considered to be object identifiers, not only file
identifiers, it is offered in this base class.
- Returns:
- a path to the root of the file system
- See Also:
FileAccessCardService.getRoot()
allocateCardChannel
protected final void allocateCardChannel()
throws InvalidCardChannelException
- Allocates a card channel.
After allocation, the accessor gets stored in the channel, unless the
channel was provided via setParentChannel. In this case, the
service providing the channel will have set the accessor to use.
CHV, authentication and secure messaging are therefore transparent
to this service or service implementation.
The transparency gets lost if the CardOS requires commands to be
sent without intervening commands. This is the case for some of
the signature commands of the MFC 4.0 and 4.21 smartcards.
- Overrides:
- allocateCardChannel in class CardService
- See Also:
releaseCardChannel(),
setParentChannel(com.ibm.opencard.service.MFCCardChannel),
MFCCardAccessor
releaseCardChannel
protected final void releaseCardChannel()
throws InvalidCardChannelException
- Releases the allocated card channel.
The accessor stored in the channel after allocation will be cleared,
unless the channel was provided via setParentChannel. In this
case, it has not been instrumented with this service's accessor.
Any way, the next service to use the channel will not be able to use
the credentials stored in this service's accessor.
If this method is invoked while no channel is allocated, it simply
returns. This behavior is required to put the release invocation in
the finally clause of a try statement. The allocation
could fail and throw an exception, which should not lead to another
exception being thrown in the finally block.
- Overrides:
- releaseCardChannel in class CardService
- See Also:
allocateCardChannel(),
setParentChannel(com.ibm.opencard.service.MFCCardChannel)
checkFileArg
protected final void checkFileArg(CardFilePath file)
- Checks whether the given path is null.
This method is used for parameter checking in derived services.
- Parameters:
file - the path to check for null- Throws:
- CardServiceInvalidParameterException - if the parameter is null
selectObject
protected final MFCCardObjectInfo selectObject(MFCCardChannel channel,
CardFilePath path,
boolean info)
throws CardServiceObjectNotAvailableException,
CardServiceUnexpectedResponseException,
CardTerminalException
- Selects an object on the smartcard.
This method is called by derived services. Unlike the typical
service methods in derived services, this method expects a channel
to be allocated and passed as argument. The third argument specifies
whether information about the selected object should be returned, or
whether the select can be done quietly. The smartcard's response is
interpreted using the MFCSelectResponseParser passed to the
constructor.
- Parameters:
channel - contact to the smartcardpath - target of the selectinfo - true if the object info is required- Returns:
- information about the selected object,
if info was true and nothing went wrong
- Throws:
- CardServiceObjectNotAvailableException - if the target could not be selected
- CardServiceUnexpectedResponseException - if the select response could not be interpreted
- CardTerminalException - if the terminal encountered an error
- See Also:
MFCSelectResponseParser
provideCredentials
public void provideCredentials(SecurityDomain domain,
CredentialBag credbag)
throws CardServiceInvalidParameterException
- Provides the credentials for a key domain.
MFC smartcards distinguish key domains, which are basically subtrees of
the file hierarchies. A key domain can therefore be identified by the
path to the root directory. Within a key domain, new keys can be defined
and keys of the enclosing domain can be redefined. Within a key domain,
the keys are identified by a unique key number.
The credential bag to be passed as the second argument must be prepared
by the application, so it holds all credentials required to perform the
commands the application will execute. The bag itself contains one or
more credential stores, which hold card-specific credentials in
card and card service specific representations.
The credentials for MFC card services must be implementations of
SignCredentials, or subinterfaces, and they must be stored in a
MFCCredentialStore, using integers as identifiers.
The relevant credential store will be extracted and evaluated during the
invocation of this method. If the contents of that store is modified,
this method must be invoked again to make those changes take effect.
- Specified by:
- provideCredentials in interface SecureService
- Parameters:
domain - The identifier of the key domain.
The MFCCardService requires a CardFilePath to be
provided as SecurityDomain.credbag - The collection of credentials for that domain- Throws:
- CardServiceInvalidParameterException - SecurityDomain must be a CardFilePath
- See Also:
SecurityDomain,
CardFilePath,
CredentialBag,
CredentialStore,
SignCredential,
SecureCredential,
MFCCredentialStore
|
