3.3.1.1 The oracle.security.crypto.core.Key Interface

This interface represents a key which may be used for encryption or decryption, for generating or verifying a digital signature, or for generating or verifying a MAC. A key may be a private key, a public key, or a symmetric key.

3.3.1.2 The oracle.security.crypto.core.PrivateKey Interface

This interface represents a private key which may be an RSAPrivateKey, a DSAPrivateKey, a DHPrivateKey, an ECPrivateKey or a PrivateKeyPKCS8 instance that holds an encrypted private key.

3.3.1.3 The oracle.security.crypto.core.PublicKey Interface

This interface represents a public key which may be a RSAPublicKey, a DSAPublicKey, a DHPublicKey or a ECPublicKey instance.

3.3.1.4 The oracle.security.crypto.core.SymmetricKey Class

This class represents a symmetric key which may be used for encryption, decryption or for MAC operations.

3.3.2 Key Generation

3.3.2.1 The oracle.security.crypto.core.KeyPairGenerator Class

This abstract class is used to generate key pairs such as RSA, DSA, Diffie-Hellman or ECDSA key pairs.

To get a new key pair generator, create a new instance of KeyPairGenerator by calling the static getInstance() method with an AlgorithmIdentifier object as a parameter. Example 3-1 shows how to create a new KeyPairGenerator instance:

This creates a KeyPairGenerator object from one of the concrete classes: RSAKeyPairGenerator, DSAKeyPairGenerator, DHKeyPairGenerator, or ECKeyPairGenerator.

Initialize the key pair generator by using one of the initialize() methods. Generate the key pair with the generateKeyPair() method. Example 3-2 shows how to initialize the key pair generator and then generate a key pair:

3.3.2.2 The oracle.security.crypto.core.SymmetricKeyGenerator Class

To get a new symmetric key generator, create a new instance of SymmetricKeyGenerator by calling the static getInstance() method with an AlgorithmIdentifier object as a parameter. Example 3-4 shows how to create a new SymmetricKeyGenerator instance:

Example 3-4 Code Example for Creating a New SymmetricKeyGenerator Instance

To create a new instance of Cipher, call the static getInstance() method with an AlgorithmIdentifier and a Key object as parameters.

Example 3-6 shows how to create a new Cipher instance. First an RC4 object is created and initialized with the specified key. Second a block cipher DES object is created and initialized with the specified key and padding. This creates a cipher and initializes it with the passed parameters. To re-initialize an existing cipher, call one of the initialize() methods.

When using CBC ciphers, the AlgorithmIdentifier object may hold cryptographic parameters such as the initialization vector (IV) or the effective key length for RC2 ciphers. To specify these parameters when creating or initializing block ciphers, build a CBCAlgorithmIdentifier object or RC2AlgorithmIdentifier object with the cryptographic parameters. Example 3-7 shows how to create and initialize a CBC cipher and a RC2 cipher.

3.3.3.2 The RSA Cipher

The RSA cipher is an implementation of PKCS#1 v2.0 that supports the RSAES-OAEP and RSAES-PKCS1-v1_5 encryption schemes. According to the specification, RSAES-OAEP is recommended for new applications, and RSAES-PKCS1-v1_5 is included only for compatibility with existing applications and protocols.

The encryption schemes are used to combine RSA encryption and decryption primitives with an encoding method. Encryption and decryption can only be done through the methods encrypt(byte[]) and decrypt(byte[]).

You can use an RSA cipher for four types of operations:

Encryption of raw data. Use one of the encrypt() methods by passing data to be encrypted.

Decryption of encrypted data. Use one of the decrypt() methods by passing encrypted data to be decrypted.

Wrapping of keys. Use the wrapKey() method by passing the key to be encrypted.

Unwrapping of encrypted keys. Use the unwrapSymmetricKey() method by passing the encrypted key to be decrypted.

