org.jmrtd

Class PassportApduService

java.lang.Object

net.sf.scuba.smartcards.CardService

org.jmrtd.PassportApduService

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

PassportService

public class PassportApduService
extends net.sf.scuba.smartcards.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: 1605 $

Author:

Cees-Bart Breunesse ([email protected]), Wojciech Mostowski ([email protected]), Martijn Oostdijk ([email protected])

See Also:

Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
protected static byte[]	APPLET_AID The applet we select when we start a session.
static byte	CAN_PACE_KEY_REFERENCE Shared secret type for PACE according to BSI TR-03110 v2.03 B.11.1.
static byte	MRZ_PACE_KEY_REFERENCE Shared secret type for PACE according to BSI TR-03110 v2.03 B.11.1.
static byte	PIN_PACE_KEY_REFERENCE Shared secret type for PACE according to BSI TR-03110 v2.03 B.11.1.
static byte	PUK_PACE_KEY_REFERENCE Shared secret type for PACE according to BSI TR-03110 v2.03 B.11.1.

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

SESSION_STARTED_STATE, SESSION_STOPPED_STATE, state

Constructor Summary

Constructors

Constructor and Description
PassportApduService(net.sf.scuba.smartcards.CardService service) Creates a new passport APDU sending service.

Method Summary

Modifier and Type	Method and Description
void	addAPDUListener(net.sf.scuba.smartcards.APDUListener l) Adds a listener.
void	addPlainTextAPDUListener(net.sf.scuba.smartcards.APDUListener l) Adds a plain text listener.
void	close() Closes the service.
byte[]	getATR() Gets the answer to reset bytes.
boolean	isOpen() Whether this service is open.
protected void	notifyExchangedPlainTextAPDU(int count, net.sf.scuba.smartcards.CommandAPDU capdu, net.sf.scuba.smartcards.ResponseAPDU rapdu) Notifies listeners about APDU event.
void	open() Opens a session by connecting to the card.
void	removeAPDUListener(net.sf.scuba.smartcards.APDUListener l) Removes a listener.
void	removePlainTextAPDUListener(net.sf.scuba.smartcards.APDUListener l) Removes a plain text listener.
byte[]	sendGeneralAuthenticate(net.sf.scuba.smartcards.APDUWrapper wrapper, byte[] data, boolean isLast) Sends a General Authenticate command.
byte[]	sendGetChallenge() Sends a GET CHALLENGE command to the passport.
byte[]	sendGetChallenge(net.sf.scuba.smartcards.APDUWrapper wrapper) Sends a GET CHALLENGE command to the passport.
byte[]	sendInternalAuthenticate(net.sf.scuba.smartcards.APDUWrapper wrapper, byte[] rndIFD) Sends an INTERNAL AUTHENTICATE command to the passport.
void	sendMSEKAT(net.sf.scuba.smartcards.APDUWrapper wrapper, byte[] keyData, byte[] idData) The MSE KAT APDU, see EAC 1.11 spec, Section B.1
void	sendMSESetATExtAuth(net.sf.scuba.smartcards.APDUWrapper wrapper, byte[] data) The MSE Set AT APDU for TA, see EAC 1.11 spec, Section B.2.
void	sendMSESetATMutualAuth(net.sf.scuba.smartcards.APDUWrapper wrapper, String oid, int refPublicKeyOrSecretKey, byte[] refPrivateKeyOrForComputingSessionKey) The MSE AT APDU for PACE, see ICAO TR-SAC-1.01, Section 3.2.1, BSI TR 03110 v2.03 B11.1.
void	sendMSESetDST(net.sf.scuba.smartcards.APDUWrapper wrapper, byte[] data) The MSE DST APDU, see EAC 1.11 spec, Section B.2
byte[]	sendMutualAuth(byte[] rndIFD, byte[] rndICC, byte[] kIFD, SecretKey kEnc, SecretKey kMac) Sends an EXTERNAL AUTHENTICATE command to the passport.
void	sendMutualAuthenticate(net.sf.scuba.smartcards.APDUWrapper wrapper, byte[] signature) Sends the EXTERNAL AUTHENTICATE command.
void	sendPSOChainMode(net.sf.scuba.smartcards.APDUWrapper wrapper, byte[] certBodyData, byte[] certSignatureData) Sends a perform security operation command in chain mode.
void	sendPSOExtendedLengthMode(net.sf.scuba.smartcards.APDUWrapper wrapper, byte[] certBodyData, byte[] certSignatureData) Sends a perform security operation command in extended length mode.
byte[]	sendReadBinary(net.sf.scuba.smartcards.APDUWrapper wrapper, int offset, int le, boolean isExtendedLength) Sends a READ BINARY command to the passport.
byte[]	sendReadBinary(short offset, int le, boolean longRead) Sends a READ BINARY command to the passport.
void	sendSelectApplet(net.sf.scuba.smartcards.APDUWrapper wrapper, byte[] aid) Sends a SELECT APPLET command to the card.
void	sendSelectFile(net.sf.scuba.smartcards.APDUWrapper wrapper, short fid) Sends a SELECT FILE command to the passport.
void	sendSelectFile(short fid) Selects a file.
void	setService(net.sf.scuba.smartcards.CardService service) Sets the service.
net.sf.scuba.smartcards.ResponseAPDU	transmit(net.sf.scuba.smartcards.CommandAPDU capdu) Tranceives an APDU.

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

