org.jmrtd

Class Util

java.lang.Object

org.jmrtd.Util

Deprecated.

The visibility of this class will be changed to package.

public class Util
extends java.lang.Object

Some static helper functions. Mostly dealing with low-level crypto.

Version:

$Revision: 1583 $

Author:

Wojciech Mostowski, Cees-Bart Breunesse ([email protected]), Engelbert Hubbers ([email protected]), Martijn Oostdijk ([email protected]), Ronny Wichers Schreur ([email protected])

Field Summary

Fields

Modifier and Type	Field and Description
static int	ENC_MODE Deprecated. Mode for KDF.
static int	MAC_MODE Deprecated. Mode for KDF.
static int	PACE_MODE Deprecated. Mode for KDF.

Method Summary

Modifier and Type	Method and Description
static byte[]	alignKeyDataToSize(byte[] keyData, int size) Deprecated.
static java.math.BigInteger	computeAffineY(java.math.BigInteger affineX, java.security.spec.ECParameterSpec params) Deprecated. This just solves the curve equation for y.
static byte[]	computeKeySeed(java.lang.String documentNumber, java.lang.String dateOfBirth, java.lang.String dateOfExpiry, java.lang.String digestAlg, boolean doTruncate) Deprecated. Computes the static key seed, based on information from the MRZ.
static byte[]	computeKeySeedForBAC(java.lang.String documentNumber, java.lang.String dateOfBirth, java.lang.String dateOfExpiry) Deprecated. Computes the static key seed to be used in BAC KDF, based on information from the MRZ.
static byte[]	computeKeySeedForPACE(java.lang.String documentNumber, java.lang.String dateOfBirth, java.lang.String dateOfExpiry) Deprecated. Computes the static key seed to be used in PACE KDF, based on information from the MRZ.
static long	computeSendSequenceCounter(byte[] rndICC, byte[] rndIFD) Deprecated.
static java.security.PublicKey	decodePublicKeyFromSmartCard(byte[] encodedPublicKey, java.security.spec.AlgorithmParameterSpec params) Deprecated.
static javax.crypto.SecretKey	deriveKey(byte[] keySeed, int mode) Deprecated. Derives the ENC or MAC key for BAC from the keySeed.
static javax.crypto.SecretKey	deriveKey(byte[] keySeed, java.lang.String cipherAlg, int keyLength, byte[] nonce, int counter) Deprecated. Derives a shared key.
static javax.crypto.SecretKey	deriveKey(byte[] keySeed, java.lang.String cipherAlgName, int keyLength, int mode) Deprecated. Derives the ENC or MAC key for BAC or PACE
static byte[]	encodePublicKeyDataObject(java.lang.String oid, java.security.PublicKey publicKey) Deprecated. Based on TR-SAC 1.01 4.5.1 and 4.5.2.
static byte[]	encodePublicKeyDataObject(java.lang.String oid, java.security.PublicKey publicKey, boolean isContextKnown) Deprecated. Based on TR-SAC 1.01 4.5.1 and 4.5.2.
static byte[]	encodePublicKeyForSmartCard(java.security.PublicKey publicKey) Deprecated. Write uncompressed coordinates (for EC) or public value (DH).
static byte[]	generateAuthenticationToken(java.lang.String oid, javax.crypto.SecretKey macKey, java.security.PublicKey publicKey) Deprecated. The authentication token SHALL be computed over a public key data object (cf.
static java.lang.String	getCurveName(java.security.spec.ECParameterSpec params) Deprecated. Gets the curve name if known (or null).
static java.lang.String	getDetailedPublicKeyAlgorithm(java.security.PublicKey publicKey) Deprecated. The public key algorithm (like RSA or) with some extra information (like 1024 bits).
static java.math.BigInteger	getPrime(java.security.spec.AlgorithmParameterSpec params) Deprecated.
static byte[]	getRawECDSASignature(byte[] signedData, int keySize) Deprecated. For ECDSA the EAC 1.11 specification requires the signature to be stripped down from any ASN.1 wrappers, as so.
static byte[]	i2os(java.math.BigInteger val) Deprecated. Converts an integer to an octet string.
static byte[]	i2os(java.math.BigInteger val, int length) Deprecated. Converts an integer to an octet string.
static java.lang.String	inferDigestAlgorithmFromCipherAlgorithmForKeyDerivation(java.lang.String cipherAlg, int keyLength) Deprecated.
static java.lang.String	inferDigestAlgorithmFromSignatureAlgorithm(java.lang.String signatureAlgorithm) Deprecated. Infers a digest algorithm mnemonic from a signature algorithm mnemonic.
static java.lang.String	inferKeyAgreementAlgorithm(java.security.PublicKey publicKey) Deprecated.
static java.lang.String	inferMacAlgorithmFromCipherAlgorithm(java.lang.String cipherAlg) Deprecated.
static java.lang.String	inferProtocolIdentifier(java.security.PublicKey publicKey) Deprecated. Infer an EAC object identifier for an EC or DH public key.
static boolean	isValid(java.security.spec.ECPoint ecPoint, java.security.spec.ECParameterSpec params) Deprecated.
static java.security.spec.AlgorithmParameterSpec	mapNonceGM(byte[] nonceS, byte[] sharedSecretH, java.security.spec.AlgorithmParameterSpec params) Deprecated.
static java.security.spec.AlgorithmParameterSpec	mapNonceIM(byte[] nonceS, byte[] nonceT, byte[] sharedSecretH, java.security.spec.AlgorithmParameterSpec params) Deprecated.
static java.security.spec.ECPoint	multiply(java.math.BigInteger s, java.security.spec.ECPoint point, java.security.spec.ECParameterSpec params) Deprecated.
static java.security.spec.ECPoint	normalize(java.security.spec.ECPoint ecPoint, java.security.spec.ECParameterSpec params) Deprecated.
static java.math.BigInteger	os2fe(byte[] bytes, java.math.BigInteger p) Deprecated. Convert an octet string to field element via OS2FE as specified in BSI TR-03111.
static java.math.BigInteger	os2i(byte[] bytes) Deprecated. Converts an octet string to an integer.
static java.math.BigInteger	os2i(byte[] bytes, int offset, int length) Deprecated. Converts an octet string to an integer.
static byte[]	padWithCAN(byte[] in, int blockSize) Deprecated.
static byte[]	padWithCAN(byte[] in, int offset, int length, int blockSize) Deprecated.
static byte[]	padWithMRZ(byte[] in) Deprecated. Pads the input in according to ISO9797-1 padding method 2.
static byte[]	padWithMRZ(byte[] in, int offset, int length) Deprecated.
static byte[]	publicKeyECPointToOS(java.security.spec.ECPoint point) Deprecated. Encode an EC public key point.
static java.security.PublicKey	reconstructPublicKey(java.security.PublicKey publicKey) Deprecated. Reconstructs the public key to use explicit domain params for EC public keys
static byte[]	recoverMessage(int digestLength, byte[] plaintext) Deprecated. Recovers the M1 part of the message sent back by the AA protocol (INTERNAL AUTHENTICATE command).
static org.bouncycastle.jce.spec.ECNamedCurveSpec	toECNamedCurveSpec(org.bouncycastle.jce.spec.ECNamedCurveParameterSpec namedParamSpec) Deprecated. Translates internal BC named curve spec to BC provided JCA compliant named curve spec.
static javax.crypto.spec.DHParameterSpec	toExplicitDHParameterSpec(org.bouncycastle.crypto.params.DHParameters params) Deprecated.
static java.security.spec.ECParameterSpec	toExplicitECParameterSpec(org.bouncycastle.jce.spec.ECNamedCurveParameterSpec parameterSpec) Deprecated.
static java.security.spec.ECParameterSpec	toExplicitECParameterSpec(java.security.spec.ECParameterSpec params) Deprecated. Translates (named) curve spec to JCA compliant explicit param spec.
static java.security.PublicKey	toPublicKey(org.bouncycastle.asn1.x509.SubjectPublicKeyInfo subjectPublicKeyInfo) Deprecated.
static org.bouncycastle.asn1.x509.SubjectPublicKeyInfo	toSubjectPublicKeyInfo(java.security.PublicKey publicKey) Deprecated.
static byte[]	unpad(byte[] in) Deprecated.
static byte[]	unwrapDO(byte expectedTag, byte[] wrappedData) Deprecated.
static byte[]	wrapDO(byte tag, byte[] data) Deprecated.

Methods inherited from class java.lang.Object

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

Field Detail

ENC_MODE

public static final int ENC_MODE

Deprecated.

Mode for KDF.

See Also:

Constant Field Values

MAC_MODE

public static final int MAC_MODE

Deprecated.

Mode for KDF.

See Also:

Constant Field Values

PACE_MODE

public static final int PACE_MODE

Deprecated.

Mode for KDF.

See Also:

Constant Field Values

Method Detail

deriveKey

public static javax.crypto.SecretKey deriveKey(byte[] keySeed,
                                               int mode)
                                        throws java.security.GeneralSecurityException

Deprecated.

Derives the ENC or MAC key for BAC from the keySeed.

Parameters:

keySeed - the key seed.

mode - either ENC_MODE or MAC_MODE

Returns:

the key

Throws:

java.security.GeneralSecurityException - on security error

deriveKey

public static javax.crypto.SecretKey deriveKey(byte[] keySeed,
                                               java.lang.String cipherAlgName,
                                               int keyLength,
                                               int mode)
                                        throws java.security.GeneralSecurityException

Deprecated.

Derives the ENC or MAC key for BAC or PACE

Parameters:

keySeed - the key seed.

cipherAlgName - either AES or DESede

keyLength - key length in bits

mode - either ENC_MODE or MAC_MODE

Returns:

the key.

Throws:

java.security.GeneralSecurityException - on security error

deriveKey

public static javax.crypto.SecretKey deriveKey(byte[] keySeed,
                                               java.lang.String cipherAlg,
                                               int keyLength,
                                               byte[] nonce,
                                               int counter)
                                        throws java.security.GeneralSecurityException

Deprecated.

Derives a shared key.

Parameters:

keySeed - the shared secret, as octets

cipherAlg - in Java mnemonic notation (for example "DESede", "AES")

keyLength - length in bits

nonce - optional nonce or null

counter - counter or mode

Returns:

the derived key

Throws:

java.security.GeneralSecurityException - if something went wrong

computeKeySeedForBAC

public static byte[] computeKeySeedForBAC(java.lang.String documentNumber,
                                          java.lang.String dateOfBirth,
                                          java.lang.String dateOfExpiry)
                                   throws java.security.GeneralSecurityException

Deprecated.

Computes the static key seed to be used in BAC KDF, based on information from the MRZ.

Parameters:

documentNumber - a string containing the document number

dateOfBirth - a string containing the date of birth (YYMMDD)

dateOfExpiry - a string containing the date of expiry (YYMMDD)

Returns:

a byte array of length 16 containing the key seed

Throws:

java.security.GeneralSecurityException - on security error

computeKeySeedForPACE

public static byte[] computeKeySeedForPACE(java.lang.String documentNumber,
                                           java.lang.String dateOfBirth,
                                           java.lang.String dateOfExpiry)
                                    throws java.security.GeneralSecurityException

Deprecated.

Computes the static key seed to be used in PACE KDF, based on information from the MRZ.

Parameters:

documentNumber - a string containing the document number

dateOfBirth - a string containing the date of birth (YYMMDD)

dateOfExpiry - a string containing the date of expiry (YYMMDD)

Returns:

a byte array of length 16 containing the key seed

Throws:

java.security.GeneralSecurityException - on security error

computeKeySeed

public static byte[] computeKeySeed(java.lang.String documentNumber,
                                    java.lang.String dateOfBirth,
                                    java.lang.String dateOfExpiry,
                                    java.lang.String digestAlg,
                                    boolean doTruncate)
                             throws java.security.GeneralSecurityException

Deprecated.

Computes the static key seed, based on information from the MRZ.

Parameters:

documentNumber - a string containing the document number

dateOfBirth - a string containing the date of birth (YYMMDD)

dateOfExpiry - a string containing the date of expiry (YYMMDD)

digestAlg - a Java mnemonic algorithm string to indicate the digest algorithm (typically SHA-1)

doTruncate - whether to truncate the resulting output to 16 bytes

Returns:

a byte array of length 16 containing the key seed

Throws:

java.security.GeneralSecurityException - on security error

padWithMRZ

public static byte[] padWithMRZ(byte[] in)

Deprecated.

Pads the input in according to ISO9797-1 padding method 2.

Parameters:

in - input

Returns:

padded output

padWithCAN

public static byte[] padWithCAN(byte[] in,
                                int blockSize)

Deprecated.

padWithMRZ

public static byte[] padWithMRZ(byte[] in,
                                int offset,
                                int length)

Deprecated.

padWithCAN

public static byte[] padWithCAN(byte[] in,
                                int offset,
                                int length,
                                int blockSize)

Deprecated.

computeSendSequenceCounter

public static long computeSendSequenceCounter(byte[] rndICC,
                                              byte[] rndIFD)

Deprecated.

unpad

public static byte[] unpad(byte[] in)
                    throws javax.crypto.BadPaddingException

Deprecated.

Throws:

javax.crypto.BadPaddingException

recoverMessage

public static byte[] recoverMessage(int digestLength,
                                    byte[] plaintext)

Deprecated.

Recovers the M1 part of the message sent back by the AA protocol (INTERNAL AUTHENTICATE command). The algorithm is described in ISO 9796-2:2002 9.3. Based on code by Ronny ([email protected]) who presumably ripped this from Bouncy Castle.

Parameters:

digestLength - should be 20

plaintext - response from card, already 'decrypted' (using the AA public key)

Returns:

the m1 part of the message

getRawECDSASignature

public static byte[] getRawECDSASignature(byte[] signedData,
                                          int keySize)
                                   throws java.io.IOException

Deprecated.

For ECDSA the EAC 1.11 specification requires the signature to be stripped down from any ASN.1 wrappers, as so.

Parameters:

signedData - signed data

keySize - key size

Returns:

signature without wrappers

Throws:

java.io.IOException - on error

alignKeyDataToSize

public static byte[] alignKeyDataToSize(byte[] keyData,
                                        int size)

Deprecated.

i2os

public static byte[] i2os(java.math.BigInteger val,
                          int length)

Deprecated.

Converts an integer to an octet string. Based on BSI TR 03111 Section 3.1.2.

Parameters:

val - positive integer

length - length

Returns:

octet string

i2os

public static byte[] i2os(java.math.BigInteger val)

Deprecated.

Converts an integer to an octet string.

Parameters:

val - positive integer

Returns:

octet string

os2i

public static java.math.BigInteger os2i(byte[] bytes)

Deprecated.

Converts an octet string to an integer. Based on BSI TR 03111 Section 3.1.2.

Parameters:

bytes - octet string

Returns:

positive integer

os2i

public static java.math.BigInteger os2i(byte[] bytes,
                                        int offset,
                                        int length)

Deprecated.

Converts an octet string to an integer. Based on BSI TR 03111 Section 3.1.2.

Parameters:

bytes - octet string

offset - offset of octet string

length - length of octet string

Returns:

positive integer

os2fe

public static java.math.BigInteger os2fe(byte[] bytes,
                                         java.math.BigInteger p)

Deprecated.

Convert an octet string to field element via OS2FE as specified in BSI TR-03111.

Parameters:

bytes - octet string

p - modulus

Returns:

positive integer

publicKeyECPointToOS

public static byte[] publicKeyECPointToOS(java.security.spec.ECPoint point)

Deprecated.

Encode an EC public key point. Prefixes a 0x04 (without a length).

Parameters:

point - public key point

Returns:

an octet string

inferDigestAlgorithmFromSignatureAlgorithm

public static java.lang.String inferDigestAlgorithmFromSignatureAlgorithm(java.lang.String signatureAlgorithm)

Deprecated.

Infers a digest algorithm mnemonic from a signature algorithm mnemonic.

Parameters:

signatureAlgorithm - a signature algorithm

Returns:

a digest algorithm, or null if inference failed

inferDigestAlgorithmFromCipherAlgorithmForKeyDerivation

public static java.lang.String inferDigestAlgorithmFromCipherAlgorithmForKeyDerivation(java.lang.String cipherAlg,
                                                                                       int keyLength)

Deprecated.

toExplicitDHParameterSpec

public static javax.crypto.spec.DHParameterSpec toExplicitDHParameterSpec(org.bouncycastle.crypto.params.DHParameters params)

Deprecated.

getDetailedPublicKeyAlgorithm

public static java.lang.String getDetailedPublicKeyAlgorithm(java.security.PublicKey publicKey)

Deprecated.

The public key algorithm (like RSA or) with some extra information (like 1024 bits).

Parameters:

publicKey - a public key

Returns:

the algorithm

getCurveName

public static java.lang.String getCurveName(java.security.spec.ECParameterSpec params)

Deprecated.

Gets the curve name if known (or null).

Parameters:

params - an specification of the curve

Returns:

the name

toExplicitECParameterSpec

public static java.security.spec.ECParameterSpec toExplicitECParameterSpec(org.bouncycastle.jce.spec.ECNamedCurveParameterSpec parameterSpec)

Deprecated.

toExplicitECParameterSpec

public static java.security.spec.ECParameterSpec toExplicitECParameterSpec(java.security.spec.ECParameterSpec params)

Deprecated.

Translates (named) curve spec to JCA compliant explicit param spec.

Parameters:

params - an EC parameter spec, possibly named

Returns:

another spec not name based

toECNamedCurveSpec

public static org.bouncycastle.jce.spec.ECNamedCurveSpec toECNamedCurveSpec(org.bouncycastle.jce.spec.ECNamedCurveParameterSpec namedParamSpec)

Deprecated.

Translates internal BC named curve spec to BC provided JCA compliant named curve spec.

Parameters:

namedParamSpec - a named EC parameter spec

Returns:

a JCA compliant named EC parameter spec

toSubjectPublicKeyInfo

public static org.bouncycastle.asn1.x509.SubjectPublicKeyInfo toSubjectPublicKeyInfo(java.security.PublicKey publicKey)

Deprecated.

toPublicKey

public static java.security.PublicKey toPublicKey(org.bouncycastle.asn1.x509.SubjectPublicKeyInfo subjectPublicKeyInfo)

Deprecated.

reconstructPublicKey

public static java.security.PublicKey reconstructPublicKey(java.security.PublicKey publicKey)

Deprecated.

Reconstructs the public key to use explicit domain params for EC public keys

Parameters:

publicKey - the public key

Returns:

the same public key (if not EC or error), or a reconstructed one (if EC)

encodePublicKeyDataObject

public static byte[] encodePublicKeyDataObject(java.lang.String oid,
                                               java.security.PublicKey publicKey)
                                        throws java.security.InvalidKeyException

Deprecated.

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:

java.security.InvalidKeyException - when public key is not DH or EC

encodePublicKeyDataObject

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

Deprecated.

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:

java.security.InvalidKeyException - when public key is not DH or EC

encodePublicKeyForSmartCard

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

Deprecated.

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

Parameters:

publicKey - public key

Returns:

encoding for smart card

Throws:

java.security.InvalidKeyException - if the key type is not EC or DH

decodePublicKeyFromSmartCard

public static java.security.PublicKey decodePublicKeyFromSmartCard(byte[] encodedPublicKey,
                                                                   java.security.spec.AlgorithmParameterSpec params)

Deprecated.

inferMacAlgorithmFromCipherAlgorithm

public static java.lang.String inferMacAlgorithmFromCipherAlgorithm(java.lang.String cipherAlg)
                                                             throws java.security.InvalidAlgorithmParameterException

Deprecated.

Throws:

java.security.InvalidAlgorithmParameterException

generateAuthenticationToken

public static byte[] generateAuthenticationToken(java.lang.String oid,
                                                 javax.crypto.SecretKey macKey,
                                                 java.security.PublicKey publicKey)
                                          throws java.security.GeneralSecurityException

Deprecated.

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:

java.security.GeneralSecurityException - on error while performing the MAC operation

inferProtocolIdentifier

public static java.lang.String inferProtocolIdentifier(java.security.PublicKey publicKey)

Deprecated.

Infer an EAC object identifier for an EC or DH public key.

Parameters:

publicKey - a public key

Returns:

either ID_PK_ECDH or ID_PK_DH

mapNonceGM

public static java.security.spec.AlgorithmParameterSpec mapNonceGM(byte[] nonceS,
                                                                   byte[] sharedSecretH,
                                                                   java.security.spec.AlgorithmParameterSpec params)

Deprecated.

mapNonceIM

public static java.security.spec.AlgorithmParameterSpec mapNonceIM(byte[] nonceS,
                                                                   byte[] nonceT,
                                                                   byte[] sharedSecretH,
                                                                   java.security.spec.AlgorithmParameterSpec params)

Deprecated.

multiply

public static java.security.spec.ECPoint multiply(java.math.BigInteger s,
                                                  java.security.spec.ECPoint point,
                                                  java.security.spec.ECParameterSpec params)

Deprecated.

getPrime

public static java.math.BigInteger getPrime(java.security.spec.AlgorithmParameterSpec params)

Deprecated.

wrapDO

public static byte[] wrapDO(byte tag,
                            byte[] data)

Deprecated.

unwrapDO

public static byte[] unwrapDO(byte expectedTag,
                              byte[] wrappedData)

Deprecated.

inferKeyAgreementAlgorithm

public static java.lang.String inferKeyAgreementAlgorithm(java.security.PublicKey publicKey)

Deprecated.

computeAffineY

public static java.math.BigInteger computeAffineY(java.math.BigInteger affineX,
                                                  java.security.spec.ECParameterSpec params)

Deprecated.

This just solves the curve equation for y.

Parameters:

affineX - the x coord of a point on the curve

params - EC parameters for curve over Fp

Returns:

the corresponding y coord

isValid

public static boolean isValid(java.security.spec.ECPoint ecPoint,
                              java.security.spec.ECParameterSpec params)

Deprecated.

normalize

public static java.security.spec.ECPoint normalize(java.security.spec.ECPoint ecPoint,
                                                   java.security.spec.ECParameterSpec params)

Deprecated.