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