getInstance, isExtendedAPDULengthSupported, notifyExchangedAPDU

Methods inherited from class java.lang.Object

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

Field Detail

MRZ_PACE_KEY_REFERENCE

public static final byte MRZ_PACE_KEY_REFERENCE

Shared secret type for PACE according to BSI TR-03110 v2.03 B.11.1.

See Also:

Constant Field Values

CAN_PACE_KEY_REFERENCE

public static final byte CAN_PACE_KEY_REFERENCE

Shared secret type for PACE according to BSI TR-03110 v2.03 B.11.1.

See Also:

Constant Field Values

PIN_PACE_KEY_REFERENCE

public static final byte PIN_PACE_KEY_REFERENCE

Shared secret type for PACE according to BSI TR-03110 v2.03 B.11.1.

See Also:

Constant Field Values

PUK_PACE_KEY_REFERENCE

public static final byte PUK_PACE_KEY_REFERENCE

Shared secret type for PACE according to BSI TR-03110 v2.03 B.11.1.

See Also:

Constant Field Values

APPLET_AID

protected static final byte[] APPLET_AID

The applet we select when we start a session.

Constructor Detail

PassportApduService

public PassportApduService(net.sf.scuba.smartcards.CardService service)
                    throws net.sf.scuba.smartcards.CardServiceException

Creates a new passport APDU sending service.

Parameters:

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

Throws:

net.sf.scuba.smartcards.CardServiceException - when the available JCE providers cannot provide the necessary cryptographic primitives:

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

Method Detail

open

public void open()
          throws net.sf.scuba.smartcards.CardServiceException

Opens a session by connecting to the card. Since version 0.5.1 this method no longer automatically selects the MRTD applet, caller (for instance PassportService) is responsible to do this now.

Specified by:

open in class net.sf.scuba.smartcards.CardService

Throws:

net.sf.scuba.smartcards.CardServiceException - on failure to open the service

isOpen

public boolean isOpen()

Whether this service is open.

Specified by:

isOpen in class net.sf.scuba.smartcards.CardService

Returns:

a boolean

transmit

public net.sf.scuba.smartcards.ResponseAPDU transmit(net.sf.scuba.smartcards.CommandAPDU capdu)
                                              throws net.sf.scuba.smartcards.CardServiceException

Tranceives an APDU. If the card responds with a status word other than 0x9000 this method does NOT throw a CardServiceException, but it returns this as error code as result.

Specified by:

transmit in class net.sf.scuba.smartcards.CardService

Parameters:

capdu - the command APDU

Returns:

the response APDU

Throws:

net.sf.scuba.smartcards.CardServiceException - on error

getATR

public byte[] getATR()

Gets the answer to reset bytes.

Specified by:

getATR in class net.sf.scuba.smartcards.CardService

Returns:

the answer to reset bytes

close

public void close()

Closes the service.

Specified by:

close in class net.sf.scuba.smartcards.CardService

setService

public void setService(net.sf.scuba.smartcards.CardService service)

Sets the service.

Parameters:

service - the carrier service that is decorated by this service

service - the carrier service

addAPDUListener

public void addAPDUListener(net.sf.scuba.smartcards.APDUListener l)

Adds a listener.

Overrides:

addAPDUListener in class net.sf.scuba.smartcards.CardService

Parameters:

