Package org.jmrtd

Class Util


  • public final class Util
    extends Object
    Some static helper functions. Mostly dealing with low-level crypto.
    Version:
    $Revision: 1803 $
    Author:
    The JMRTD team ([email protected])
    • Method Detail

      • getBouncyCastleProvider

        public static Provider getBouncyCastleProvider()
        Returns the BC provider, if present.
        Returns:
        the BC provider, the SC provider, or null
      • deriveKey

        public static SecretKey deriveKey​(byte[] keySeed,
                                          int mode)
                                   throws GeneralSecurityException
        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:
        GeneralSecurityException - on security error
      • deriveKey

        public static SecretKey deriveKey​(byte[] keySeed,
                                          String cipherAlgName,
                                          int keyLength,
                                          int mode)
                                   throws GeneralSecurityException
        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, MAC_MODE, or PACE_MODE
        Returns:
        the key.
        Throws:
        GeneralSecurityException - on security error
      • deriveKey

        public static SecretKey deriveKey​(byte[] keySeed,
                                          String cipherAlg,
                                          int keyLength,
                                          byte[] nonce,
                                          int mode)
                                   throws GeneralSecurityException
        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
        mode - the mode either ENC, MAC, or PACE mode
        Returns:
        the derived key
        Throws:
        GeneralSecurityException - if something went wrong
      • deriveKey

        public static SecretKey deriveKey​(byte[] keySeed,
                                          String cipherAlg,
                                          int keyLength,
                                          byte[] nonce,
                                          int mode,
                                          byte paceKeyReference)
                                   throws GeneralSecurityException
        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
        mode - the mode either ENC, MAC, or PACE mode
        paceKeyReference - Key Reference For Pace Protocol
        Returns:
        the derived key
        Throws:
        GeneralSecurityException - if something went wrong
      • computeKeySeed

        public static byte[] computeKeySeed​(String documentNumber,
                                            String dateOfBirth,
                                            String dateOfExpiry,
                                            String digestAlg,
                                            boolean doTruncate)
                                     throws GeneralSecurityException
        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:
        GeneralSecurityException - on security error
      • computeKeySeed

        public static byte[] computeKeySeed​(String cardAccessNumber,
                                            String digestAlg,
                                            boolean doTruncate)
                                     throws GeneralSecurityException
        Computes the key seed from a card access number (CAN) to derive secure messaging keys from.
        Parameters:
        cardAccessNumber - the card access number
        digestAlg - the digest algorithm to use
        doTruncate - whether to truncate to 16 bytes or not
        Returns:
        the resulting key seed
        Throws:
        GeneralSecurityException - on error
      • pad

        public static byte[] pad​(byte[] in,
                                 int blockSize)
        Pads the input in according to ISO9797-1 padding method 2, using the given block size.
        Parameters:
        in - input
        blockSize - the block size
        Returns:
        padded bytes
      • pad

        public static byte[] pad​(byte[] bytes,
                                 int offset,
                                 int length,
                                 int blockSize)
        Pads the input bytes indicated by offset and length according to ISO9797-1 padding method 2, using the given block size in blockSize.
        Parameters:
        bytes - input
        offset - the offset
        length - the length
        blockSize - the block size
        Returns:
        padded bytes
      • unpad

        public static byte[] unpad​(byte[] bytes)
                            throws BadPaddingException
        Unpads the input bytes according to ISO9797-1 padding method 2.
        Parameters:
        bytes - the input
        Returns:
        the unpadded bytes
        Throws:
        BadPaddingException - on padding exception
      • recoverMessage

        public static byte[] recoverMessage​(int digestLength,
                                            byte[] decryptedResponse)
        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.
        Parameters:
        digestLength - should be 20
        decryptedResponse - 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 IOException
        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:
        IOException - on error
      • alignKeyDataToSize

        public static byte[] alignKeyDataToSize​(byte[] keyData,
                                                int size)
        Align the given key data.
        Parameters:
        keyData - the key data
        size - the new size
        Returns:
        a byte array with key data
      • i2os

        public static byte[] i2os​(BigInteger val,
                                  int length)
        Converts an integer to an octet string. Based on BSI TR 03111 Section 3.1.2.
        Parameters:
        val - a non-negative integer
        length - the desired length of the octet string
        Returns:
        octet string
      • i2os

        public static byte[] i2os​(BigInteger val)
        Converts a non-negative integer to an octet string.
        Parameters:
        val - non-negative integer
        Returns:
        the octet string
      • os2i

        public static BigInteger os2i​(byte[] bytes)
        Converts an octet string to an integer. Based on BSI TR 03111 Section 3.1.2.
        Parameters:
        bytes - octet string
        Returns:
        a non-negative integer
      • os2i

        public static BigInteger os2i​(byte[] bytes,
                                      int offset,
                                      int length)
        Converts an octet string to an integer. Based on BSI TR 03111 Section 3.1.2.
        Parameters:
        bytes - a byte array containing the octet string
        offset - the offset of the octet string within the given byte array
        length - the length of the octet string
        Returns:
        a non-negative integer
      • os2fe

        public static BigInteger os2fe​(byte[] bytes,
                                       BigInteger p)
        Converts an octet string to a field element via OS2FE as specified in BSI TR-03111.
        Parameters:
        bytes - octet string
        p - the modulus
        Returns:
        a non-negative integer modulo p
      • inferDigestAlgorithmFromSignatureAlgorithm

        public static String inferDigestAlgorithmFromSignatureAlgorithm​(String signatureAlgorithm)
        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 String inferDigestAlgorithmFromCipherAlgorithmForKeyDerivation​(String cipherAlg,
                                                                                     int keyLength)
        Infers a digest algorithm mnemonic from a signature algorithm mnemonic for use in key derivation.
        Parameters:
        cipherAlg - a cipher algorithm
        keyLength - the key length
        Returns:
        a (best effort approximation) digest algorithm that is typically used in conjunction with the given cipher algorithm and key length, or null if inference failed
      • toExplicitDHParameterSpec

        public static DHParameterSpec toExplicitDHParameterSpec​(DHParameters params)
        Returns a Difie-Hellman parameter specification which includes the prime order of the subgroup generated by the generator if this information is available in the given (Bouncy Castle) parameters.
        Parameters:
        params - parameters for Diffie-Hellman as a Bouncy Castle specific object.
        Returns:
        a JCE Diffie-Hellman parameter specification
      • getDetailedPublicKeyAlgorithm

        public static String getDetailedPublicKeyAlgorithm​(PublicKey publicKey)
        Returns detailed information about the given public key (like RSA or) with some extra information (like 1024 bits).
        Parameters:
        publicKey - a public key
        Returns:
        the algorithm
      • getDetailedPrivateKeyAlgorithm

        public static String getDetailedPrivateKeyAlgorithm​(PrivateKey privateKey)
        Returns detailed algorithm information (including key length) about the given private key.
        Parameters:
        privateKey - a private key
        Returns:
        detailed information about the given private key
      • getCurveName

        public static String getCurveName​(ECParameterSpec params)
        Returns the curve name, if known, or null.
        Parameters:
        params - an specification of the curve
        Returns:
        the curve name
      • toExplicitECParameterSpec

        public static ECParameterSpec toExplicitECParameterSpec​(ECNamedCurveParameterSpec parameterSpec)
        Translates (named) curve specification to JCA compliant explicit parameter specification.
        Parameters:
        parameterSpec - a BC named curve parameter specification
        Returns:
        a JCA compliant explicit parameter specification
      • toExplicitECParameterSpec

        public static ECParameterSpec toExplicitECParameterSpec​(ECParameterSpec params)
        Translates (named) curve specification to JCA compliant explicit param specification.
        Parameters:
        params - an EC parameter specification, possibly named
        Returns:
        another specification not name based
      • toECNamedCurveSpec

        public static ECNamedCurveSpec toECNamedCurveSpec​(ECNamedCurveParameterSpec namedParamSpec)
        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 SubjectPublicKeyInfo toSubjectPublicKeyInfo​(PublicKey publicKey)
        Convert the given JCA compliant public key to a BC subject public key info structure.
        Parameters:
        publicKey - a public key
        Returns:
        a BC subject public key info structure
      • toPublicKey

        public static PublicKey toPublicKey​(SubjectPublicKeyInfo subjectPublicKeyInfo)
        Extracts a public key from a BC subject public key info structure.
        Parameters:
        subjectPublicKeyInfo - the BC subject public key info structure
        Returns:
        a public key or null
      • reconstructPublicKey

        public static PublicKey reconstructPublicKey​(PublicKey publicKey)
        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)
      • os2ECPoint

        public static ECPoint os2ECPoint​(byte[] encodedECPoint)
        Decodes an EC point from a BSI encoded octet string.
        Parameters:
        encodedECPoint - the encoded EC point
        Returns:
        the EC point
      • ecPoint2OS

        public static byte[] ecPoint2OS​(ECPoint point)
        Encodes (using BSI encoding) an EC point (for use as public key value). Prefixes a 0x04 (without a length).
        Parameters:
        point - an EC Point
        Returns:
        an octet string
      • inferProtocolIdentifier

        public static String inferProtocolIdentifier​(PublicKey publicKey)
        Infers 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
      • add

        public static ECPoint add​(ECPoint x,
                                  ECPoint y,
                                  ECParameterSpec params)
        Adds two EC points.
        Parameters:
        x - an EC point
        y - another EC point
        params - the domain parameters
        Returns:
        the resulting EC point
      • multiply

        public static ECPoint multiply​(BigInteger s,
                                       ECPoint point,
                                       ECParameterSpec params)
        Multiplies a scalar and an EC point.
        Parameters:
        s - the scalar
        point - the EC point
        params - the domain parameters
        Returns:
        the resulting EC point
      • getBytes

        public static byte[] getBytes​(String str)
        Converts a string to bytes using UTF-8.
        Parameters:
        str - a string
        Returns:
        the bytes
      • getPrime

        public static BigInteger getPrime​(AlgorithmParameterSpec params)
        Extracts the prime from the given DH or ECDH parameter specification which (hopefully) specifies a curve over a prime field. (This will throw an IllegalArgumentException for non-prime fields.)
        Parameters:
        params - a parameter specification
        Returns:
        the prime
      • inferKeyAgreementAlgorithm

        public static String inferKeyAgreementAlgorithm​(PublicKey publicKey)
        Attempts to infer a relevant key agreement algorithm (either "DH" or "ECDH") given a public key.
        Parameters:
        publicKey - the public key
        Returns:
        either "DH" or "ECDH"
      • computeAffineY

        public static BigInteger computeAffineY​(BigInteger affineX,
                                                ECParameterSpec params)
        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
      • toBouncyCastleECPoint

        public static ECPoint toBouncyCastleECPoint​(ECPoint point,
                                                    ECParameterSpec params)
        Converts a JCA EC point to a BC EC point.
        Parameters:
        point - the JCA EC point
        params - the parameters to interpret the point
        Returns:
        the corresponding BC EC point
      • fromBouncyCastleECPoint

        public static ECPoint fromBouncyCastleECPoint​(ECPoint point)
        Convert a BC EC point to a JCA EC point.
        Parameters:
        point - the BC EC point
        Returns:
        the corresponding JCA EC point
      • isValid

        public static boolean isValid​(ECPoint ecPoint,
                                      ECParameterSpec params)
        Determines whether an EC point is valid with respect to the given EC parameters.
        Parameters:
        ecPoint - an EC point
        params - the EC parameter specification
        Returns:
        a boolean indicating whether the EC point is valid with respect tot the given EC parameters
      • normalize

        public static ECPoint normalize​(ECPoint ecPoint,
                                        ECParameterSpec params)
        Normalizes an EC point given the EC parameters.
        Parameters:
        ecPoint - the EC point
        params - the EC parameter specification
        Returns:
        the normalized EC point
      • toBouncyECPublicKeyParameters

        public static ECPublicKeyParameters toBouncyECPublicKeyParameters​(ECPublicKey publicKey)
        Converts the EC public key to a BC public key parameter specification.
        Parameters:
        publicKey - the EC public key
        Returns:
        a BC typed public key parameter specification
      • toBouncyECPrivateKeyParameters

        public static ECPrivateKeyParameters toBouncyECPrivateKeyParameters​(ECPrivateKey privateKey)
        Converts the EC private key to a BC private key parameter specification.
        Parameters:
        privateKey - the EC private key
        Returns:
        a BC typed private key parameter specification
      • toBouncyECDomainParameters

        public static ECDomainParameters toBouncyECDomainParameters​(ECParameterSpec params)
        Converts a JCA compliant EC parameter (domain) specification to a BC EC domain specification.
        Parameters:
        params - the EC parameter specification
        Returns:
        the corresponding BC typed EC domain parameter specification.
      • getCipher

        public static Cipher getCipher​(String algorithm)
                                throws GeneralSecurityException
        Returns a cipher for the given encryption algorithm, possibly using the BC provider explicitly if the configured JCA providers cannot provide a cipher for the algorithm.
        Parameters:
        algorithm - the encryption algorithm
        Returns:
        a cipher
        Throws:
        GeneralSecurityException - on error
      • getCipher

        public static Cipher getCipher​(String algorithm,
                                       int mode,
                                       Key key)
                                throws GeneralSecurityException
        Returns a cipher for the given encryption algorithm and key, possibly using the BC provider explicitly if the configured JCA providers cannot provide a cipher for the algorithm and key.
        Parameters:
        algorithm - the encryption algorithm
        mode - the mode of operation (encrypt or decrypt)
        key - the key
        Returns:
        a cipher
        Throws:
        GeneralSecurityException - on error
      • getKeyAgreement

        public static KeyAgreement getKeyAgreement​(String algorithm)
                                            throws GeneralSecurityException
        Returns a key agreement object for the given algorithm, possibly using the BC provider explicitly if the configured JCA providers cannot provide a key agreement for the algorithm.
        Parameters:
        algorithm - the key agreement algorithm
        Returns:
        a key agreement object
        Throws:
        GeneralSecurityException - on error
      • getKeyPairGenerator

        public static KeyPairGenerator getKeyPairGenerator​(String algorithm)
                                                    throws GeneralSecurityException
        Returns a key pair generator for the given algorithm, possibly using the BC provider explicitly when the configured JCA providers cannot provide a generator for the algorithm.
        Parameters:
        algorithm - the algorithm
        Returns:
        a key pair generator
        Throws:
        GeneralSecurityException - on error
      • getMac

        public static Mac getMac​(String algorithm)
                          throws GeneralSecurityException
        Returns a MAC for the given algorithm, possibly using the BC provider explicitly if the configured JCA providers cannot provide a MAC for the algorithm.
        Parameters:
        algorithm - the MAC algorithm
        Returns:
        a MAC object
        Throws:
        GeneralSecurityException - on error
      • getMac

        public static Mac getMac​(String algorithm,
                                 Key key)
                          throws GeneralSecurityException
        Returns a MAC for the given algorithm and key, possibly using the BC provider explicitly when the configured JCA providers cannot provide a MAC for the algorithm and key.
        Parameters:
        algorithm - the MAC algorithm
        key - the key
        Returns:
        a MAC object
        Throws:
        GeneralSecurityException - on error
      • getMessageDigest

        public static MessageDigest getMessageDigest​(String algorithm)
                                              throws GeneralSecurityException
        Returns a message digest for the given algorithm, possibly using the BC provider explicitly if the configured JCA providers cannot provide a message digest for the algorithm.
        Parameters:
        algorithm - the message digest algorithm
        Returns:
        a message digest object
        Throws:
        GeneralSecurityException - on error
      • getPublicKey

        public static PublicKey getPublicKey​(String algorithm,
                                             KeySpec keySpec)
                                      throws GeneralSecurityException
        Returns a public key for the given algorithm and key specification, possibly using the BC provider explicitly when the configured JCA providers cannot provide a public key for the algorithm and key specification.
        Parameters:
        algorithm - the public key algorithm
        keySpec - the key specification
        Returns:
        a public key object
        Throws:
        GeneralSecurityException - on error
      • getSignature

        public static Signature getSignature​(String algorithm)
                                      throws GeneralSecurityException
        Returns a signature for the given signature algorithm, possibly using the BC provider if the configured JCA providers cannot provide a signature.
        Parameters:
        algorithm - the signature algorithm
        Returns:
        a signature object
        Throws:
        GeneralSecurityException - on error
      • getCertificateFactory

        public static CertificateFactory getCertificateFactory​(String algorithm)
                                                        throws GeneralSecurityException
        Returns a certificate factory object for the given certificate algorithm, possibly using the BC provider explicitly if the configured JCA providers cannot provide a certificate factory for the algorithm.
        Parameters:
        algorithm - the certificate algorithm
        Returns:
        a certificate factory
        Throws:
        GeneralSecurityException - on error
      • toOIDBytes

        public static byte[] toOIDBytes​(String oid)
        Encodes an object identifier. 0x80 Cryptographic mechanism reference. Object Identifier of the protocol to select (value only, tag 0x06 is omitted).
        Parameters:
        oid - the object identifier
        Returns:
        the encoding
      • partition

        public static List<byte[]> partition​(int segmentSize,
                                             byte[] data)
        Partitions a byte array into a number of segments of the given size, and a final segment if there is a remainder.
        Parameters:
        segmentSize - the number of bytes per segment
        data - the data to be partitioned
        Returns:
        a list with the segments
      • stripLeadingZeroes

        public static byte[] stripLeadingZeroes​(byte[] bytes)
        Strips any leading zeroes from a byte-array and returns the resulting byte-array.
        Parameters:
        bytes - the input byte-array (which is not modified in the process)
        Returns:
        a copy of the input byte-array, without the leading zeroes