org.jmrtd

Class AbstractMRTDCardService

java.lang.Object

net.sf.scuba.smartcards.CardService

org.jmrtd.FileSystemCardService

org.jmrtd.AbstractMRTDCardService

Direct Known Subclasses:

PassportService

public abstract class AbstractMRTDCardService
extends FileSystemCardService

Base class for MRTD card services.

Since:

0.7.0

Version:

$Revision: 1781 $

Author:

The JMRTD team ([email protected])

Field Summary

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

SESSION_STARTED_STATE, SESSION_STOPPED_STATE, state

Constructor Summary

Constructors

Constructor and Description
AbstractMRTDCardService()

Method Summary

Modifier and Type	Method and Description
abstract AAResult	doAA(PublicKey publicKey, String digestAlgorithm, String signatureAlgorithm, byte[] challenge) Performs the Active Authentication protocol.
abstract BACResult	doBAC(AccessKeySpec bacKey) Performs the Basic Access Control protocol.
abstract BACResult	doBAC(SecretKey kEnc, SecretKey kMac) Performs the Basic Access Control protocol.
abstract EACCAResult	doEACCA(BigInteger keyId, String oid, String publicKeyOID, PublicKey publicKey) Perform CA (Chip Authentication) part of EAC (version 1).
abstract EACTAResult	doEACTA(CVCPrincipal caReference, List<CardVerifiableCertificate> terminalCertificates, PrivateKey terminalKey, String taAlg, EACCAResult chipAuthenticationResult, PACEResult paceResult) Performs Terminal Authentication (TA) part of EAC (version 1).
abstract EACTAResult	doEACTA(CVCPrincipal caReference, List<CardVerifiableCertificate> terminalCertificates, PrivateKey terminalKey, String taAlg, EACCAResult chipAuthenticationResult, String documentNumber) Performs Terminal Authentication (TA) part of EAC (version 1).
abstract PACEResult	doPACE(AccessKeySpec keySpec, String oid, AlgorithmParameterSpec params) Performs the PACE 2.0 / SAC protocol.
abstract SecureMessagingWrapper	getWrapper() Return the secure messaging wrapper currently in use.
abstract void	sendSelectApplet(boolean shouldUseSecureMessaging) Selects the card side applet.

Methods inherited from class org.jmrtd.FileSystemCardService

getInputStream

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

addAPDUListener, close, getAPDUListeners, getATR, getInstance, isConnectionLost, isExtendedAPDULengthSupported, isOpen, notifyExchangedAPDU, open, removeAPDUListener, transmit

Methods inherited from class java.lang.Object

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

Constructor Detail

AbstractMRTDCardService

public AbstractMRTDCardService()

Method Detail

doBAC

public abstract BACResult doBAC(AccessKeySpec bacKey)
                         throws net.sf.scuba.smartcards.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 expiration date

Returns:

the BAC result

Throws:

net.sf.scuba.smartcards.CardServiceException - if authentication failed

doBAC

public abstract 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.

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 abstract PACEResult doPACE(AccessKeySpec keySpec,
                                  String oid,
                                  AlgorithmParameterSpec params)
                           throws PACEException

Performs the PACE 2.0 / SAC protocol. A secure messaging channel is set up as a result.

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:

PACEException - on error

sendSelectApplet

public abstract void sendSelectApplet(boolean shouldUseSecureMessaging)
                               throws net.sf.scuba.smartcards.CardServiceException

Selects the card side applet. If PACE has been executed successfully previously, then the card 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.

Parameters:

shouldUseSecureMessaging - indicates whether a secure messaging channel has already been established (which is the case if PACE has been executed)

Throws:

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

doAA

public abstract AAResult doAA(PublicKey publicKey,
                              String digestAlgorithm,
                              String signatureAlgorithm,
                              byte[] challenge)
                       throws net.sf.scuba.smartcards.CardServiceException

Performs the Active Authentication protocol.

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

doEACCA

public abstract 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.

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 abstract 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.

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 abstract 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.

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

getWrapper

public abstract SecureMessagingWrapper getWrapper()

Return the secure messaging wrapper currently in use.

Returns:

the secure messaging wrapper