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 AutCardService

public abstract 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

    public int getChallengeLength(KeyRef key)
                           throws opencard.core.service.CardServiceException,
                                  opencard.core.terminal.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:
    `keyref` - 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:
    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 challenge 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

### internalAuthenticate

    public byte[] internalAuthenticate(KeyRef keyref,
                                       byte[] challenge)
                                throws opencard.core.service.CardServiceException,
                                       opencard.core.terminal.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:
    opencard.core.service.CardServiceException - if this service encountered an error
    opencard.core.terminal.CardTerminalException - if the underlying card terminal encountered an error when communicating with the smartcard

### externalAuthenticate

    public boolean externalAuthenticate(KeyRef keyref,
                                        SignCredential credential)
                                 throws opencard.core.service.CardServiceException,
                                        opencard.core.terminal.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:
    opencard.core.service.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.
    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 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:
    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
  See Also:
    `CHVCardService.closeApplication(opencard.opt.security.SecurityDomain)`

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