org.jmrtd
Class PassportApduService

java.lang.Object
  net.sourceforge.scuba.smartcards.CardService
      org.jmrtd.PassportApduService

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

PassportService

public class PassportApduService
extends CardService

Low level card service for sending apdus to the passport. This service is not responsible for maintaining information about the state of the authentication or secure messaging protocols. It merely offers the basic functionality for sending passport specific apdus to the passport. Based on ICAO-TR-PKI. Defines the following commands:

• GET CHALLENGE
• EXTERNAL AUTHENTICATE
• INTERNAL AUTHENTICATE (using secure messaging)
• SELECT FILE (using secure messaging)
• READ BINARY (using secure messaging)

Version:

$Revision: 1246 $

Author:

Cees-Bart Breunesse (ceesb@cs.ru.nl), Martijn Oostdijk (martijn.oostdijk@gmail.com)

See Also:

Serialized Form

Field Summary

Fields inherited from class net.sourceforge.scuba.smartcards.CardService

listeners, SESSION_STARTED_STATE, SESSION_STOPPED_STATE, state

Constructor Summary

PassportApduService(CardService service)
Creates a new passport apdu sending service.

Method Summary

void	addAPDUListener(APDUListener l) Adds a listener.
void	close() Closes the session with the card.
protected CommandAPDU	createGetChallengeAPDU()
CommandAPDU	createReadBinaryAPDU(int offset, int le, boolean longRead)
boolean	isOpen() Whether this service is open.
void	open() Opens a session by connecting to the card and selecting the passport applet.
void	removeAPDUListener(APDUListener l) Removes the listener l, if present.
byte[]	sendGetChallenge() Sends a GET CHALLENGE command to the passport.
byte[]	sendGetChallenge(SecureMessagingWrapper wrapper) Sends a GET CHALLENGE command to the passport.
byte[]	sendInternalAuthenticate(SecureMessagingWrapper wrapper, byte[] rndIFD) Sends an INTERNAL AUTHENTICATE command to the passport.
void	sendMSEAT(SecureMessagingWrapper wrapper, byte[] data) The MSE AT APDU, see EAC 1.11 spec, Section B.2
void	sendMSEDST(SecureMessagingWrapper wrapper, byte[] data) The MSE DST APDU, see EAC 1.11 spec, Section B.2
void	sendMSEKAT(SecureMessagingWrapper wrapper, byte[] keyData, byte[] idData) The MSE KAT APDU, see EAC 1.11 spec, Section B.1
byte[]	sendMutualAuth(byte[] rndIFD, byte[] rndICC, byte[] kIFD, SecretKey kEnc, SecretKey kMac) Sends an EXTERNAL AUTHENTICATE command to the passport.
void	sendMutualAuthenticate(SecureMessagingWrapper wrapper, byte[] signature) Sends the EXTERNAL AUTHENTICATE commands for EAC terminal verification
void	sendPSOChainMode(SecureMessagingWrapper wrapper, byte[] certBodyData, byte[] certSignatureData)
void	sendPSOExtendedLengthMode(SecureMessagingWrapper wrapper, byte[] certBodyData, byte[] certSignatureData)
byte[]	sendReadBinary(SecureMessagingWrapper wrapper, int offset, int le, boolean longRead) Sends a READ BINARY command to the passport.
byte[]	sendReadBinary(short offset, int le) Sends a READ BINARY command to the passport.
int	sendSelectApplet(byte[] aid) Sends a SELECT APPLET command to the card.
void	sendSelectFile(SecureMessagingWrapper wrapper, short fid) Sends a SELECT FILE command to the passport.
void	setListenersState(boolean state)
void	setService(CardService service)
ResponseAPDU	transmit(CommandAPDU capdu) TO CLARIFY: If the card responds with a status word other than 0x9000, ie. an staus word indicating an error, this method does NOT throw a CardServiceException, but it returns this as error code as result.

Methods inherited from class net.sourceforge.scuba.smartcards.CardService

notifyExchangedAPDU

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PassportApduService

public PassportApduService(CardService service)
                    throws CardServiceException

Creates a new passport apdu sending service.

Parameters:

service - another service which will deal with sending the apdus to the card

Throws:

GeneralSecurityException - when the available JCE providers cannot provide the necessary cryptographic primitives:

• Cipher: "DESede/CBC/Nopadding"
• Mac: "ISO9797Alg3Mac"

CardServiceException

Method Detail

open

public void open()
          throws CardServiceException

Opens a session by connecting to the card and selecting the passport applet.

Specified by:

open in class CardService

Throws:

CardServiceException

isOpen

public boolean isOpen()

Whether this service is open.

Specified by:

isOpen in class CardService

Returns:

a boolean

setListenersState

public void setListenersState(boolean state)

Overrides:

setListenersState in class CardService

transmit

public ResponseAPDU transmit(CommandAPDU capdu)
                      throws CardServiceException

TO CLARIFY: If the card responds with a status word other than 0x9000, ie. an staus word indicating an error, this method does NOT throw a CardServiceException, but it returns this as error code as result. Right? This can cause confusion, as most other method DO translate any status words indicating errors into CardServiceExceptions.

Specified by:

transmit in class CardService

Parameters:

capdu - the command apdu to send.

Returns:

the response from the card, including the status word.

Throws:

CardServiceException - - if the card operation failed

close

public void close()

Description copied from class: CardService

Closes the session with the card. Disconnects from the card and reader. Notifies any interested apduListeners.

Specified by:

close in class CardService

setService

public void setService(CardService service)

addAPDUListener

public void addAPDUListener(APDUListener l)

