Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## de.cardcontact.opencard.service.gemxcos
Class GemXCosCardService

    java.lang.Object
      opencard.core.service.CardService
          de.cardcontact.opencard.service.gemxcos.GemXCosCardService

All Implemented Interfaces:
  FileAccessCardService, FileSystemCardService, CHVCardService, SecureService, CardServiceInterface

    public class GemXCosCardService

extends CardService
implements FileAccessCardService, FileSystemCardService, CHVCardService

File access card service for Gemplus XCos cards.

Author:
  Frank Thater

Field Summary

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

Constructor Summary
`GemXCosCardService()`

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)` Creates a file on the smartcard.
`void` | `delete(CardFilePath file)` Deletes a file on the smartcard.
`protected ResponseAPDU` | `doSelect(CardChannel channel, CardFilePathComponent comp, boolean isDF, byte p1, byte p2, boolean sendLe)` Select a single path component
`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 void` | `initialize(CardServiceScheduler scheduler, SmartCard smartcard, boolean blocking)` Create the IsoCardState object in the card channel if it does not yet exist.
`void` | `invalidate(CardFilePath file)` Invalidates a file on the smartcard.
`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)` Reads a record from a structured file.
`byte[][]` | `readRecords(CardFilePath file, int number)` Reads consecutive records from a structured file.
`void` | `rehabilitate(CardFilePath file)` Rehabilitates a file on the smartcard.
`CardFileInfo` | `selectFile(CardChannel channel, CardFilePath path)` Select directory or file according to path.
`boolean` | `verifyPassword(SecurityDomain domain, int number, 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

### GemXCosCardService

    public GemXCosCardService()

Method Detail

### initialize

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

  Create the IsoCardState 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()`

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

  Description copied from interface: `FileAccessCardService`
  Reads a record from a structured file. Structured files consist of records. Each record is an array of bytes. Data is addressed only in terms of records, and records are always read completely. The record size will be determined by the card service. ISO 7816-4 specifies the following structured file types:

  linear fixed
    An array of records, with absolute addressing. All records have the same, fixed size.
  linear variable
    An array of records, with absolute addressing. Every record may have a different size.
  cyclic fixed
    A ring buffer of records, with relative addressing. All records have the same, fixed size. Cyclic files are typically used for keeping logs on transactions.

  Files with a cyclic structure may not be easily accessible with this method, since the absolute addressing may be interpreted in different ways by different cards. For example, the first record may be the record that is physically stored first on the card, or it may be the record that was last written into the ring buffer. The method `readRecords` is the preferred way to read cyclic files.

  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.readRecords(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[])`

### 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`

### doSelect

    protected ResponseAPDU doSelect(CardChannel channel,
                                    CardFilePathComponent comp,
                                    boolean isDF,
                                    byte p1,
                                    byte p2,
                                    boolean sendLe)
                             throws InvalidCardChannelException,
                                    CardTerminalException

  Select a single path component

  Parameters:
    `channel` - Card channel to use for SELECT command
    `comp` - Path component. null is parent file is to be selected
    `isDF` - true if the path component is known to be a DF
  Returns:
    Response APDU from SELECT command
  Throws:
    `InvalidCardChannelException`
    `CardTerminalException`

### selectFile

    public CardFileInfo selectFile(CardChannel channel,
                                   CardFilePath path)
                            throws InvalidCardChannelException,
                                   CardTerminalException,
                                   CardServiceObjectNotAvailableException,
                                   CardServiceUnexpectedStatusWordException

  Select directory or file according to path. This function observes the currently selected EF or DF as stored in the CardState object of the CardChannel.

  Parameters:
    `channel` - Card channel used to communicate with the card
    `path` - Path to file to be selected
  Returns:
    File control information returned in SELECT command or null if file was not selected
  Throws:
    `InvalidCardChannelException`
    `CardTerminalException`
    `CardServiceObjectNotAvailableException`
    `CardServiceUnexpectedStatusWordException`

### 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,
                                  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

  Description copied from interface: `FileSystemCardService`
  Creates a file on the smartcard. Creating files is a card-specific operation. While the ISO file types are specified, the access conditions that can be defined are not. When creating a file, the access conditions to the new file have to be given. The result is that no card-independent arguments to a `create` method can be specified.
  This method defines only a card-neutral signature by expecting a byte array as a parameter. The data to be stored in that byte array is card-specific. It is suggested, but not required, that a file header, as it is returned by `CardFileInfo.getHeader`, is accepted as that parameter block. A file header typically holds all information needed for creating a file, in a card-specific encoding. This information includes the file ID, structure, size, and the access conditions.

  This method is intended to be used in a scenario where new applications have to be downloaded on a smartcard. Typically, a server will be contacted to retrieve the information about the directories and files that have to be created. This server can be supplied with the card's ATR, which is encapsulated by class `CardID`. The server will then be able to send parameter blocks that are appropriate arguments for this method and the respective card.

  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()`

### delete

    public void delete(CardFilePath file)
                throws CardServiceException,
                       CardTerminalException

  Description copied from interface: `FileSystemCardService`
  Deletes a file on the smartcard. Deleting a file completely removes it from the smartcard. The associated resources on the card, that is the allocated memory, will be freed. It is not possible to restore the file. A new file with the same id as the deleted file may be created in the same directory (DF).

  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

### invalidate

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

  Description copied from interface: `FileSystemCardService`
  Invalidates a file on the smartcard. Invalidating a file makes it inaccessible, but leaves it on the card. The associated resources of the file are not freed. It is not possible to create a new file with the same id in the same directory (DF). It may be possible to reverse the invalidation by invoking `rehabilitate`.
  Since a card service may implement this interface to provide create and delete access only, a `CardServiceInabilityException` may be thrown if invalidation is not supported.

  This method should not be implemented by setting all access conditions of the file to NEVER. Files with access condition NEVER are often used for internal purposes, for example to hold keys or application specific executable code. Invalidating a file should make the card OS ignore the file's contents.

  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

  Description copied from interface: `FileSystemCardService`
  Rehabilitates a file on the smartcard. This is the inverse operation to the invalidation of a smartcard file. It restores the file to the state it had before invalidation. Since a card service may implement this interface to provide create and delete access only, a `CardServiceInabilityException` may be thrown if rehabilitation is not supported.

  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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD