Using Cryptography Extensions

C H A P T E R 13

This chapter describes how to use the basic security and cryptography classes, which do not appear in all Java Card development kits. For the location of cryptography files in the development kit, see Installed Files and Directories.

The security and cryptography classes are supported by the RI (cref). The support for security and cryptography allows you to:

Generate message digests using the SHA1 algorithm

Generate cryptographic keys on Java Card technology-compliant smart cards for use in the ECC and RSA algorithms

Set cryptographic keys on Java Card technology-compliant smart cards for use in the AES, DES, 3DES, ECC, and RSA algorithms

Encrypt and decrypt data with the keys using the AES, DES, 3DES, and RSA algorithms

Generate signatures using the AES, DES, 3DES, ECC, or SHA and RSA algorithms

Generate sequences of random bytes

Generate checksums

Use part of a message as padding in a signature block

Note - DES is also known as single-key DES. 3DES is also known as triple-DES.

For more information on the SHA1, DES, 3DES, and RSA encryption schemes, see:

For SHA1--”Secure Hash Standard”, FIPS Publication 180-1:
http://www.itl.nist.gov/

For DES--”Data Encryption Standard (DES)”, FIPS Publication 46-2 and “DES Modes of Operation”, FIPS Publication 81:
http://www.itl.nist.gov/

For RSA--“RSAES-OAEP (Optional Asymmetric Encryption Padding) Encryption Scheme”:
http://www.rsasecurity.com/

For AES--”Advanced Encryption Standard (AES)” FIPs Publication 197:
http://www.itl.nist.gov/

For ECC--”Public Key Cryptography for the Financial Industry: The Elliptic Curve Digital Signature Algorithm” (ECDSA): X9.62-1998
http://www.x9.org/

For Checksum--”Information technology--Telecommunications and information exchange between systems--High-level data link control (HDLC) procedures”
ISO/IEC-13239:2002 (replaces ISO-3309):
http://www.iso.org/

Supported Cryptography Classes

The implementation of security and cryptography in version 3.0.3 of the RI supports the use of the following classes:

javacardx.crypto.Cipher

javacard.security.Checksum

javacard.security.InitializedMessageDigest

javacard.security.KeyAgreement

javacard.security.KeyBuilder

javacard.security.KeyPair

javacard.security.MessageDigest

javacard.security.RandomData

javacard.security.Signature

javacard.security.SignatureMessageRecovery

Note - In version 3.0.3 of the RI, the implementation of RandomData is not suitable for porting.

TABLE 13-1 lists the cryptography algorithms that are implemented for the RI.

TABLE 13-1 Algorithms Implemented by the Cryptography Classes
Class	Algorithm
`Checksum`	`ALG_ISO3309_CRC16`--ISO/IEC 3309-compliant 16-bit CRC algorithm. This algorithm uses the generator polynomial: `x^16+x^12+x^5+1`. The default initial checksum value used by this algorithm is 0. This algorithm is also compliant with the frame-checking sequence as specified in section 4.2.5.2 of the ISO/IEC 13239 specification. `ALG_ISO3309_CRC32`--ISO/IEC 3309-compliant 32-bit CRC algorithm. This algorithm uses the generator polynomial: `X^32+X^26+X^23+X^22+X^16+X^12+X^11+X^10+X^8 +X^7+X^5+X^4+X^2+X+1`. The default initial checksum value used by this algorithm is 0. This algorithm is also compliant with the frame-checking sequence as specified in section 4.2.5.3 of the ISO/IEC 13239 specification.
`Cipher`	`ALG_DES_CBC_ISO9797_M2`--provides a cipher using `DES` in `CBC` mode. This algorithm uses `CBC` for `DES` and `3DES`. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme. `ALG_RSA_PKCS1`--provides a cipher using `RSA`. Input data is padded according to the `PKCS#1` (v1.5) scheme. `ALG_AES_BLOCK_128_CBC_NOPAD`--provides a cipher using `AES` with block size 128 in CBC mode and does not pad input data.
InitializedMessageDigest	Provides the functionality of MessageDigest, with the additional ability to allow for initialization with a starting hash value corresponding to a previously hashed part of the message. Provide for SHA1 and SHA256.
`KeyAgreement`	`ALG_EC_SVDP_DH`--elliptic curve secret value derivation primitive, Diffie-Hellman version, as per [IEEE P1363]. `ALG_EC_SVDP_DHC`--elliptic curve secret value derivation primitive, Diffie-Hellman version, with cofactor multiplication, as per [IEEE P1363].
`KeyBuilder`	The algorithms define the key lengths for: 128-bit `AES` 64-bit `DES` 112-, 128-, 160-, 192-bit `ECC` 128-bit `DES3` 512-bit `RSA`
`KeyPair`	The algorithms define the key lengths for: 112-, 128-, 160-, 192-bit `ECC` 512-bit `RSA`
`MessageDigest`	Message digest algorithm `SHA1` and `SHA256`
`RandomData`	Pseudo-random number generator with a 48-bit seed, which is modified using a linear congruential formula.
`Signature`	`ALG_DES_MAC8_ISO9797_M2`--generates an 8-byte `MAC` (most significant 8 bytes of encrypted block) using `DES` or `3DES` in `CBC` mode. This algorithm uses `CBC` for `DES` and `3DES`. Input data is padded according to the ISO 9797 method 2 (ISO 7816-4, EMV’96) scheme. `ALG_RSA_SHA_PKCS1`--encrypts the 20 byte `SHA1` digest using `RSA`. The digest is padded according to the `PKCS#1` (v1.5) scheme. `ALG_AES_MAC_128_NOPAD`--generates a 16-byte MAC using `AES` with blocksize 128 in CBC mode and does not pad input data. `ALG_ECDSA_SHA`--signs/verifies the 20-byte SHA digest using ECDSA.
SignatureMessageRecovery	`ALG_RSA_SHA_ISO9796_MR`--This algorithm uses the first part of the input message as padding bytes during signing. During verification, these message bytes (recoverable message) can be recovered to reconstruct the message.

Instantiating the Classes

Implementations of the cryptography classes extend the corresponding base class with implementations of their abstract methods. All data allocation associated with the implementation instance is performed when the instance is constructed. This is done to ensure that any lack of required resources can be flagged when the applet is installed.

Each cryptography class, except KeyPair, has a getInstance method which takes the desired algorithm as one of its parameters. The method returns an instance of the class in the context of the calling applet. Instead of using a getInstance method, KeyPair takes the desired algorithm as a parameter in its constructor.

If you request an algorithm that is not listed in TABLE 13-1 or that is not implemented in this release, getInstance will throw a CryptoException with reason code NO_SUCH_ALGORITHM.