TUTORIALS

CLASSPATH basics

As easy as 1, 2, 3...

How to use Crionics products

jPDF is a self-managed application programming interface (API) which requires no additional software to read, process and generate PDF documents. In most cases, you can access the jPDF API by referencing jpdf.jar in your classpath. This will grant access to all public classes in the package com.crionics.jpdf.*

Information regarding the API can be found:

• By reading the API description at http://www.crionics.com/docs/java-docs/index.html
• By browsing the list of online tutorials at http://www.crionics.com/tutorials/tutorials.html.
• By reading the Sample code part of the distribution.
• By getting in touch with the Crionics support team.

If you want to use PDF Encryption and Signatures, however, you may have to perform one more step: Install a cryptography provider.

jPDF uses the Java Cryptography Extension to instantiate algorithms: MD2, MD5, SHA1, RSA, DSA, AES and ARC4. Depending on your JDK (or your application server setup), you may have to install additional providers.

The Java Cryptography Extensions (JCE) is a standard Java API organized into two layers:

• A framework layer - referenced as jce1_2_2.jar which is bundled in the distribution. Starting with JDK 1.4 the framework is already part of the default classpath and does not need to be manually added. Also, if you plan to use jPDF from an application server, chances are the API is already pre-configured.
  
• A JCE implementation layer - where cryptography providers can plug-in their own cryptography algorithms.

You can get a FREE JCE provider from Bouncy Castle at http://www.bouncycastle.org/latest_releases.html. But you are welcome to use any other providers as long as they support the algorithms mentioned above.

Installing the Bouncy Castle provider

In this tutorial, we explain how to install the Bouncy Castle JCE into your JDK. The installation may differ if you are trying to install a new JCE provider in an application server.

1. Go to http://www.bouncycastle.org/latest_releases.html and download one of the following JARs depending on the JVM version you have:
(Please note that the version level might be different.)

For JDK1.5, download bcprov-jdk15-129.jar
For JDK1.4, download bcprov-jdk14-129.jar
For JDK1.3, download bcprov-jdk13-129.jar
For JDK1.2, download bcprov-jdk12-129.jar

2. Once downloaded, copy the file to <JDK_HOME>/jre/lib/ext - This folder contains the default global libraries for your JVM.

3. If you have a JDK version <= 1.3, copy also the JCE framework from <JPDF_DISTRIBUTION>/lib/jce1_2_2.jar to <JDK_HOME>/jre/lib/ext . You may also have to install a policy file to unlock encryption for keys > 40 bits. See the JCE Homepage for more info.

4. Edit the file <JDK_HOME>/jre/lib/security/java.security - This file describes the JCE providers installed in your system.

5. Pay attention to the lines security.provider.<n>=<className> . The <n> defines the order in which providers are looked up by the JCE framework.

6. Add the Bouncy Castle provider to the list. Your list should look like this one:

security.provider.1=org.bouncycastle.jce.provider.BouncyCastleProvider
security.provider.2=sun.security.provider.Sun
security.provider.3=com.sun.rsajca.Provider

That's it.
You are ready to sign and encrypt pdf documents.