Package org.jmrtd

Class 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.
      • Fields inherited from class net.sf.scuba.smartcards.CardService

        SESSION_STARTED_STATE, SESSION_STOPPED_STATE, state
    • 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.
    • 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_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_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 card
        maxTranceiveLength - maximum length for APDUs
        maxBlockSize - maximum buffer size for plain text APDUs
        isSFIEnabled - whether short file identifiers should be used for read binaries when possible
        shouldCheckMAC - 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 class net.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 class AbstractMRTDCardService
        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 class net.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 class AbstractMRTDCardService
        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 class AbstractMRTDCardService
        Parameters:
        kEnc - static 3DES key required for BAC
        kMac - static 3DES key required for BAC
        Returns:
        the result
        Throws:
        net.sf.scuba.smartcards.CardServiceException - if authentication failed
        GeneralSecurityException - 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 class AbstractMRTDCardService
        Parameters:
        keySpec - the MRZ
        oid - as specified in the PACEInfo, indicates GM or IM or CAM, DH or ECDH, cipher, digest, length
        params - 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 class AbstractMRTDCardService
        Parameters:
        keyId - passport's public key id (stored in DG14), null if none
        oid - the object identifier indicating the Chip Authentication protocol
        publicKeyOID - the object identifier indicating the public key algorithm used
        publicKey - 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 class AbstractMRTDCardService
        Parameters:
        caReference - reference issuer
        terminalCertificates - terminal certificate chain
        terminalKey - terminal private key
        taAlg - algorithm
        chipAuthenticationResult - the chip authentication result
        documentNumber - 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 class AbstractMRTDCardService
        Parameters:
        caReference - reference issuer
        terminalCertificates - terminal certificate chain
        terminalKey - terminal private key
        taAlg - algorithm
        chipAuthenticationResult - the chip authentication result
        paceResult - 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 class AbstractMRTDCardService
        Parameters:
        publicKey - the public key to use (usually read from the card)
        digestAlgorithm - the digest algorithm to use, or null
        signatureAlgorithm - signature algorithm
        challenge - 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 class net.sf.scuba.smartcards.CardService
      • getMaxTranceiveLength

        public int getMaxTranceiveLength()
        Returns the maximum tranceive length of (protected) APDUs.
        Returns:
        the maximum APDU tranceive length
      • transmit

        public net.sf.scuba.smartcards.ResponseAPDU transmit​(net.sf.scuba.smartcards.CommandAPDU commandAPDU)
                                                      throws net.sf.scuba.smartcards.CardServiceException
        Specified by:
        transmit in class net.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 class net.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 class net.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 class FileSystemCardService
        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 class net.sf.scuba.smartcards.CardService
      • removeAPDUListener

        public void removeAPDUListener​(net.sf.scuba.smartcards.APDUListener l)
        Overrides:
        removeAPDUListener in class net.sf.scuba.smartcards.CardService