org.jmrtd
Class PassportService

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

All Implemented Interfaces:

Serializable

public class PassportService
extends PassportApduService
implements Serializable

Card service for reading files (such as data groups) and using the BAC and AA protocols on the passport. Defines secure messaging. Defines active authentication. Based on ICAO-TR-PKI and ICAO-TR-LDS. Usage:

        open() ==><br />
        doBAC(...) ==><br />
        doAA() ==><br />
        readFile(...)<sup>*</sup> ==><br />
        close()
 

Version:

$Revision:352 $

Author:

Martijn Oostdijk (martijn.oostdijk@gmail.com)

See Also:

Serialized Form

Field Summary

static short	EF_COM File indicating which data groups are present.
static short	EF_CVCA File with the EAC CVCA references.
static short	EF_DG1 Data group 1 contains the MRZ.
static short	EF_DG10 Data group 10 contains substance features.
static short	EF_DG11 Data group 11 contains additional personal details.
static short	EF_DG12 Data group 12 contains additional document details.
static short	EF_DG13 Data group 13 contains optional details.
static short	EF_DG14 Data group 14 is RFU.
static short	EF_DG15 Data group 15 contains the public key used for Active Authentication.
static short	EF_DG16 Data group 16 contains person(s) to notify.
static short	EF_DG2 Data group 2 contains face image data.
static short	EF_DG3 Data group 3 contains finger print data.
static short	EF_DG4 Data group 4 contains iris data.
static short	EF_DG5 Data group 5 contains displayed portrait.
static short	EF_DG6 Data group 6 is RFU.
static short	EF_DG7 Data group 7 contains displayed signature.
static short	EF_DG8 Data group 8 contains data features.
static short	EF_DG9 Data group 9 contains structure features.
static short	EF_SOD The security document.
static int	maxBlockSize Deprecated. hack
protected Random	random
static SimpleDateFormat	SDF
static byte	SF_COM
static byte	SF_CVCA
static byte	SF_DG1 Short file identifiers for the DGs
static byte	SF_DG10
static byte	SF_DG11
static byte	SF_DG12
static byte	SF_DG13
static byte	SF_DG14
static byte	SF_DG15
static byte	SF_DG16
static byte	SF_DG2
static byte	SF_DG3
static byte	SF_DG4
static byte	SF_DG5
static byte	SF_DG6
static byte	SF_DG7
static byte	SF_DG8
static byte	SF_DG9
static byte	SF_SOD
protected SecureMessagingWrapper	wrapper Deprecated. visibility will be set to private

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

listeners

Constructor Summary

PassportService(CardService service)
Creates a new passport service for accessing the passport.

Method Summary

void	addAuthenticationListener(AuthListener l) Adds an authentication event listener.
void	close() Closes this service.
boolean	doAA(PublicKey publicKey) s * Performs the Active Authentication protocol.
void	doBAC(BACKeySpec bacKey) Performs the Basic Access Control protocol.
KeyPair	doCA(int keyId, PublicKey key) Perform CA (Chip Authentication) part of EAC.
void	doEAC(int keyId, PublicKey key, org.jmrtd.cert.CVCPrincipal caReference, List<org.jmrtd.cert.CardVerifiableCertificate> terminalCertificates, PrivateKey terminalKey, String documentNumber) Performs the EAC protocol with the passport.
byte[]	doTA(org.jmrtd.cert.CVCPrincipal caReference, List<org.jmrtd.cert.CardVerifiableCertificate> terminalCertificates, PrivateKey terminalKey, byte[] caKeyHash, String documentNumber)
byte[]	doTA(org.jmrtd.cert.CVCPrincipal caReference, List<org.jmrtd.cert.CardVerifiableCertificate> terminalCertificates, PrivateKey terminalKey, String taAlg, byte[] caKeyHash, String documentNumber) Perform TA (Terminal Authentication) part of EAC.
SecureMessagingWrapper	getWrapper() Gets the wrapper.
boolean	isOpen() Whether this service is open.
protected void	notifyAAPerformed(AAEvent event) Notifies listeners about AA event.
protected void	notifyBACPerformed(BACEvent event) Notifies listeners about BAC events.
protected void	notifyEACPerformed(EACEvent event) Notifies listeners about EAC event.
void	open() Opens a session.
CardFileInputStream	readFile(short fid) Gets the file indicated by a file identifier.
void	removeAuthenticationListener(AuthListener l) Removes an authentication event listener.
byte[]	sendAA(PublicKey publicKey, byte[] challenge) Performs the Active Authentication protocol.
void	setWrapper(SecureMessagingWrapper wrapper) Deprecated. hack

Methods inherited from class org.jmrtd.PassportApduService

