de.cardcontact.opencard.service.isocard
Class IsoCardService

java.lang.Object
  opencard.core.service.CardService
      de.cardcontact.opencard.service.isocard.IsoCardService

All Implemented Interfaces:

CHVCardServiceWithControl, IsoFileSystemCardService, FileAccessCardService, FileSystemCardService, CHVCardService, SecureService, CardServiceInterface

Direct Known Subclasses:

ACOSCardService

public class IsoCardService
extends CardService
implements FileAccessCardService, IsoFileSystemCardService, CHVCardServiceWithControl, SecureService

File access card service for ISO7816-4,-8 and -9 cards. First implemented and tested with ORGA Micardo 2.x operating systems

Author:

Andreas Schwier

Field Summary

Fields inherited from interface opencard.opt.iso.fs.FileAccessCardService

READ_SEVERAL

Constructor Summary

IsoCardService()

Method Summary

void	appendRecord(CardFilePath file, byte[] data) Append record to linear file
void	closeApplication(SecurityDomain domain) Resets the achieved card holder verifications on the smartcard.
void	create(CardFilePath parent, byte[] data) Create file in parent usind file information supplied as byte array This is the original signature defined by OCF
void	create(CardFilePath parent, byte fileDescriptorByte, byte shortFileIdentifier, byte[] data) Create file in parent usind file information supplied as byte array This is the signature defined by OpenSCPD
void	delete(CardFilePath file) Delete the file referenced This is the original signature defined by OCF
void	delete(CardFilePath file, CardFilePathComponent child, boolean childIsDF) Delete the referenced file This is the signature defined by OpenSCDP
boolean	exists(CardFilePath file) Determine if file exists
CardFileInfo	getFileInfo(CardFilePath file) Obtain file information as returned in the SELECT command
int	getPasswordLength(SecurityDomain domain, int number) Determines the padded length of a password.
CardFilePath	getRoot() Return the root path (:3F00) of this card service
protected SecureChannelCredential	getSecureChannelCredential(CardFilePath file, int accessMode) Obtain a secure channel credential, if any is defined for the given file and access mode
void	initialize(CardServiceScheduler scheduler, SmartCard smartcard, boolean blocking) Create the IsoCardSelector object in the card channel if it does not yet exist.
void	invalidate(CardFilePath file) Invalidate (Deactivate) the file specified
void	provideCredentials(SecurityDomain domain, CredentialBag creds) Provides credentials to a card service.
byte[]	read(CardFilePath file, int offset, int length) Read binary data from transparent file
byte[]	readRecord(CardFilePath file, int recordNumber) Read record from linear file
byte[][]	readRecords(CardFilePath file, int number) Reads consecutive records from a structured file.
void	rehabilitate(CardFilePath file) Rehabilitate (Activate) the file specified
protected ResponseAPDU	sendCommandAPDU(CardChannel channel, SecureChannelCredential secureChannelCredential, CommandAPDU com) Exchange APDU with card, optionally transforming the APDU with a secure channel
protected ResponseAPDU	sendCommandAPDU(CardChannel channel, SecureChannelCredential secureChannelCredential, int uq, CommandAPDU com) Exchange APDU with card, optionally transforming the APDU with a secure channel
ResponseAPDU	sendCommandAPDU(CardFilePath path, CommandAPDU com, int usageQualifier) Send APDU making sure that the object referenced by path is selected
boolean	verifyPassword(SecurityDomain domain, int number, byte[] password) Checks a password for card holder verification.
boolean	verifyPassword(SecurityDomain domain, int number, CHVControl cc, byte[] password) Checks a password for card holder verification.
void	write(CardFilePath file, int offset, byte[] data) Write binary data to transparent file
void	write(CardFilePath file, int foffset, byte[] source, int soffset, int length) Write binary data to transparent file
void	writeRecord(CardFilePath file, int recordNumber, byte[] data) Update record in linear file

Methods inherited from class opencard.core.service.CardService