To create a new instance of Cipher, call the static getInstance() method with AlgorithmIdentifier and Key objects as parameters. Example 3-8 demonstrates how to create an RSApkcs1 object and initialize it with the specified key. The cipher can then be used to encrypt or decrypt data.

When using RSA ciphers, the AlgorithmIdentifier object may hold cryptographic parameters such as the mask generation function for RSAES-OAEP. To specify these parameters when creating or initializing RSA ciphers, build an OAEPAlgorithmIdentifier, or use the default one located in the oracle.security.crypto.core.AlgID interface.

3.3.3.3 Password Based Encryption

The abstract oracle.security.crypto.core.PBE class provides methods for Password Based Encryption (PBE) operations. The concrete classes extending the PBE are the PKCS5PBE and PKCS12PBE classes.

To create a new instance of PBE, call the static getInstance() method with a PBEAlgorithmIdentifier object as a parameter. For example:

PBE pbeEnc = PBE.getInstance(pbeAlgID);

This will create a PKCS5PBE object and initialize it with the specified PBE algorithm. The PBE can then be used to encrypt or decrypt data, wrap or unwrap keys.

When using PBE objects, the AlgorithmIdentifier object may hold cryptographic parameters such as the salt or the iteration count as well as the ASN.1 Object Identifier specifying the PBE algorithm to use. To specify these parameters when creating or initializing PBEs, build a PBEAlgorithmIdentifier object with the cryptographic parameters.

3.3.4 Signatures

The oracle.security.crypto.core.Signature abstract class provides methods to sign and verify signatures. The concrete classes extending the Signature class are the RSAMDSignature, DSA and the ECDSA classes.

The algorithms available for signature operations are:

For RSA: AlgID.md2WithRSAEncryption, AlgID.md5WithRSAEncryption and AlgID.sha_1WithRSAEncryption

For DSA: AlgID.dsaWithSHA1

For ECDSA: AlgID.ecdsaWithSHA1

To create a new instance of Signature, call the static getInstance() method with an AlgorithmIdentifier and a PrivateKey or PublicKey objects as parameters. Example 3-10 shows how to create a new Signature object and initialize it with the specified algorithm.

3.3.6 Key Agreement

The oracle.security.crypto.core.KeyAgreement class abstract class provides methods for public key agreement schemes such as Diffie-Hellman. The concrete classes extending the KeyAgreement class are the DHKeyAgreement and the ECDHKeyAgreement classes.

3.3.7.1 The oracle.security.crypto.core.RandomBitsSource class

RandomBitsSource is an abstract class representing secure PRNG implementations. Note that, by the very nature of PRNGs, the security of their output depends on the amount and quality of seeding entropy used. Implementing classes should provide guidance as to their proper initialization and use. The concrete classes extending the RandomBitsSource are the MD5RandomBitsSource, SHA1RandomBitsSource, and the DSARandomBitsSource classes.

Create a new instance of RandomBitsSource by calling the static getDefault() method to return the default PRNG:

RandomBitsSource rbs = RandomBitsSource.getDefault();

A RandomBitsSource object can also be created by instantiating one of the subclasses:

RandomBitsSource rbs = new SHA1RandomBitsSource();

By default, a newly created PRNG created from a subclass will be seeded. To seed a generic RandomBitsSource object, use one of the seed methods by using a byte array or an EntropySource object:

rbs.seed(myByteArray);

The object is then ready to generate random data:

rbs.randomBytes(myRandomByteArray);

3.3.7.2 The oracle.security.crypto.core.EntropySource class

The EntropySource class provides a source of seed material for the PRNGs. The concrete classes extending the EntropySource are the SpinnerEntropySource and SREntropySource classes.

Create a new instance of EntropySource by calling the static getDefault() method to return the default entropy source:

EntropySource es = EntropySource.getDefault();

You can also create an EntropySource object by instantiating one of the subclasses:

EntropySource rbs = new SpinnerEntropySource();

The entropy source is readied for use by using one of the generateByte methods: