opencard.opt.security
Interface AutCardService

All Superinterfaces:
CardServiceInterface

public interface AutCardService
extends CardServiceInterface


Method Summary
 void closeApplication(SecurityDomain domain)
          Resets the achieved external authentications on the smartcard.
 boolean externalAuthenticate(KeyRef keyref, SignCredential credential)
          Performs an external authentication against the smartcard.
 int getChallengeLength(KeyRef key)
          Determines the required length of a challenge for internal authentication.
 byte[] internalAuthenticate(KeyRef keyref, byte[] challenge)
          Requests an internal authentication from the smartcard.
 
Methods inherited from interface opencard.opt.service.CardServiceInterface
getCard, setCHVDialog
 

Method Detail

getChallengeLength

int getChallengeLength(KeyRef key)
                       throws CardServiceException,
                              CardTerminalException
Determines the required length of a challenge for internal authentication. The terminal or host application can then prepare a random challenge of the given length to invoke internalAuthenticate.

Parameters:
key - a reference identifying the key to be used for internal authentication in a subsequent invocation
Returns:
the number of bytes in an appropriate random challenge. The card may be able to deal with other sizes of random challenges. For example, if a public key algorithm is used, the card may be able to pad shorter challenges to the required block length. The value returned here could the be the maximum length that a random challenge may have. For secret key algorithms, the value returned typically is the block size, and no other sizes are acceptable.
Throws:
CardServiceException - if this service encountered an error. This may occur if the service needs to contact the smartcard in order to determine the challenge 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

internalAuthenticate

byte[] internalAuthenticate(KeyRef keyref,
                            byte[] challenge)
                            throws CardServiceException,
                                   CardTerminalException
Requests an internal authentication from the smartcard. The smartcard will take the random challenge passed as argument, perform some operations involving a secret, and return the result of these operations. The terminal or host application can then check the result to verify that the secret used by the card is the expected one, thereby authenticating the card.

Parameters:
keyref - a reference identifying the key to be used for internal authentication
challenge - the random challenge to be used by the smartcard
Returns:
a byte array holding the result of the smartcard's operations. It is up to the application to verify that this result is the expected one. (You wouldn't want to trust a smartcard just because this method returned true, would you?)
Throws:
CardServiceException - if this service encountered an error
CardTerminalException - if the underlying card terminal encountered an error when communicating with the smartcard

externalAuthenticate

boolean externalAuthenticate(KeyRef keyref,
                             SignCredential credential)
                             throws CardServiceException,
                                    CardTerminalException
Performs an external authentication against the smartcard. The smartcard will provide a random challenge, which is signed using the credential passed as an argument. The result of this operation is sent back to the smartcard and verified there. If the credential provided by the terminal or host application is the one expected by the smartcard, the external authentication succeeds. Otherwise, it fails. Note that repeated failed attempts to authenticate may cause the smartcard to permanently block the key that is used to check the authentication.

Parameters:
keyref - a reference identifying the key to be used for external authentication
credential - the secret to be used to authenticate the application against the smartcard. The secret will be used only once, and before this method returns. The application may take actions to ensure that the secret cannot be used arbitrarily often, or after this method returned.
Returns:
true if the smartcard accepted the credential and therefore considers the outside world to be authenticated, false if the smartcard rejected to authenticate the outside world.
Throws:
CardServiceException - if this service encountered an error. In this context, it is not considered an error if the smartcard rejected the authentication. However, an exception will be thrown if the referred key on the smartcard is blocked so that authentication using this key becomes impossible.
CardTerminalException - if the underlying card terminal encountered an error when communicating with the smartcard

closeApplication

void closeApplication(SecurityDomain domain)
                      throws CardServiceException,
                             CardTerminalException
Resets the achieved external authentications 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 external authentication, giving access to the application data. By resetting the external authentication, the on-card application therefore gets closed.

External authentication as well as Card Holder Verification (CHV) can be required to satisfy access conditions that are imposed by the card. The operation expected to be performed when invoking this method is to reset the state in the smartcard so that these access conditions are no longer satisfied. This avoids that another terminal or host application accesses the smartcard's data without proving it's authorization first. The signature of the method here is the same as in the interface CHVCardService, since both are expected to do the same thing.

Parameters:
domain - the security domain for which to reset external authentications
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
See Also:
CHVCardService.closeApplication(opencard.opt.security.SecurityDomain)