allocateCardChannel, getCard, getCardChannel, getCHVDialog, releaseCardChannel, setCardChannel, setCHVDialog

Methods inherited from class java.lang.Object

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

Methods inherited from interface opencard.opt.service.CardServiceInterface

getCard, setCHVDialog

Constructor Detail

IsoCardService

public IsoCardService()

Method Detail

initialize

public void initialize(CardServiceScheduler scheduler,
                       SmartCard smartcard,
                       boolean blocking)
                throws CardServiceException

Create the IsoCardSelector object in the card channel if it does not yet exist. Overwrites #opencard.core.service.CardService#initialize

Overrides:

initialize in class CardService

Parameters:

scheduler - where this service is going to allocate channels

smartcard - which smartcard has to be supported by this service

blocking - whether channel allocation is going to be blocking

Throws:

CardServiceException - if the service could not be initialized. The object created via the default constructor may not be used if this happens.

See Also:

CardServiceFactory

exists

public boolean exists(CardFilePath file)
               throws CardServiceException,
                      CardTerminalException

Determine if file exists

Specified by:

exists in interface FileAccessCardService

Parameters:

file - the path to the file to query

Returns:

true if the file exists, false otherwise

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.exists(opencard.opt.iso.fs.CardFilePath)

getFileInfo

public CardFileInfo getFileInfo(CardFilePath file)
                         throws CardServiceException,
                                CardTerminalException

Obtain file information as returned in the SELECT command

Specified by:

getFileInfo in interface FileAccessCardService

Parameters:

file - the path to the file to query

Returns:

information about the file, or null if it doesn't exist

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.getFileInfo(opencard.opt.iso.fs.CardFilePath)

getRoot

public CardFilePath getRoot()

Return the root path (:3F00) of this card service

Specified by:

getRoot in interface FileAccessCardService

Returns:

the path to the master file

See Also:

FileAccessCardService.getRoot()

getSecureChannelCredential

protected SecureChannelCredential getSecureChannelCredential(CardFilePath file,
                                                             int accessMode)

Obtain a secure channel credential, if any is defined for the given file and access mode

Parameters:

file - File for which a secure channel credential should be obtained

accessMode - Desired mode of access (READ, UPDATE or APPEND)

Returns:

null or SecureChannelCredential object

sendCommandAPDU

protected ResponseAPDU sendCommandAPDU(CardChannel channel,
                                       SecureChannelCredential secureChannelCredential,
                                       int uq,
                                       CommandAPDU com)
                                throws InvalidCardChannelException,
                                       CardTerminalException

Exchange APDU with card, optionally transforming the APDU with a secure channel

Parameters:

channel -

secureChannelCredential -

uq - usage Qualifier

com -

Returns:

the response APDU

Throws:

InvalidCardChannelException

CardTerminalException

sendCommandAPDU

protected ResponseAPDU sendCommandAPDU(CardChannel channel,
                                       SecureChannelCredential secureChannelCredential,
                                       CommandAPDU com)
                                throws InvalidCardChannelException,
                                       CardTerminalException

Exchange APDU with card, optionally transforming the APDU with a secure channel

Parameters:

channel -

secureChannelCredential -

com -

Returns:

the response APDU

Throws:

InvalidCardChannelException

CardTerminalException

read

public byte[] read(CardFilePath file,
                   int offset,
                   int length)
            throws CardServiceException,
                   CardTerminalException

Read binary data from transparent file

Specified by:

read in interface FileAccessCardService

Parameters:

file - the path to the file to read from

offset - the index of the first byte to read (0 for first)

length - the number of bytes to read, or READ_SEVERAL. If 0 is passed, the behavior is implementation dependent.

Returns:

an array holding the data read from the file, or null if a read with length READ_SEVERAL has been performed at the end of the file

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.read(opencard.opt.iso.fs.CardFilePath, int, int)

readRecord