l - a listener

removeAPDUListener

public void removeAPDUListener(net.sf.scuba.smartcards.APDUListener l)

Removes a listener.

Overrides:

removeAPDUListener in class net.sf.scuba.smartcards.CardService

Parameters:

l - a listener

sendSelectApplet

public void sendSelectApplet(net.sf.scuba.smartcards.APDUWrapper wrapper,
                             byte[] aid)
                      throws net.sf.scuba.smartcards.CardServiceException

Sends a SELECT APPLET command to the card.

Parameters:

wrapper - the secure messaging wrapper to use

aid - the applet to select

Throws:

net.sf.scuba.smartcards.CardServiceException - on tranceive error

sendSelectFile

public void sendSelectFile(short fid)
                    throws net.sf.scuba.smartcards.CardServiceException

Selects a file.

Parameters:

fid - the file identifier

Throws:

net.sf.scuba.smartcards.CardServiceException - on error

sendSelectFile

public void sendSelectFile(net.sf.scuba.smartcards.APDUWrapper wrapper,
                           short fid)
                    throws net.sf.scuba.smartcards.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:

net.sf.scuba.smartcards.CardServiceException - on tranceive error

sendReadBinary

public byte[] sendReadBinary(short offset,
                             int le,
                             boolean longRead)
                      throws net.sf.scuba.smartcards.CardServiceException

Sends a READ BINARY command to the passport.

Parameters:

offset - offset into the file

le - the expected length of the file to read

longRead - whether to use extended length APDUs

Returns:

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

Throws:

net.sf.scuba.smartcards.CardServiceException - if the command was not successful

sendReadBinary

public byte[] sendReadBinary(net.sf.scuba.smartcards.APDUWrapper wrapper,
                             int offset,
                             int le,
                             boolean isExtendedLength)
                      throws net.sf.scuba.smartcards.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

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

Returns:

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

Throws:

net.sf.scuba.smartcards.CardServiceException - if the command was not successful

sendGetChallenge

public byte[] sendGetChallenge()
                        throws net.sf.scuba.smartcards.CardServiceException

Sends a GET CHALLENGE command to the passport.

Returns:

a byte array of length 8 containing the challenge

Throws:

net.sf.scuba.smartcards.CardServiceException - on tranceive error

sendGetChallenge

public byte[] sendGetChallenge(net.sf.scuba.smartcards.APDUWrapper wrapper)
                        throws net.sf.scuba.smartcards.CardServiceException

Sends a GET CHALLENGE command to the passport.

Parameters:

wrapper - secure messaging wrapper

Returns:

a byte array of length 8 containing the challenge

Throws:

net.sf.scuba.smartcards.CardServiceException - on tranceive error

sendInternalAuthenticate

public byte[] sendInternalAuthenticate(net.sf.scuba.smartcards.APDUWrapper wrapper,
                                       byte[] rndIFD)
                                throws net.sf.scuba.smartcards.CardServiceException

Sends an INTERNAL AUTHENTICATE command to the passport. This is part of AA.

Parameters:

wrapper - secure messaging wrapper

rndIFD - the challenge to send

Returns:

the response from the passport (status word removed)

Throws:

net.sf.scuba.smartcards.CardServiceException - on tranceive error

sendMutualAuth

public byte[] sendMutualAuth(byte[] rndIFD,
                             byte[] rndICC,
                             byte[] kIFD,
                             SecretKey kEnc,
                             SecretKey kMac)
                      throws net.sf.scuba.smartcards.CardServiceException

Sends an EXTERNAL AUTHENTICATE command to the passport. This is part of BAC. 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:

net.sf.scuba.smartcards.CardServiceException - on tranceive error

sendMutualAuthenticate

public void sendMutualAuthenticate(net.sf.scuba.smartcards.APDUWrapper wrapper,
                                   byte[] signature)
                            throws net.sf.scuba.smartcards.CardServiceException

Sends the EXTERNAL AUTHENTICATE command. This is used in EAC-TA.

Parameters:

wrapper - secure messaging wrapper

signature - terminal signature

Throws:

net.sf.scuba.smartcards.CardServiceException - if the resulting status word different from 9000

sendMSEKAT

public void sendMSEKAT(net.sf.scuba.smartcards.APDUWrapper wrapper,
                       byte[] keyData,
                       byte[] idData)
                throws net.sf.scuba.smartcards.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:

net.sf.scuba.smartcards.CardServiceException - on error

sendMSESetDST

public void sendMSESetDST(net.sf.scuba.smartcards.APDUWrapper wrapper,
                          byte[] data)
                   throws net.sf.scuba.smartcards.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:

net.sf.scuba.smartcards.CardServiceException - on error

sendMSESetATExtAuth

public void sendMSESetATExtAuth(net.sf.scuba.smartcards.APDUWrapper wrapper,
                                byte[] data)
                         throws net.sf.scuba.smartcards.CardServiceException

The MSE Set AT APDU for TA, see EAC 1.11 spec, Section B.2. MANAGE SECURITY ENVIRONMENT command with SET Authentication Template function. Note that caller is responsible for prefixing the byte[] params with specified tags.

Parameters:

wrapper - secure messaging wrapper

data - public key reference data object (should already be prefixed with tag 0x83)

Throws:

net.sf.scuba.smartcards.CardServiceException - on error

sendMSESetATMutualAuth

public void sendMSESetATMutualAuth(net.sf.scuba.smartcards.APDUWrapper wrapper,
                                   String oid,
                                   int refPublicKeyOrSecretKey,
                                   byte[] refPrivateKeyOrForComputingSessionKey)
                            throws net.sf.scuba.smartcards.CardServiceException

The MSE AT APDU for PACE, see ICAO TR-SAC-1.01, Section 3.2.1, BSI TR 03110 v2.03 B11.1. Note that (for now) caller is responsible for prefixing the byte[] params with specified tags.

Parameters:

wrapper - secure messaging wrapper

oid - OID of the protocol to select (this method will prefix 0x80)

refPublicKeyOrSecretKey - value specifying whether to use MRZ (0x01) or CAN (0x02) (this method will prefix 0x83)

refPrivateKeyOrForComputingSessionKey - indicates a private key or reference for computing a session key (this method will prefix 0x84)

Throws:

net.sf.scuba.smartcards.CardServiceException - on error

sendGeneralAuthenticate

public byte[] sendGeneralAuthenticate(net.sf.scuba.smartcards.APDUWrapper wrapper,
                                      byte[] data,
                                      boolean isLast)
                               throws net.sf.scuba.smartcards.CardServiceException

Sends a General Authenticate command.

Parameters:

wrapper - secure messaging wrapper

data - data to be sent, without the 0x7C prefix (this method will add it)

isLast - indicates whether this is the last command in the chain

Returns:

dynamic authentication data without the 0x7C prefix (this method will remove it)

Throws:

net.sf.scuba.smartcards.CardServiceException - on error

sendPSOExtendedLengthMode

public void sendPSOExtendedLengthMode(net.sf.scuba.smartcards.APDUWrapper wrapper,
                                      byte[] certBodyData,
                                      byte[] certSignatureData)
                               throws net.sf.scuba.smartcards.CardServiceException

Sends a perform security operation command in extended length mode.

Parameters:

wrapper - secure messaging wrapper

certBodyData - the certificate body

certSignatureData - signature data

Throws:

net.sf.scuba.smartcards.CardServiceException - on error communicating over the service

sendPSOChainMode

public void sendPSOChainMode(net.sf.scuba.smartcards.APDUWrapper wrapper,
                             byte[] certBodyData,
                             byte[] certSignatureData)
                      throws net.sf.scuba.smartcards.CardServiceException

Sends a perform security operation command in chain mode.

Parameters:

wrapper - secure messaging wrapper

certBodyData - the certificate body

certSignatureData - signature data

Throws:

net.sf.scuba.smartcards.CardServiceException - on error communicating over the service

addPlainTextAPDUListener

public void addPlainTextAPDUListener(net.sf.scuba.smartcards.APDUListener l)

Adds a plain text listener.

Parameters:

l - a listener

removePlainTextAPDUListener

public void removePlainTextAPDUListener(net.sf.scuba.smartcards.APDUListener l)

Removes a plain text listener.

Parameters:

l - a listener

notifyExchangedPlainTextAPDU

protected void notifyExchangedPlainTextAPDU(int count,
                                            net.sf.scuba.smartcards.CommandAPDU capdu,
                                            net.sf.scuba.smartcards.ResponseAPDU rapdu)

Notifies listeners about APDU event.

Parameters:

count - count

capdu - command APDU

rapdu - response APDU