Description copied from class: CardService

Adds a listener.

Overrides:

addAPDUListener in class CardService

Parameters:

l - the listener to add

removeAPDUListener

public void removeAPDUListener(APDUListener l)

Description copied from class: CardService

Removes the listener l, if present.

Overrides:

removeAPDUListener in class CardService

Parameters:

l - the listener to remove

createReadBinaryAPDU

public CommandAPDU createReadBinaryAPDU(int offset,
                                        int le,
                                        boolean longRead)

createGetChallengeAPDU

protected CommandAPDU createGetChallengeAPDU()

sendSelectApplet

public int sendSelectApplet(byte[] aid)
                     throws CardServiceException

Sends a SELECT APPLET command to the card.

Parameters:

aid - the applet to select

Returns:

status word

Throws:

CardServiceException

sendSelectFile

public void sendSelectFile(SecureMessagingWrapper wrapper,
                           short fid)
                    throws CardServiceException

Sends a SELECT FILE command to the passport. Secure messaging will be applied to the command and response apdu.

Parameters:

wrapper - the secure messaging wrapper to use

fid - the file to select

Throws:

CardServiceException

sendReadBinary

public byte[] sendReadBinary(short offset,
                             int le)
                      throws CardServiceException

Sends a READ BINARY command to the passport.

Parameters:

offset - offset into the file

le - the expected length of the file to read

Returns:

a byte array of length le with (the specified part of) the contents of the currently selected file

Throws:

CardServiceException

sendReadBinary

public byte[] sendReadBinary(SecureMessagingWrapper wrapper,
                             int offset,
                             int le,
                             boolean longRead)
                      throws CardServiceException

Sends a READ BINARY command to the passport. Secure messaging will be applied to the command and response apdu.

Parameters:

wrapper - the secure messaging wrapper to use

offset - offset into the file

le - the expected length of the file to read

longRead - whether it should be a long (INS=B1) read

Returns:

a byte array of length le with (the specified part of) the contents of the currently selected file

Throws:

CardServiceException

sendGetChallenge

public byte[] sendGetChallenge()
                        throws CardServiceException

Sends a GET CHALLENGE command to the passport.

Returns:

a byte array of length 8 containing the challenge

Throws:

CardServiceException

sendGetChallenge

public byte[] sendGetChallenge(SecureMessagingWrapper wrapper)
                        throws CardServiceException

Sends a GET CHALLENGE command to the passport.

Returns:

a byte array of length 8 containing the challenge

Throws:

CardServiceException

sendInternalAuthenticate

public byte[] sendInternalAuthenticate(SecureMessagingWrapper wrapper,
                                       byte[] rndIFD)
                                throws CardServiceException

Sends an INTERNAL AUTHENTICATE command to the passport.

Parameters:

wrapper - secure messaging wrapper

rndIFD - the challenge to send

Returns:

the response from the passport (status word removed)

Throws:

CardServiceException

sendMutualAuth

public byte[] sendMutualAuth(byte[] rndIFD,
                             byte[] rndICC,
                             byte[] kIFD,
                             SecretKey kEnc,
                             SecretKey kMac)
                      throws CardServiceException

Sends an EXTERNAL AUTHENTICATE command to the passport. The resulting byte array has length 32 and contains rndICC (first 8 bytes), rndIFD (next 8 bytes), their key material " kICC" (last 16 bytes).

Parameters:

rndIFD - our challenge

rndICC - their challenge

kIFD - our key material

kEnc - the static encryption key

kMac - the static mac key

Returns:

a byte array of length 32 containing the response that was sent by the passport, decrypted (using kEnc) and verified (using kMac)

Throws:

CardServiceException

sendMutualAuthenticate

public void sendMutualAuthenticate(SecureMessagingWrapper wrapper,
                                   byte[] signature)
                            throws CardServiceException

Sends the EXTERNAL AUTHENTICATE commands for EAC terminal verification

Parameters:

wrapper - secure messaging wrapper

signature - terminal signature

Throws:

CardServiceException - if the resulting status word different from 9000

sendMSEKAT

public void sendMSEKAT(SecureMessagingWrapper wrapper,
                       byte[] keyData,
                       byte[] idData)
                throws CardServiceException

The MSE KAT APDU, see EAC 1.11 spec, Section B.1

Parameters:

wrapper - secure messaging wrapper

keyData - key data object (tag 0x91)

idData - key id data object (tag 0x84), can be null

Throws:

CardServiceException - on error

sendMSEDST

public void sendMSEDST(SecureMessagingWrapper wrapper,
                       byte[] data)
                throws CardServiceException

The MSE DST APDU, see EAC 1.11 spec, Section B.2

Parameters:

wrapper - secure messaging wrapper

data - public key reference data object (tag 0x83)

Throws:

CardServiceException - on error

sendMSEAT

public void sendMSEAT(SecureMessagingWrapper wrapper,
                      byte[] data)
               throws CardServiceException

The MSE AT APDU, see EAC 1.11 spec, Section B.2

Parameters:

wrapper - secure messaging wrapper

data - public key reference data object (tag 0x83)

Throws:

CardServiceException - on error

sendPSOExtendedLengthMode

public void sendPSOExtendedLengthMode(SecureMessagingWrapper wrapper,
                                      byte[] certBodyData,
                                      byte[] certSignatureData)
                               throws CardServiceException

Throws:

CardServiceException

sendPSOChainMode

public void sendPSOChainMode(SecureMessagingWrapper wrapper,
                             byte[] certBodyData,
                             byte[] certSignatureData)
                      throws CardServiceException

Throws:

CardServiceException