The Crypto-J API generally uses the following model:

Step	Action	Result
0	Import classes using  import com.rsa.jsafe.*;	Imports Crypto-J classes.
1	Call getInstance	Creates and sets objects.
2	Call Init	Initializes algorithm object. If the algorithm requires a key, creates and sets the key.
3	Call Update	Starts the action indicated by the algorithm; for example, data encryption.
4	Call Final	Finishes the action begun in the Update step.
5	Call clearSensitiveData	Overwrites any sensitive data in memory. In addition, if choosing the "Native"device, frees any allocated memory not yet deallocated.

Using the Crypto-J API

Step 0: Import classes using com.rsa.jsafe.*;

Before you begin the actual coding of a Java application or applet that uses Crypto-J, you must use the import statement shown above. This directs the Java compiler to search its list of known packages and directories to locate Crypto-J. If you encounter errors during this step, they will probably be compile-time errors and will most likely indicate that the compiler cannot find the jsafe.jar file. See your compiler's documentation about how to set your path to find the .class or .jar files.
Note: With Crypto-J 2.3, we have changed our package name to begin with lower-case com. Sun Microsystems originally suggested that package names begin with upper-case COM, and Crypto-J followed that suggestion in previous releases. Later, Sun changed their recommendation to lower-case com. In addition, upper-case COM produced errors on some platforms, and much of the Java community now uses lower-case com.

Step 1: Call getInstance

When you need an object to perform a particular cryptographic transformation, call the getInstance method of the appropriate class. The getInstance method will create a new object for you. This object includes support for the specified algorithm.

Step 2: Call Init

Once you have this algorithm object, you need to Initialize it, often with a key. You can build a key object from scratch with getInstance, or you can call the algorithm object's getBlankKey or getBlankKeyPair method to ensure that your key object and algorithm object match. When you have the blank key object, it will have a generate method to build itself, or a setData method to use specified key data.

Step 3: Call Update

After you have initialized the algorithm object with a key, start processing data with an Update call (such as encryptUpdate). You can call Update as many times as you want, allowing you to break the input data into smaller blocks.

Step 4: Call Final

When you have updated all the data you want to transform, call the Final method to complete the process. The Final method appends or takes away padding (if necessary) depending upon the algorithm and parameters, and finishes cryptographic processing.

Step 5: Call clearSensitiveData

Because your objects contain sensitive information (such as key data), you can call clearSensitiveData to overwrite any arrays that contain secret information. Although clearSensitiveData is called automatically by the finalize method, you may want to call it explicitly to ensure that sensitive data is not exposed. Calling clearSensitiveData more than once does not cause any damage. You should take care to call clearSensitiveData in the following situations:

• to free natively allocated memory
• whenever you are finished with a Crypto-J object

When you build a Crypto-J object using "Native," you must call clearSensitiveData. The Native implementation allocates memory, so a call must exist somewhere to free it. The clearSensitiveData method frees any natively allocated memory that has not yet been deallocated. If you do not call clearSensitiveData, the garbage collector may or may not call the finalize method (which calls clearSensitiveData). If it does not, your program may create a memory leak.

Finishing With a Crypto-J Object

Crypto-J classes contain the finalize method, which, in Crypto-J, clears sensitive information (by calling the clearSensitiveData method) before garbage collection occurs. However, the garbage collector might not call the finalize method unless the application sets the following:

 System.runFinalizersOnExit(true);

Because of the nature of Java, however, your arrays that contain sensitive data may have been copied. Therefore, if you call clearSensitiveData, you overwrite one copy of the secret, but another copy could be somewhere else. However, Crypto-J lets you mask sensitive data while it is not in use, using memory obfuscation.