public byte[] readRecord(CardFilePath file,
                         int recordNumber)
                  throws CardServiceException,
                         CardTerminalException

Read record from linear file

Specified by:

readRecord in interface FileAccessCardService

Parameters:

file - the path to the file to read from

recordNumber - the index of the record to read (0 for first)

Returns:

an array holding the record read. If the record has length 0, which may happen with linear variable files, an array of length 0 is returned.

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.readRecord(opencard.opt.iso.fs.CardFilePath, int)

readRecords

public byte[][] readRecords(CardFilePath file,
                            int number)
                     throws CardServiceException,
                            CardTerminalException

Description copied from interface: FileAccessCardService

Reads consecutive records from a structured file. For a discussion of structured file types, see readRecord. The first record read will always be the first in the structured file. For linear files with fixed or variable record size, first is interpreted as an absolute record number. For cyclic files, first refers to the record most recently written. Starting with that first record, the specified number of consecutive records will be read. In the case of a cyclic file, the second record will be the second most recently written record, and so on.
Typically, smartcards will implement absolute addressing for cyclic files, where the first record is the least recently written, and the following are sorted by decreasing time of writing. In this case, this method can be implemented by repeated invocations of readRecord.
The magic number READ_SEVERAL may be passed as the number of records to read. In this case, all records in the file are read. This is especially useful with linear variable files, where the number of records in the file cannot be determined via file attributes.

Specified by:

readRecords in interface FileAccessCardService

Parameters:

file - the path to the file to read from

number - the number of records to read, or READ_SEVERAL. If 0 is passed, the behavior is implementation dependent.

Returns:

an array holding the records read, where the records are arrays themselves

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.readRecord(opencard.opt.iso.fs.CardFilePath, int), FileAccessCardService.READ_SEVERAL

write

public void write(CardFilePath file,
                  int foffset,
                  byte[] source,
                  int soffset,
                  int length)
           throws CardServiceException,
                  CardTerminalException

Write binary data to transparent file

Specified by:

write in interface FileAccessCardService

Parameters:

file - the path to the file to write to

foffset - the file index of the first byte to overwrite (0 for first byte in file)

source - an array holding the data to write

soffset - the array index of the first byte to write

length - the number of bytes to write

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.write(opencard.opt.iso.fs.CardFilePath, int, byte[], int, int)

write

public void write(CardFilePath file,
                  int offset,
                  byte[] data)
           throws CardServiceException,
                  CardTerminalException

Write binary data to transparent file

Specified by:

write in interface FileAccessCardService

Parameters:

file - the path to the file to write to

offset - the file index of the first byte to overwrite (0 for first byte in file)

data - the data to write to the file

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.write(opencard.opt.iso.fs.CardFilePath, int, byte[])

writeRecord

public void writeRecord(CardFilePath file,
                        int recordNumber,
                        byte[] data)
                 throws CardServiceException,
                        CardTerminalException

Update record in linear file

Specified by:

writeRecord in interface FileAccessCardService

Parameters:

file - the path to the file to write to

recordNumber - the index of the record to overwrite (0 for first)

data - the data to write to the file

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.writeRecord(opencard.opt.iso.fs.CardFilePath, int, byte[])

appendRecord

public void appendRecord(CardFilePath file,
                         byte[] data)
                  throws CardServiceException,
                         CardTerminalException

Append record to linear file

Specified by:

appendRecord in interface FileAccessCardService

Parameters:

file - the path to the file to append to

data - the data to write to the new record

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.appendRecord(opencard.opt.iso.fs.CardFilePath, byte[])

sendCommandAPDU

public ResponseAPDU sendCommandAPDU(CardFilePath path,
                                    CommandAPDU com,
                                    int usageQualifier)
                             throws CardServiceException,
                                    CardTerminalException

Send APDU making sure that the object referenced by path is selected

Parameters:

path -

com -

usageQualifier -

Returns:

Response APDU

Throws:

CardServiceException

CardTerminalException

provideCredentials

public void provideCredentials(SecurityDomain domain,
                               CredentialBag creds)
                        throws CardServiceException

Description copied from interface: SecureService

Provides credentials to a card service. The security domain should be specified as the path to the directory in which the application's card resident parts are located. The bag of credentials should hold a credential store suitable for the respective card and card service implementation. Only credentials in that store will (and can) be used by the service.

Specified by:

provideCredentials in interface SecureService

Parameters:

domain - the security domain for which to provide credentials

creds - the credentials for that domain

Throws:

CardServiceException - If the card service could not process the credentials, if the SecurityDomain is invalid.

See Also:

CardService

getPasswordLength

public int getPasswordLength(SecurityDomain domain,
                             int number)
                      throws CardServiceException,
                             CardTerminalException

Description copied from interface: CHVCardService

Determines the padded length of a password. The returned value is required to pad passwords for verification.

Specified by:

getPasswordLength in interface CHVCardService

Parameters:

domain - The security domain in which the password resides. null can be passed to refer to the root domain on the smartcard.
For file system based smartcards, the security domain is specified as a CardFilePath. The root domain then corresponds to the master file.

number - The number of the password. This parameter is used to distinguish between different passwords in the same security domain.

Returns:

the number of data bytes for the specified password

Throws:

CardServiceException - if this service encountered an error. This may occur if the service needs to contact the smartcard in order to determine the password length. An exception may also be thrown if the service is unable to locate the security domain.

CardTerminalException - if the underlying card terminal encountered an error when communicating with the smartcard

verifyPassword

public boolean verifyPassword(SecurityDomain domain,
                              int number,
                              CHVControl cc,
                              byte[] password)
                       throws CardServiceException,
                              CardTerminalException

Description copied from interface: CHVCardServiceWithControl

Checks a password for card holder verification. Note that repeated verification of a wrong password will typically block that password on the smartcard.

Specified by:

verifyPassword in interface CHVCardServiceWithControl

Parameters:

domain - The security domain in which to verify the password. null can be passed to refer to the root domain on the smartcard.
For file system based smartcards, the security domain is specified as a CardFilePath. The root domain then corresponds to the master file.

number - The number of the password to verify. This parameter is used to distinguish between different passwords in the same security domain.

cc - Control parameter defined by the application

password - The password data that has to be verified. If the data is supplied, it has to be padded to the length returned by getPasswordLength for that password.
null may be passed to indicate that this service should use a protected PIN path facility, if available. Alternatively, this service may query the password by some other, implementation-dependend means. In any case, the service implementation will require knowledge about the encoding of the password data on the smartcard.

Throws:

CardServiceException - if this service encountered an error. In this context, it is not considered an error if the password to be verified is wrong. However, if the password is blocked on the smartcard, an exception will be thrown.

CardTerminalException - if the underlying card terminal encountered an error when communicating with the smartcard

verifyPassword

public boolean verifyPassword(SecurityDomain domain,
                              int number,
                              byte[] password)
                       throws CardServiceException,
                              CardTerminalException

Description copied from interface: CHVCardService

Checks a password for card holder verification. Note that repeated verification of a wrong password will typically block that password on the smartcard.

Specified by:

verifyPassword in interface CHVCardService

Parameters:

domain - The security domain in which to verify the password. null can be passed to refer to the root domain on the smartcard.
For file system based smartcards, the security domain is specified as a CardFilePath. The root domain then corresponds to the master file.

number - The number of the password to verify. This parameter is used to distinguish between different passwords in the same security domain.

password - The password data that has to be verified. If the data is supplied, it has to be padded to the length returned by getPasswordLength for that password.
null may be passed to indicate that this service should use a protected PIN path facility, if available. Alternatively, this service may query the password by some other, implementation-dependend means. In any case, the service implementation will require knowledge about the encoding of the password data on the smartcard.

Throws:

