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

## opencard.opt.security
Interface CHVCardService

public abstract interface CHVCardService
extends CardServiceInterface

A card service interface for Card Holder Verification (CHV). CHV is typically performed by querying a password or PIN (Personal Identification Number) from the user and presenting it to the card for verification. The user's input has to be converted into the format understood by the smartcard, for example by BCD-packing and padding a PIN. The methods in this interface expect this converted data, which is referred to as password. Please note that there is no assumption on how the password data is obtained and preprocessed. For example, biometric scanning could be used instead of querying a PIN.

Method Summary
`void` | `closeApplication(SecurityDomain domain)` Resets the achieved card holder verifications on the smartcard.
`int` | `getPasswordLength(SecurityDomain domain, int number)` Determines the padded length of a password.
`boolean` | `verifyPassword(SecurityDomain domain, int number, byte[] password)` Checks a password for card holder verification.

Methods inherited from interface opencard.opt.service.CardServiceInterface
`getCard, setCHVDialog`

Method Detail

### getPasswordLength

    public int getPasswordLength(SecurityDomain domain,
                                 int number)
                          throws opencard.core.service.CardServiceException,
                                 opencard.core.terminal.CardTerminalException

  Determines the padded length of a password. The returned value is required to pad passwords for verification.
  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:
    opencard.core.service.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.
    opencard.core.terminal.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 opencard.core.service.CardServiceException,
                                  opencard.core.terminal.CardTerminalException

  Checks a password for card holder verification. Note that repeated verification of a wrong password will typically block that password on the smartcard.
  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:
    opencard.core.service.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.
    opencard.core.terminal.CardTerminalException - if the underlying card terminal encountered an error when communicating with the smartcard

### closeApplication

    public void closeApplication(SecurityDomain domain)
                          throws opencard.core.service.CardServiceException,
                                 opencard.core.terminal.CardTerminalException

  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.

  Parameters:
    `domain` - the security domain for which to reset card holder verifications
  Throws:
    opencard.core.service.CardServiceException - if this service, or the underlying implementation, encountered an error
    opencard.core.terminal.CardTerminalException - if the underlying terminal encountered an error while communicating with the smartcard

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