addAPDUListener, createGetChallengeAPDU, createReadBinaryAPDU, removeAPDUListener, sendGetChallenge, sendGetChallenge, sendInternalAuthenticate, sendMSEAT, sendMSEDST, sendMSEKAT, sendMutualAuth, sendMutualAuthenticate, sendPSOChainMode, sendPSOExtendedLengthMode, sendReadBinary, sendReadBinary, sendSelectApplet, sendSelectFile, setListenersState, setService, transmit

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

Field Detail

EF_DG1

public static final short EF_DG1

Data group 1 contains the MRZ.

See Also:

Constant Field Values

EF_DG2

public static final short EF_DG2

Data group 2 contains face image data.

See Also:

Constant Field Values

EF_DG3

public static final short EF_DG3

Data group 3 contains finger print data.

See Also:

Constant Field Values

EF_DG4

public static final short EF_DG4

Data group 4 contains iris data.

See Also:

Constant Field Values

EF_DG5

public static final short EF_DG5

Data group 5 contains displayed portrait.

See Also:

Constant Field Values

EF_DG6

public static final short EF_DG6

Data group 6 is RFU.

See Also:

Constant Field Values

EF_DG7

public static final short EF_DG7

Data group 7 contains displayed signature.

See Also:

Constant Field Values

EF_DG8

public static final short EF_DG8

Data group 8 contains data features.

See Also:

Constant Field Values

EF_DG9

public static final short EF_DG9

Data group 9 contains structure features.

See Also:

Constant Field Values

EF_DG10

public static final short EF_DG10

Data group 10 contains substance features.

See Also:

Constant Field Values

EF_DG11

public static final short EF_DG11

Data group 11 contains additional personal details.

See Also:

Constant Field Values

EF_DG12

public static final short EF_DG12

Data group 12 contains additional document details.

See Also:

Constant Field Values

EF_DG13

public static final short EF_DG13

Data group 13 contains optional details.

See Also:

Constant Field Values

EF_DG14

public static final short EF_DG14

Data group 14 is RFU.

See Also:

Constant Field Values

EF_DG15

public static final short EF_DG15

Data group 15 contains the public key used for Active Authentication.

See Also:

Constant Field Values

EF_DG16

public static final short EF_DG16

Data group 16 contains person(s) to notify.

See Also:

Constant Field Values

EF_SOD

public static final short EF_SOD

The security document.

See Also:

Constant Field Values

EF_COM

public static final short EF_COM

File indicating which data groups are present.

See Also:

Constant Field Values

EF_CVCA

public static final short EF_CVCA

File with the EAC CVCA references. Note: this can be overridden by a file identifier in the DG14 file (TerminalAuthenticationInfo). So check that one first. Also, this file does not have a header tag, like the others.

See Also:

Constant Field Values

SF_DG1

public static final byte SF_DG1

Short file identifiers for the DGs

See Also:

Constant Field Values

SF_DG2

public static final byte SF_DG2

See Also:

Constant Field Values

SF_DG3

public static final byte SF_DG3

See Also:

Constant Field Values

SF_DG4

public static final byte SF_DG4

See Also:

Constant Field Values

SF_DG5

public static final byte SF_DG5

See Also:

Constant Field Values

SF_DG6

public static final byte SF_DG6

See Also:

Constant Field Values

SF_DG7

public static final byte SF_DG7

See Also:

Constant Field Values

SF_DG8

public static final byte SF_DG8

See Also:

Constant Field Values

SF_DG9

public static final byte SF_DG9

See Also:

Constant Field Values

SF_DG10

public static final byte SF_DG10

See Also:

Constant Field Values

SF_DG11

public static final byte SF_DG11

See Also:

Constant Field Values

SF_DG12

public static final byte SF_DG12

See Also:

Constant Field Values

SF_DG13

public static final byte SF_DG13

See Also:

Constant Field Values

SF_DG14

public static final byte SF_DG14

See Also:

Constant Field Values

SF_DG15

public static final byte SF_DG15

See Also:

Constant Field Values

SF_DG16

public static final byte SF_DG16

See Also:

Constant Field Values

SF_COM

public static final byte SF_COM

See Also:

Constant Field Values

SF_SOD

public static final byte SF_SOD

See Also:

Constant Field Values

SF_CVCA

public static final byte SF_CVCA

See Also:

Constant Field Values

SDF

public static final SimpleDateFormat SDF

maxBlockSize

public static int maxBlockSize

Deprecated. hack

The file read block size, some passports cannot handle large values

wrapper

protected SecureMessagingWrapper wrapper

Deprecated. visibility will be set to private

random

protected Random random

Constructor Detail

PassportService

public PassportService(CardService service)
                throws CardServiceException

Creates a new passport service for accessing the passport.

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.

CardServiceException

Method Detail

open

public void open()
          throws CardServiceException

Opens a session. This is done by connecting to the card, selecting the passport application.

Overrides:

open in class PassportApduService

Throws:

CardServiceException

isOpen

public boolean isOpen()

Whether this service is open.

Overrides:

isOpen in class PassportApduService

Returns:

a boolean

doBAC

public void doBAC(BACKeySpec bacKey)
           throws CardServiceException

Performs the Basic Access Control protocol.

Parameters:

bacKey - the key based on the document number, the card holder's birth date, and the document's expiry date

Throws:

CardServiceException - if authentication failed

doCA

public KeyPair doCA(int keyId,
                    PublicKey key)
             throws CardServiceException

Perform CA (Chip Authentication) part of EAC. For details see TR-03110 ver. 1.11. In short, we authenticate the chip with (EC)DH key agreement protocol and create new secure messaging keys.

Parameters:

keyId - passport's public key id (stored in DG14), -1 if none.

key - passport's public key (stored in DG14).

Throws:

CardServiceException - if CA failed or some error occurred

doTA

public byte[] doTA(org.jmrtd.cert.CVCPrincipal caReference,
                   List<org.jmrtd.cert.CardVerifiableCertificate> terminalCertificates,
                   PrivateKey terminalKey,
                   String taAlg,
                   byte[] caKeyHash,
                   String documentNumber)
            throws CardServiceException

Perform TA (Terminal Authentication) part of EAC. For details see TR-03110 ver. 1.11. In short, we feed the sequence of terminal certificates to the card for verification, get a challenge from the passport, sign it with terminal private key, and send back to the card for verification.

Throws:

CardServiceException

doTA

public byte[] doTA(org.jmrtd.cert.CVCPrincipal caReference,
                   List<org.jmrtd.cert.CardVerifiableCertificate> terminalCertificates,
                   PrivateKey terminalKey,
                   byte[] caKeyHash,
                   String documentNumber)
            throws CardServiceException

Throws:

CardServiceException

doEAC

public void doEAC(int keyId,
                  PublicKey key,
                  org.jmrtd.cert.CVCPrincipal caReference,
                  List<org.jmrtd.cert.CardVerifiableCertificate> terminalCertificates,
                  PrivateKey terminalKey,
                  String documentNumber)
           throws CardServiceException

Performs the EAC protocol with the passport. For details see TR-03110 ver. 1.11. In short: a. authenticate the chip with (EC)DH key agreement protocol (new secure messaging keys are created then), b. feed the sequence of terminal certificates to the card for verification. c. get a challenge from the passport, sign it with terminal private key, send back to the card for verification.

Parameters:

keyId - passport's public key id (stored in DG14), -1 if none.

key - passport's public key (stored in DG14).

caReference - the CA certificate key reference, this can be read from the CVCA file

terminalCertificates - the list/chain of terminal certificates

terminalKey - terminal private key

documentNumber - the passport number

Throws:

CardServiceException - on error

addAuthenticationListener

public void addAuthenticationListener(AuthListener l)

Adds an authentication event listener.

Parameters:

l - listener

removeAuthenticationListener

public void removeAuthenticationListener(AuthListener l)

Removes an authentication event listener.

Parameters:

l - listener

notifyBACPerformed

protected void notifyBACPerformed(BACEvent event)

Notifies listeners about BAC events.

Parameters:

event - BAC event

notifyEACPerformed

protected void notifyEACPerformed(EACEvent event)

Notifies listeners about EAC event.

Parameters:

event - EAC event.

doAA

public boolean doAA(PublicKey publicKey)
             throws CardServiceException

s * Performs the Active Authentication protocol.

Parameters:

publicKey - the public key to use (usually read from the card)

Returns:

a boolean indicating whether the card was authenticated

Throws:

GeneralSecurityException - if something goes wrong

CardServiceException

sendAA

public byte[] sendAA(PublicKey publicKey,
                     byte[] challenge)
              throws CardServiceException

Performs the Active Authentication protocol. This method just gives the response from the card without checking. Use doAA(PublicKey) instead.

Parameters:

publicKey - the public key to use (usually read from the card)

challenge - the random challenge of exactly 8 bytes

Returns:

response from the card

Throws:

CardServiceException

notifyAAPerformed

protected void notifyAAPerformed(AAEvent event)

Notifies listeners about AA event.

Parameters:

event - AA event.

close

public void close()

Closes this service.

Overrides:

close in class PassportApduService

getWrapper

public SecureMessagingWrapper getWrapper()

Gets the wrapper. Returns null until BAC has been performed.

Returns:

the wrapper

setWrapper

public void setWrapper(SecureMessagingWrapper wrapper)

Deprecated. hack

Parameters:

wrapper - wrapper

readFile

public CardFileInputStream readFile(short fid)
                             throws CardServiceException

Gets the file indicated by a file identifier.

Parameters:

fid - ICAO file identifier

Returns:

the file

Throws:

IOException - if the file cannot be read

CardServiceException