CardServiceException - if this service encountered an error. In this context, it is not considered an error if the password to be verified is wrong. However, if the password is blocked on the smartcard, an exception will be thrown.

CardTerminalException - if the underlying card terminal encountered an error when communicating with the smartcard

closeApplication

public void closeApplication(SecurityDomain domain)
                      throws CardServiceException,
                             CardTerminalException

Description copied from interface: CHVCardService

Resets the achieved card holder verifications on the smartcard. Typically, other permanent access conditions that have been satisfied will also be reset. If the card does not allow to reset access conditions for a specific application, it is expected that all access conditions for all on-card applications are reset.

The name of this method implies that an application on the smartcard is first selected and then opened by performing card holder verification, giving access to the application data. By resetting the card holder verification, the on-card application therefore gets closed.

Specified by:

closeApplication in interface CHVCardService

Parameters:

domain - the security domain for which to reset card holder verifications

Throws:

CardServiceException - if this service, or the underlying implementation, encountered an error

CardTerminalException - if the underlying terminal encountered an error while communicating with the smartcard

create

public void create(CardFilePath parent,
                   byte[] data)
            throws CardServiceException,
                   CardTerminalException

Create file in parent usind file information supplied as byte array This is the original signature defined by OCF

Specified by:

create in interface FileSystemCardService

Parameters:

parent - the path to the directory in which to create a new file

data - the parameters specifying the file to create. This argument is card-specific. Refer to the documentation of the card-specific service for details.

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileAccessCardService.getFileInfo(opencard.opt.iso.fs.CardFilePath), CardFileInfo.getHeader(), CardID, SmartCard.getCardID()

create

public void create(CardFilePath parent,
                   byte fileDescriptorByte,
                   byte shortFileIdentifier,
                   byte[] data)
            throws CardServiceException,
                   CardTerminalException

Create file in parent usind file information supplied as byte array This is the signature defined by OpenSCPD

Specified by:

create in interface IsoFileSystemCardService

Parameters:

parent - the path to the directory in which to create a new file

fileDescriptorByte - File descriptor byte according to ISO 7816-4

shortFileIdentifier - Short file identifer coded on bit b8 - b4

data - the parameters specifying the file to create. This argument is card-specific. Refer to the documentation of the card-specific service for details.

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

See Also:

FileSystemCardService, FileAccessCardService.getFileInfo(opencard.opt.iso.fs.CardFilePath), CardFileInfo.getHeader(), CardID, SmartCard.getCardID()

delete

public void delete(CardFilePath file)
            throws CardServiceException,
                   CardTerminalException

Delete the file referenced This is the original signature defined by OCF

Specified by:

delete in interface FileSystemCardService

Parameters:

file - the path to the file to delete

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

delete

public void delete(CardFilePath file,
                   CardFilePathComponent child,
                   boolean childIsDF)
            throws CardServiceException,
                   CardTerminalException

Delete the referenced file This is the signature defined by OpenSCDP

Specified by:

delete in interface IsoFileSystemCardService

Parameters:

file - the path to the file to delete

child - File identifier of child object (either EF, DF or application)

childIsDF - True, if the child is a dedicated file

Throws:

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

invalidate

public void invalidate(CardFilePath file)
                throws CardServiceInabilityException,
                       CardServiceException,
                       CardTerminalException

Invalidate (Deactivate) the file specified

Specified by:

invalidate in interface FileSystemCardService

Parameters:

file - the path to the file to invalidate

Throws:

CardServiceInabilityException - if the service does not support this operation

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error

rehabilitate

public void rehabilitate(CardFilePath file)
                  throws CardServiceInabilityException,
                         CardServiceException,
                         CardTerminalException

Rehabilitate (Activate) the file specified

Specified by:

rehabilitate in interface FileSystemCardService

Parameters:

file - the path to the file to rehabilitate

Throws:

CardServiceInabilityException - if the service does not support this operation

CardServiceException - if the service encountered an error

CardTerminalException - if the terminal encountered an error