Package 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: 1805 $

Author:

The JMRTD team ([email protected])

Constructor Summary

Constructors

Constructor	Description
PACEProtocol(APDULevelPACECapable service, SecureMessagingWrapper wrapper, int maxTranceiveLength, boolean shouldCheckMAC)	Constructs a PACE protocol instance.

Method Summary

Modifier and Type	Method	Description
static byte[]	computeKeySeedForPACE(String cardAccessNumber)	Computes a key seed given a card access number (CAN).
static byte[]	computeKeySeedForPACE(AccessKeySpec accessKey)	Computes a key seed based on an access key.
static PublicKey	decodePublicKeyFromSmartCard(byte[] encodedPublicKey, AlgorithmParameterSpec params)	Decodes a public key received from the PICC.
static SecretKey	deriveStaticPACEKey(AccessKeySpec accessKey, String oid)	Derives the static key K_pi.
PACEResult	doPACE(AccessKeySpec accessKey, 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.
PACEMappingResult	doPACEStep2(PACEInfo.MappingType mappingType, String agreementAlg, AlgorithmParameterSpec params, byte[] piccNonce, Cipher staticPACECipher)	The second step in the PACE protocol computes ephemeral domain parameters by mapping the PICC generated nonce (and optionally the PCD generated nonce, which will be exchanged, in case of Integrated Mapping).
PACEGMMappingResult	doPACEStep2GM(String agreementAlg, AlgorithmParameterSpec params, byte[] piccNonce)	The second step in the PACE protocol (GM case) computes ephemeral domain parameters by performing a key agreement protocol with the PICC nonce as input.
PACEIMMappingResult	doPACEStep2IM(String agreementAlg, AlgorithmParameterSpec params, byte[] piccNonce, Cipher staticPACECipher)	The second step in the PACE protocol computes ephemeral domain parameters by performing a key agreement protocol with the PICC and PCD nonces as input.
PublicKey	doPACEStep3ExchangePublicKeys(PublicKey pcdPublicKey, AlgorithmParameterSpec ephemeralParams)	Sends the PCD's public key to the PICC and receives and interprets the PICC's public key in exchange.
KeyPair	doPACEStep3GenerateKeyPair(String agreementAlg, AlgorithmParameterSpec ephemeralParams)	Chooses a random ephemeral key pair.
byte[]	doPACEStep3KeyAgreement(String agreementAlg, PrivateKey pcdPrivateKey, PublicKey piccPublicKey)	Performs the key agreement.
byte[]	doPACEStep4(String oid, PACEInfo.MappingType mappingType, KeyPair pcdKeyPair, PublicKey piccPublicKey, SecretKey macKey)	Exchanges authentication tokens.
static byte[]	encodePublicKeyDataObject(String oid, PublicKey publicKey)	Based on TR-SAC 1.01 4.5.1 and 4.5.2.
static byte[]	encodePublicKeyDataObject(String oid, PublicKey publicKey, boolean isContextKnown)	Based on TR-SAC 1.01 4.5.1 and 4.5.2.
static byte[]	encodePublicKeyForSmartCard(PublicKey publicKey)	Write uncompressed coordinates (for EC) or public value (DH).
static byte[]	generateAuthenticationToken(String oid, SecretKey macKey, PublicKey publicKey)	Generates an authentication token.
static ECPoint	icartPointEncode(BigInteger t, ECParameterSpec params)	Icart's point encoding for Elliptic Curve over a prime field.
static DHParameterSpec	mapNonceGMWithDH(byte[] nonceS, BigInteger sharedSecretH, DHParameterSpec staticParameters)	Maps the nonce for the DH case using Generic Mapping to get new parameters (notably a new generator).
static ECParameterSpec	mapNonceGMWithECDH(byte[] nonceS, ECPoint sharedSecretPointH, ECParameterSpec staticParameters)	Maps the nonce for the ECDH case using Generic Mapping to get new parameters (notably a new generator).
static AlgorithmParameterSpec	mapNonceIMWithDH(byte[] nonceS, byte[] nonceT, String cipherAlgorithm, DHParameterSpec params)	Transforms the nonces using a pseudo random number function and maps the resulting value to a field element.
static AlgorithmParameterSpec	mapNonceIMWithECDH(byte[] nonceS, byte[] nonceT, String cipherAlgorithm, ECParameterSpec params)	Transforms the nonces using a pseudo random number function and maps the resulting value to a point on the curve.
static byte[]	pseudoRandomFunction(byte[] s, byte[] t, BigInteger p, String algorithm)	Pseudo random number function as specified in Doc 9303 - Part 11, 4.4.3.3.2.
static PublicKey	updateParameterSpec(PublicKey publicKey, PrivateKey privateKey)	Updates the parameters of the given public key to match the parameters of the given private key.

Methods inherited from class java.lang.Object

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

Constructor Detail

PACEProtocol

public PACEProtocol(APDULevelPACECapable service,
                    SecureMessagingWrapper wrapper,
                    int maxTranceiveLength,
                    boolean shouldCheckMAC)

Constructs a PACE protocol instance.

Parameters:

service - the service for sending APDUs

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

maxTranceiveLength - the maximal tranceive length (on responses to READ BINARY) to use in the resulting secure messaging channel

shouldCheckMAC - whether the resulting secure messaging channel should apply strict MAC checking on response APDUs

Method Detail

doPACE

public PACEResult doPACE(AccessKeySpec accessKey,
                         String oid,
                         AlgorithmParameterSpec params)
                  throws net.sf.scuba.smartcards.CardServiceException

Performs the PACE 2.0 / SAC protocol.

Parameters:

accessKey - the MRZ or CAN based access key

oid - as specified in the PACEInfo, indicates GM or IM or CAM, DH or ECDH, cipher, digest, length

params - explicit static domain parameters for DH or ECDH

Returns:

a PACE result

Throws:

net.sf.scuba.smartcards.CardServiceException - if authentication failed or on some lower-level 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 PACEMappingResult doPACEStep2(PACEInfo.MappingType mappingType,
                                     String agreementAlg,
                                     AlgorithmParameterSpec params,
                                     byte[] piccNonce,
                                     Cipher staticPACECipher)
                              throws PACEException

The second step in the PACE protocol computes ephemeral domain parameters by mapping the PICC generated nonce (and optionally the PCD generated nonce, which will be exchanged, in case of Integrated Mapping).

Parameters:

mappingType - either CAM, GM, or IM

agreementAlg - the agreement algorithm, either DH or ECDH

params - the static domain parameters

piccNonce - the nonce received from the PICC

staticPACECipher - the cipher to use in IM

Returns:

the newly computed ephemeral domain parameters

Throws:

PACEException - on error

doPACEStep2GM

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

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

Parameters:

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

doPACEStep2IM

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

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

Parameters:

agreementAlg - the agreement algorithm, either DH or ECDH

params - the static domain parameters

piccNonce - the received nonce from the PICC

staticPACECipher - the cipher to use for IM

Returns:

the computed ephemeral domain parameters

Throws:

PACEException - on error

doPACEStep3GenerateKeyPair

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

Chooses a random ephemeral key pair.

Parameters:

agreementAlg - the agreement algorithm

ephemeralParams - the parameters

Returns:

the key pair

Throws:

PACEException - on error

doPACEStep3ExchangePublicKeys

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

Sends the PCD's public key to the PICC and receives and interprets the PICC's public key in exchange.

Parameters:

pcdPublicKey - the PCD's public key

ephemeralParams - the ephemeral parameters to interpret the PICC's public key

Returns:

the PICC's public key

Throws:

PACEException - on error

doPACEStep3KeyAgreement

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

Performs the key agreement.

Parameters:

agreementAlg - the agreement algorithm, either "DH" or "ECDH"

pcdPrivateKey - the PCD's private key

piccPublicKey - the PICC's public key

Returns:

the shared secret

Throws:

PACEException - on error

doPACEStep4

public byte[] doPACEStep4(String oid,
                          PACEInfo.MappingType mappingType,
                          KeyPair pcdKeyPair,
                          PublicKey piccPublicKey,
                          SecretKey macKey)
                   throws net.sf.scuba.smartcards.CardServiceException

Exchanges authentication tokens.

Parameters:

oid - the object identifier

mappingType - the mapping type (GM or IM)

pcdKeyPair - the PCD's key pair

piccPublicKey - the PICC's public key

macKey - the MAC key to use

Returns:

possible encrypted chip authentication data (PACE-CAM case)

Throws:

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

deriveStaticPACEKey

public static SecretKey deriveStaticPACEKey(AccessKeySpec accessKey,
                                            String oid)
                                     throws GeneralSecurityException

Derives the static key K_pi.

Parameters:

accessKey - 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(AccessKeySpec accessKey)
                                    throws GeneralSecurityException

Computes a key seed based on an access key.

Parameters:

accessKey - the access key

Returns:

a key seed for secure messaging keys

Throws:

GeneralSecurityException - on error

mapNonceGMWithECDH

public static ECParameterSpec mapNonceGMWithECDH(byte[] nonceS,
                                                 ECPoint sharedSecretPointH,
                                                 ECParameterSpec staticParameters)

Maps the nonce for the ECDH case using Generic Mapping to get new parameters (notably a new generator).

Parameters:

nonceS - the nonce received from the PICC

sharedSecretPointH - the shared secret

staticParameters - the static parameters

Returns:

the new parameters

mapNonceGMWithDH

public static DHParameterSpec mapNonceGMWithDH(byte[] nonceS,
                                               BigInteger sharedSecretH,
                                               DHParameterSpec staticParameters)

Maps the nonce for the DH case using Generic Mapping to get new parameters (notably a new generator).

Parameters:

nonceS - the nonce received from the PICC

sharedSecretH - the shared secret point

staticParameters - the static parameters

Returns:

the new parameters

mapNonceIMWithECDH

public static AlgorithmParameterSpec mapNonceIMWithECDH(byte[] nonceS,
                                                        byte[] nonceT,
                                                        String cipherAlgorithm,
                                                        ECParameterSpec params)
                                                 throws GeneralSecurityException

Transforms the nonces using a pseudo random number function and maps the resulting value to a point on the curve. The resulting point is used as a generator as part of the returned domain parameters.

Parameters:

nonceS - the nonce from the PICC

nonceT - the nonce from the PCD

cipherAlgorithm - the cipher algorithm to be used by the pseudo random function (either "AES" or "DESede")

params - the static domain parameters

Returns:

the newly computed domain parameters

Throws:

GeneralSecurityException - on error

mapNonceIMWithDH

public static AlgorithmParameterSpec mapNonceIMWithDH(byte[] nonceS,
                                                      byte[] nonceT,
                                                      String cipherAlgorithm,
                                                      DHParameterSpec params)
                                               throws GeneralSecurityException

Transforms the nonces using a pseudo random number function and maps the resulting value to a field element. The resulting field element is used as a generator as part of the returned domain parameters.

Parameters:

nonceS - the nonce from the PICC

nonceT - the nonce from the PCD

cipherAlgorithm - the cipher algorithm to be used by the pseudo random function (either "AES" or "DESede")

params - the static domain parameters

Returns:

the newly computed domain parameters

Throws:

GeneralSecurityException - on error

pseudoRandomFunction

public static byte[] pseudoRandomFunction(byte[] s,
                                          byte[] t,
                                          BigInteger p,
                                          String algorithm)
                                   throws GeneralSecurityException

Pseudo random number function as specified in Doc 9303 - Part 11, 4.4.3.3.2. Used in PACE IM.

Parameters:

s - the nonce that was sent by the ICC

t - the nonce that was generated by the PCD

p - the order of the prime field

algorithm - the algorithm for block cipher E (either "AES" or "DESede")

Returns:

the resulting x

Throws:

GeneralSecurityException - on cryptographic error

icartPointEncode

public static ECPoint icartPointEncode(BigInteger t,
                                       ECParameterSpec params)

Icart's point encoding for Elliptic Curve over a prime field. This maps a field element to a point on the curve. Used in PACE IM ECDH.

Parameters:

t - the field element to encode

params - the parameters describing the curve and field

Returns:

the point on the curve that the input is mapped to

updateParameterSpec

public static PublicKey updateParameterSpec(PublicKey publicKey,
                                            PrivateKey privateKey)
                                     throws GeneralSecurityException

Updates the parameters of the given public key to match the parameters of the given private key.

Parameters:

publicKey - the public key, should be an EC public key

privateKey - the private key, should be an EC private key

Returns:

a new public key that uses the parameters of the private key

Throws:

GeneralSecurityException - on security error, or when keys are not EC

generateAuthenticationToken

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

Generates an authentication token. 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

computeKeySeedForPACE

public static byte[] computeKeySeedForPACE(String cardAccessNumber)
                                    throws GeneralSecurityException

Computes a key seed given a card access number (CAN).

Parameters:

cardAccessNumber - the card access number

Returns:

a key seed for deriving secure messaging keys

Throws:

GeneralSecurityException - on error

encodePublicKeyDataObject

public static byte[] encodePublicKeyDataObject(String oid,
                                               PublicKey publicKey)
                                        throws InvalidKeyException

Based on TR-SAC 1.01 4.5.1 and 4.5.2. For signing authentication token, not for sending to smart card. Assumes context is known.

Parameters:

oid - object identifier

publicKey - public key

Returns:

encoded public key data object for signing as authentication token

Throws:

InvalidKeyException - when public key is not DH or EC

encodePublicKeyDataObject

public static byte[] encodePublicKeyDataObject(String oid,
                                               PublicKey publicKey,
                                               boolean isContextKnown)
                                        throws InvalidKeyException

Based on TR-SAC 1.01 4.5.1 and 4.5.2. For signing authentication token, not for sending to smart card.

Parameters:

oid - object identifier

publicKey - public key

isContextKnown - whether context of public key is known to receiver (we will not include domain parameters in that case).

Returns:

encoded public key data object for signing as authentication token

Throws:

InvalidKeyException - when public key is not DH or EC

encodePublicKeyForSmartCard

public static byte[] encodePublicKeyForSmartCard(PublicKey publicKey)
                                          throws InvalidKeyException

Write uncompressed coordinates (for EC) or public value (DH).

Parameters:

publicKey - public key

Returns:

encoding for smart card

Throws:

InvalidKeyException - if the key type is not EC or DH

decodePublicKeyFromSmartCard

public static PublicKey decodePublicKeyFromSmartCard(byte[] encodedPublicKey,
                                                     AlgorithmParameterSpec params)

Decodes a public key received from the PICC.

Parameters:

encodedPublicKey - the encoded public key that was received

params - the parameters used for interpreting the public key

Returns:

the decoded public key object