Package org.jmrtd
Class PassportService
- java.lang.Object
-
- net.sf.scuba.smartcards.CardService
-
- org.jmrtd.FileSystemCardService
-
- org.jmrtd.AbstractMRTDCardService
-
- org.jmrtd.PassportService
-
public class PassportService extends AbstractMRTDCardService
Card service for reading files (such as data groups) and using the various access control protocols (BAC, PACE, EAC-TA), clone-detection verification protocols (AA, EAC-CA), and the resulting secure messaging as implemented by the MRTD ICC. Based on ICAO Doc 9303 2015. Originally based on ICAO-TR-PKI and ICAO-TR-LDS.- Version:
- $Revision:352 $
- Author:
- The JMRTD team ([email protected])
-
-
Field Summary
Fields Modifier and Type Field 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 int
DEFAULT_MAX_BLOCKSIZE
The default maximal blocksize used for unencrypted APDUs.static short
EF_CARD_ACCESS
Card Access.static short
EF_CARD_SECURITY
Card Security.static short
EF_COM
The data group presence list.static short
EF_CVCA
Contains EAC CVA references.static short
EF_DG1
File identifier for data group 1.static short
EF_DG10
File identifier for data group 10.static short
EF_DG11
File identifier for data group 11.static short
EF_DG12
File identifier for data group 12.static short
EF_DG13
File identifier for data group 13.static short
EF_DG14
File identifier for data group 14.static short
EF_DG15
File identifier for data group 15.static short
EF_DG16
File identifier for data group 16.static short
EF_DG2
File identifier for data group 2.static short
EF_DG3
File identifier for data group 3.static short
EF_DG4
File identifier for data group 4.static short
EF_DG5
File identifier for data group 5.static short
EF_DG6
File identifier for data group 6.static short
EF_DG7
File identifier for data group 7.static short
EF_DG8
File identifier for data group 8.static short
EF_DG9
File identifier for data group 9.static short
EF_SOD
The security document.static int
EXTENDED_MAX_TRANCEIVE_LENGTH
The extended maximal tranceive length of APDUs.static byte
MRZ_PACE_KEY_REFERENCE
Shared secret type for PACE according to BSI TR-03110 v2.03 B.11.1.static byte
NO_PACE_KEY_REFERENCE
Shared secret type for non-PACE key.static int
NORMAL_MAX_TRANCEIVE_LENGTH
The normal maximal tranceive length of APDUs.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.static byte
SFI_CARD_ACCESS
Short file identifier for card access file.static byte
SFI_CARD_SECURITY
Short file identifier for card security file.static byte
SFI_COM
Short file identifier for file.static byte
SFI_CVCA
Short file identifier for file.static byte
SFI_DG1
Short file identifier for file.static byte
SFI_DG10
Short file identifier for file.static byte
SFI_DG11
Short file identifier for file.static byte
SFI_DG12
Short file identifier for file.static byte
SFI_DG13
Short file identifier for file.static byte
SFI_DG14
Short file identifier for file.static byte
SFI_DG15
Short file identifier for file.static byte
SFI_DG16
Short file identifier for file.static byte
SFI_DG2
Short file identifier for file.static byte
SFI_DG3
Short file identifier for file.static byte
SFI_DG4
Short file identifier for file.static byte
SFI_DG5
Short file identifier for file.static byte
SFI_DG6
Short file identifier for file.static byte
SFI_DG7
Short file identifier for file.static byte
SFI_DG8
Short file identifier for file.static byte
SFI_DG9
Short file identifier for file.static byte
SFI_SOD
Short file identifier for file.
-
Constructor Summary
Constructors Constructor Description PassportService(net.sf.scuba.smartcards.CardService service, int maxTranceiveLength, int maxBlockSize, boolean isSFIEnabled, boolean shouldCheckMAC)
Creates a new passport service for accessing the passport.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addAPDUListener(net.sf.scuba.smartcards.APDUListener l)
void
close()
Closes this service.AAResult
doAA(PublicKey publicKey, String digestAlgorithm, String signatureAlgorithm, byte[] challenge)
Performs the Active Authentication protocol.BACResult
doBAC(SecretKey kEnc, SecretKey kMac)
Performs the Basic Access Control protocol.BACResult
doBAC(AccessKeySpec bacKey)
Performs the Basic Access Control protocol.EACCAResult
doEACCA(BigInteger keyId, String oid, String publicKeyOID, PublicKey publicKey)
Perform CA (Chip Authentication) part of EAC (version 1).EACTAResult
doEACTA(CVCPrincipal caReference, List<CardVerifiableCertificate> terminalCertificates, PrivateKey terminalKey, String taAlg, EACCAResult chipAuthenticationResult, String documentNumber)
Performs Terminal Authentication (TA) part of EAC (version 1).EACTAResult
doEACTA(CVCPrincipal caReference, List<CardVerifiableCertificate> terminalCertificates, PrivateKey terminalKey, String taAlg, EACCAResult chipAuthenticationResult, PACEResult paceResult)
Performs Terminal Authentication (TA) part of EAC (version 1).PACEResult
doPACE(AccessKeySpec keySpec, String oid, AlgorithmParameterSpec params)
Performs the PACE 2.0 / SAC protocol.byte[]
getATR()
Returns the answer to reset.net.sf.scuba.smartcards.CardFileInputStream
getInputStream(short fid)
Returns the file indicated by the file identifier as an input stream.int
getMaxTranceiveLength()
Returns the maximum tranceive length of (protected) APDUs.SecureMessagingWrapper
getWrapper()
Returns the secure messaging wrapper currently in use.boolean
isConnectionLost(Exception e)
Determines whether an exception indicates a tag is lost event.boolean
isOpen()
Returns a boolean that indicates whether this service is open.void
open()
Opens a session to the card.void
removeAPDUListener(net.sf.scuba.smartcards.APDUListener l)
void
sendSelectApplet(boolean hasPACESucceeded)
Selects the card side applet.boolean
shouldCheckMAC()
Whether secure channels should check the MAC on response APDUs sent by the ICC.net.sf.scuba.smartcards.ResponseAPDU
transmit(net.sf.scuba.smartcards.CommandAPDU commandAPDU)
-
-
-
Field Detail
-
NO_PACE_KEY_REFERENCE
public static final byte NO_PACE_KEY_REFERENCE
Shared secret type for non-PACE key.- See Also:
- Constant Field Values
-
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
-
EF_CARD_ACCESS
public static final short EF_CARD_ACCESS
Card Access.- See Also:
- Constant Field Values
-
EF_CARD_SECURITY
public static final short EF_CARD_SECURITY
Card Security.- See Also:
- Constant Field Values
-
EF_DG1
public static final short EF_DG1
File identifier for data group 1. Data group 1 contains the MRZ.- See Also:
- Constant Field Values
-
EF_DG2
public static final short EF_DG2
File identifier for data group 2. Data group 2 contains face image data.- See Also:
- Constant Field Values
-
EF_DG3
public static final short EF_DG3
File identifier for data group 3. Data group 3 contains finger print data.- See Also:
- Constant Field Values
-
EF_DG4
public static final short EF_DG4
File identifier for data group 4. Data group 4 contains iris data.- See Also:
- Constant Field Values
-
EF_DG5
public static final short EF_DG5
File identifier for data group 5. Data group 5 contains displayed portrait.- See Also:
- Constant Field Values
-
EF_DG6
public static final short EF_DG6
File identifier for data group 6. Data group 6 is RFU.- See Also:
- Constant Field Values
-
EF_DG7
public static final short EF_DG7
File identifier for data group 7. Data group 7 contains displayed signature.- See Also:
- Constant Field Values
-
EF_DG8
public static final short EF_DG8
File identifier for data group 8. Data group 8 contains data features.- See Also:
- Constant Field Values
-
EF_DG9
public static final short EF_DG9
File identifier for data group 9. Data group 9 contains structure features.- See Also:
- Constant Field Values
-
EF_DG10
public static final short EF_DG10
File identifier for data group 10. Data group 10 contains substance features.- See Also:
- Constant Field Values
-
EF_DG11
public static final short EF_DG11
File identifier for data group 11. Data group 11 contains additional personal details.- See Also:
- Constant Field Values
-
EF_DG12
public static final short EF_DG12
File identifier for data group 12. Data group 12 contains additional document details.- See Also:
- Constant Field Values
-
EF_DG13
public static final short EF_DG13
File identifier for data group 13. Data group 13 contains optional details.- See Also:
- Constant Field Values
-
EF_DG14
public static final short EF_DG14
File identifier for data group 14. Data group 14 contains security infos.- See Also:
- Constant Field Values
-
EF_DG15
public static final short EF_DG15
File identifier for data group 15. Data group 15 contains the public key used for Active Authentication.- See Also:
- Constant Field Values
-
EF_DG16
public static final short EF_DG16
File identifier for data group 16. 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
The data group presence list.- See Also:
- Constant Field Values
-
EF_CVCA
public static final short EF_CVCA
Contains EAC CVA references. Note: this can be overridden by a file identifier in the DG14 file (in a TerminalAuthenticationInfo). Check DG14 first. Also, this file does not have a header tag, like the others.- See Also:
- Constant Field Values
-
SFI_CARD_ACCESS
public static final byte SFI_CARD_ACCESS
Short file identifier for card access file.- See Also:
- Constant Field Values
-
SFI_CARD_SECURITY
public static final byte SFI_CARD_SECURITY
Short file identifier for card security file.- See Also:
- Constant Field Values
-
SFI_DG1
public static final byte SFI_DG1
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG2
public static final byte SFI_DG2
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG3
public static final byte SFI_DG3
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG4
public static final byte SFI_DG4
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG5
public static final byte SFI_DG5
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG6
public static final byte SFI_DG6
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG7
public static final byte SFI_DG7
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG8
public static final byte SFI_DG8
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG9
public static final byte SFI_DG9
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG10
public static final byte SFI_DG10
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG11
public static final byte SFI_DG11
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG12
public static final byte SFI_DG12
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG13
public static final byte SFI_DG13
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG14
public static final byte SFI_DG14
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG15
public static final byte SFI_DG15
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_DG16
public static final byte SFI_DG16
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_COM
public static final byte SFI_COM
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_SOD
public static final byte SFI_SOD
Short file identifier for file.- See Also:
- Constant Field Values
-
SFI_CVCA
public static final byte SFI_CVCA
Short file identifier for file.- See Also:
- Constant Field Values
-
DEFAULT_MAX_BLOCKSIZE
public static final int DEFAULT_MAX_BLOCKSIZE
The default maximal blocksize used for unencrypted APDUs.- See Also:
- Constant Field Values
-
NORMAL_MAX_TRANCEIVE_LENGTH
public static final int NORMAL_MAX_TRANCEIVE_LENGTH
The normal maximal tranceive length of APDUs.- See Also:
- Constant Field Values
-
EXTENDED_MAX_TRANCEIVE_LENGTH
public static final int EXTENDED_MAX_TRANCEIVE_LENGTH
The extended maximal tranceive length of APDUs.- See Also:
- Constant Field Values
-
APPLET_AID
protected static final byte[] APPLET_AID
The applet we select when we start a session.
-
-
Constructor Detail
-
PassportService
public PassportService(net.sf.scuba.smartcards.CardService service, int maxTranceiveLength, int maxBlockSize, boolean isSFIEnabled, boolean shouldCheckMAC)
Creates a new passport service for accessing the passport.- Parameters:
service
- another service which will deal with sending the APDUs to the cardmaxTranceiveLength
- maximum length for APDUsmaxBlockSize
- maximum buffer size for plain text APDUsisSFIEnabled
- whether short file identifiers should be used for read binaries when possibleshouldCheckMAC
- whether the secure messaging channels, resulting from BAC, PACE, EAC-CA, should check MACs on response APDUs
-
-
Method Detail
-
open
public void open() throws net.sf.scuba.smartcards.CardServiceException
Opens a session to the card. As of 0.4.10 this no longer auto selects the passport application, caller is responsible to call #sendSelectApplet(boolean) now.- Specified by:
open
in classnet.sf.scuba.smartcards.CardService
- Throws:
net.sf.scuba.smartcards.CardServiceException
- on error
-
sendSelectApplet
public void sendSelectApplet(boolean hasPACESucceeded) throws net.sf.scuba.smartcards.CardServiceException
Selects the card side applet. If PACE has been executed successfully previously, then the ICC has authenticated us and a secure messaging channel has already been established. If not, then the caller should request BAC execution as a next step.- Specified by:
sendSelectApplet
in classAbstractMRTDCardService
- Parameters:
hasPACESucceeded
- indicates whether PACE has been executed successfully (in which case a secure messaging channel has been established)- Throws:
net.sf.scuba.smartcards.CardServiceException
- on error
-
isOpen
public boolean isOpen()
Returns a boolean that indicates whether this service is open.- Specified by:
isOpen
in classnet.sf.scuba.smartcards.CardService
- Returns:
- a boolean that indicates whether this service is open
-
doBAC
public BACResult doBAC(AccessKeySpec bacKey) throws net.sf.scuba.smartcards.CardServiceException
Performs the Basic Access Control protocol.- Specified by:
doBAC
in classAbstractMRTDCardService
- Parameters:
bacKey
- the key based on the document number, the card holder's birth date, and the document's expiration date- Returns:
- the BAC result
- Throws:
net.sf.scuba.smartcards.CardServiceException
- if authentication failed
-
doBAC
public BACResult doBAC(SecretKey kEnc, SecretKey kMac) throws net.sf.scuba.smartcards.CardServiceException, GeneralSecurityException
Performs the Basic Access Control protocol. It does BAC using kEnc and kMac keys, usually calculated from the document number, the card holder's date of birth, and the card's date of expiry. A secure messaging channel is set up as a result.- Specified by:
doBAC
in classAbstractMRTDCardService
- Parameters:
kEnc
- static 3DES key required for BACkMac
- static 3DES key required for BAC- Returns:
- the result
- Throws:
net.sf.scuba.smartcards.CardServiceException
- if authentication failedGeneralSecurityException
- on security primitives related problems
-
doPACE
public PACEResult doPACE(AccessKeySpec keySpec, String oid, AlgorithmParameterSpec params) throws net.sf.scuba.smartcards.CardServiceException
Performs the PACE 2.0 / SAC protocol. A secure messaging channel is set up as a result.- Specified by:
doPACE
in classAbstractMRTDCardService
- Parameters:
keySpec
- the MRZoid
- as specified in the PACEInfo, indicates GM or IM or CAM, DH or ECDH, cipher, digest, lengthparams
- explicit static domain parameters the domain params for DH or ECDH- Returns:
- the result
- Throws:
net.sf.scuba.smartcards.CardServiceException
- on error
-
doEACCA
public EACCAResult doEACCA(BigInteger keyId, String oid, String publicKeyOID, PublicKey publicKey) throws net.sf.scuba.smartcards.CardServiceException
Perform CA (Chip Authentication) part of EAC (version 1). 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. A new secure messaging channel is set up as a result.- Specified by:
doEACCA
in classAbstractMRTDCardService
- Parameters:
keyId
- passport's public key id (stored in DG14),null
if noneoid
- the object identifier indicating the Chip Authentication protocolpublicKeyOID
- the object identifier indicating the public key algorithm usedpublicKey
- passport's public key (stored in DG14)- Returns:
- the Chip Authentication result
- Throws:
net.sf.scuba.smartcards.CardServiceException
- if CA failed or some error occurred
-
doEACTA
public EACTAResult doEACTA(CVCPrincipal caReference, List<CardVerifiableCertificate> terminalCertificates, PrivateKey terminalKey, String taAlg, EACCAResult chipAuthenticationResult, String documentNumber) throws net.sf.scuba.smartcards.CardServiceException
Performs Terminal Authentication (TA) part of EAC (version 1). 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 card, sign it with the terminal private key, and send the result back to the card for verification.- Specified by:
doEACTA
in classAbstractMRTDCardService
- Parameters:
caReference
- reference issuerterminalCertificates
- terminal certificate chainterminalKey
- terminal private keytaAlg
- algorithmchipAuthenticationResult
- the chip authentication resultdocumentNumber
- the document number- Returns:
- the Terminal Authentication result
- Throws:
net.sf.scuba.smartcards.CardServiceException
- on error
-
doEACTA
public EACTAResult doEACTA(CVCPrincipal caReference, List<CardVerifiableCertificate> terminalCertificates, PrivateKey terminalKey, String taAlg, EACCAResult chipAuthenticationResult, PACEResult paceResult) throws net.sf.scuba.smartcards.CardServiceException
Performs Terminal Authentication (TA) part of EAC (version 1). 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 card, sign it with the terminal private key, and send the result back to the card for verification.- Specified by:
doEACTA
in classAbstractMRTDCardService
- Parameters:
caReference
- reference issuerterminalCertificates
- terminal certificate chainterminalKey
- terminal private keytaAlg
- algorithmchipAuthenticationResult
- the chip authentication resultpaceResult
- the PACE result- Returns:
- the Terminal Authentication result
- Throws:
net.sf.scuba.smartcards.CardServiceException
- on error
-
doAA
public AAResult doAA(PublicKey publicKey, String digestAlgorithm, String signatureAlgorithm, byte[] challenge) throws net.sf.scuba.smartcards.CardServiceException
Performs the Active Authentication protocol.- Specified by:
doAA
in classAbstractMRTDCardService
- Parameters:
publicKey
- the public key to use (usually read from the card)digestAlgorithm
- the digest algorithm to use, or nullsignatureAlgorithm
- signature algorithmchallenge
- challenge- Returns:
- a boolean indicating whether the card was authenticated
- Throws:
net.sf.scuba.smartcards.CardServiceException
- on error
-
close
public void close()
Closes this service.- Specified by:
close
in classnet.sf.scuba.smartcards.CardService
-
getMaxTranceiveLength
public int getMaxTranceiveLength()
Returns the maximum tranceive length of (protected) APDUs.- Returns:
- the maximum APDU tranceive length
-
getWrapper
public SecureMessagingWrapper getWrapper()
Returns the secure messaging wrapper currently in use. Returnsnull
until access control has been performed.- Specified by:
getWrapper
in classAbstractMRTDCardService
- Returns:
- the wrapper
-
transmit
public net.sf.scuba.smartcards.ResponseAPDU transmit(net.sf.scuba.smartcards.CommandAPDU commandAPDU) throws net.sf.scuba.smartcards.CardServiceException
- Specified by:
transmit
in classnet.sf.scuba.smartcards.CardService
- Throws:
net.sf.scuba.smartcards.CardServiceException
-
getATR
public byte[] getATR() throws net.sf.scuba.smartcards.CardServiceException
Returns the answer to reset.- Specified by:
getATR
in classnet.sf.scuba.smartcards.CardService
- Returns:
- the answer to reset
- Throws:
net.sf.scuba.smartcards.CardServiceException
- on error
-
isConnectionLost
public boolean isConnectionLost(Exception e)
Determines whether an exception indicates a tag is lost event.- Specified by:
isConnectionLost
in classnet.sf.scuba.smartcards.CardService
- Parameters:
e
- an exception- Returns:
- whether the exception indicates a tag is lost event
-
shouldCheckMAC
public boolean shouldCheckMAC()
Whether secure channels should check the MAC on response APDUs sent by the ICC.- Returns:
- a boolean indicating whether the MAC should be checked
-
getInputStream
public net.sf.scuba.smartcards.CardFileInputStream getInputStream(short fid) throws net.sf.scuba.smartcards.CardServiceException
Returns the file indicated by the file identifier as an input stream. The resulting input stream will send APDUs to the card as it is being read.- Specified by:
getInputStream
in classFileSystemCardService
- Parameters:
fid
- the file identifier- Returns:
- the file as an input stream
- Throws:
net.sf.scuba.smartcards.CardServiceException
- if the file cannot be read
-
addAPDUListener
public void addAPDUListener(net.sf.scuba.smartcards.APDUListener l)
- Overrides:
addAPDUListener
in classnet.sf.scuba.smartcards.CardService
-
removeAPDUListener
public void removeAPDUListener(net.sf.scuba.smartcards.APDUListener l)
- Overrides:
removeAPDUListener
in classnet.sf.scuba.smartcards.CardService
-
-