org.jmrtd.protocol

Class PACEProtocol

java.lang.Object

org.jmrtd.protocol.PACEProtocol

public class PACEProtocol
extends Object

The Password Authenticated Connection Establishment protocol.

Since:

0.5.6

Version:

$Revision: $

Author:

The JMRTD team ([email protected])

Constructor Summary

Constructors

Constructor and Description
PACEProtocol(PassportService service, SecureMessagingWrapper wrapper) Constructs a PACE protocol instance.

Method Summary

Modifier and Type	Method and Description
static byte[]	computeKeySeedForPACE(KeySpec keySpec)
static SecretKey	deriveStaticPACEKey(KeySpec keySpec, String oid) Derives the static key K_pi.
PACEResult	doPACE(KeySpec keySpec, String oid, AlgorithmParameterSpec params) Performs the PACE 2.0 / SAC protocol.
PACEResult	doPACE(SecretKey staticPACEKey, String oid, AlgorithmParameterSpec params) Performs the PACE 2.0 / SAC protocol.
byte[]	doPACEStep1(SecretKey staticPACEKey, Cipher staticPACECipher) The first step in the PACE protocol receives an encrypted nonce from the PICC and decrypts it.
AlgorithmParameterSpec	doPACEStep2(PACEInfo.MappingType mappingType, String agreementAlg, AlgorithmParameterSpec params, byte[] piccNonce) The second step in the PACE protocol computes ephemeral domain parameters by performing a key agreement protocol with the PICC nonce as input.
AlgorithmParameterSpec	doPACEStep2GM(String agreementAlg, AlgorithmParameterSpec params, byte[] piccNonce)
AlgorithmParameterSpec	doPACEStep2IM(String agreementAlg, AlgorithmParameterSpec params, byte[] piccNonce)
PublicKey	doPACEStep3ExchangePublicKeys(PublicKey pcdPublicKey, AlgorithmParameterSpec ephemeralParams)
KeyPair	doPACEStep3GenerateKeyPair(String agreementAlg, AlgorithmParameterSpec ephemeralParams)
byte[]	doPACEStep3KeyAgreement(String agreementAlg, PrivateKey pcdPrivateKey, PublicKey piccPublicKey)
byte[]	doPACEStep4(String oid, PACEInfo.MappingType mappingType, KeyPair pcdKeyPair, PublicKey piccPublicKey, SecretKey macKey)
static byte[]	generateAuthenticationToken(String oid, SecretKey macKey, PublicKey publicKey) The authentication token SHALL be computed over a public key data object (cf.

Methods inherited from class java.lang.Object

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

Constructor Detail

PACEProtocol

public PACEProtocol(PassportService service,
                    SecureMessagingWrapper wrapper)

Constructs a PACE protocol instance.

Parameters:

service - the service for sending APDUs

wrapper - the already established secure messaging channel (or null)

Method Detail

doPACE

public PACEResult doPACE(KeySpec keySpec,
                         String oid,
                         AlgorithmParameterSpec params)
                  throws PACEException

Performs the PACE 2.0 / SAC protocol.

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:

a PACE result

Throws:

PACEException - on error

doPACE

public PACEResult doPACE(SecretKey staticPACEKey,
                         String oid,
                         AlgorithmParameterSpec params)
                  throws PACEException

Performs the PACE 2.0 / SAC protocol.

Parameters:

staticPACEKey - the password key

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:

a PACE result

Throws:

PACEException - on error

doPACEStep1

public byte[] doPACEStep1(SecretKey staticPACEKey,
                          Cipher staticPACECipher)
                   throws PACEException

The first step in the PACE protocol receives an encrypted nonce from the PICC and decrypts it.

Parameters:

staticPACEKey - the static PACE key

staticPACECipher - the cipher to reuse

Returns:

the decrypted encrypted PICC nonce

Throws:

PACEException - on error

doPACEStep2

public AlgorithmParameterSpec doPACEStep2(PACEInfo.MappingType mappingType,
                                          String agreementAlg,
                                          AlgorithmParameterSpec params,
                                          byte[] piccNonce)
                                   throws PACEException

The second step in the PACE protocol computes ephemeral domain parameters by performing a key agreement protocol with the PICC nonce as input.

Parameters:

mappingType - either CAM, GM, or IM

agreementAlg - the agreement algorithm, either DH or ECDH

params - the static domain parameters

piccNonce - the received nonce from the PICC

Returns:

the computed ephemeral domain parameters

Throws:

PACEException - on error

doPACEStep2GM

public AlgorithmParameterSpec doPACEStep2GM(String agreementAlg,
                                            AlgorithmParameterSpec params,
                                            byte[] piccNonce)
                                     throws PACEException

Throws:

PACEException

doPACEStep2IM

public AlgorithmParameterSpec doPACEStep2IM(String agreementAlg,
                                            AlgorithmParameterSpec params,
                                            byte[] piccNonce)
                                     throws PACEException

Throws:

PACEException

doPACEStep3GenerateKeyPair

public KeyPair doPACEStep3GenerateKeyPair(String agreementAlg,
                                          AlgorithmParameterSpec ephemeralParams)
                                   throws PACEException

Throws:

PACEException

doPACEStep3ExchangePublicKeys

public PublicKey doPACEStep3ExchangePublicKeys(PublicKey pcdPublicKey,
                                               AlgorithmParameterSpec ephemeralParams)
                                        throws PACEException

Throws:

PACEException

doPACEStep3KeyAgreement

public byte[] doPACEStep3KeyAgreement(String agreementAlg,
                                      PrivateKey pcdPrivateKey,
                                      PublicKey piccPublicKey)
                               throws PACEException

Throws:

PACEException

doPACEStep4

public byte[] doPACEStep4(String oid,
                          PACEInfo.MappingType mappingType,
                          KeyPair pcdKeyPair,
                          PublicKey piccPublicKey,
                          SecretKey macKey)
                   throws PACEException

Throws:

PACEException

deriveStaticPACEKey

public static SecretKey deriveStaticPACEKey(KeySpec keySpec,
                                            String oid)
                                     throws GeneralSecurityException

Derives the static key K_pi.

Parameters:

keySpec - the key material from the MRZ

oid - the PACE object identifier is needed to determine the cipher algorithm and the key length

Returns:

the derived key

Throws:

GeneralSecurityException - on error

computeKeySeedForPACE

public static byte[] computeKeySeedForPACE(KeySpec keySpec)
                                    throws GeneralSecurityException

Throws:

GeneralSecurityException

generateAuthenticationToken

public static byte[] generateAuthenticationToken(String oid,
                                                 SecretKey macKey,
                                                 PublicKey publicKey)
                                          throws GeneralSecurityException

The authentication token SHALL be computed over a public key data object (cf. Section 4.5) containing the object identifier as indicated in MSE:Set AT (cf. Section 3.2.1), and the received ephemeral public key (i.e. excluding the domain parameters, cf. Section 4.5.3) using an authentication code and the key KS MAC derived from the key agreement.

Parameters:

oid - the object identifier as indicated in MSE Set AT

macKey - the KS MAC key derived from the key agreement

publicKey - the received public key

Returns:

the authentication code

Throws:

GeneralSecurityException - on error while performing the MAC operation