TUTORIALS

 How to use certificate security

As easy as 1, 2, 3...

What's so different from password security?

Please make sure you have reviewed the tutorials about basic and password security before reading this tutorial.
Also helpful is a good understanding of keystore and cryptography in general.

There are three main differences between password security and certificate security. In certificate security:

1. The credentials are no longer passwords, but public/private keys.
2. You can define how access permissions are set for each individual.
3. Anonymous access is no longer allowed.

Selecting permissions, encryption algorithm and key length are similar to password security.

// Set the default encryption parameters:
preferences.setDefaultSecurityType(Preferences.SECURITY_CERTIFICATE_PROTECTED);
preferences.setDefaultEncryptionType(Preferences.ENCRYPTION_AES);
preferences.setDefaultEncryptionKeyLength(128);

As presented in the basic tutorial, credentials come not with one credentials implementations but two:

1. One for opening a document (CertificateCredentials);
2. The other for creating documents (CertificateCredentialsCreation).

We will see in the next sections the details of each implementation.

Opening a PKI document

The first thing we need to do in order to open a document protected by Certificate Security is to get hold of our identity.
In Java, key pairs are usually stored in a key store. The following code opens a keystore from its path, type and password. We won't be discussing the details of generating key pairs and certificates in a key store. You can find many online references about it. Alternatively, you could also use the jPDF Viewer wizards to generate your key pairs and import certificates.

// Instantiate a key store:
public KeyStore readKeyStore(File file, String type, String keystorePassword) throws KeyStoreException,NoSuchAlgorithmException, CertificateException, IOException
{

FileInputStream is = new FileInputStream(file);
KeyStore ks = KeyStore.getInstance(type);
char[] password = keystorePassword.toCharArray();
ks.load(is, password);
is.close();
return ks;

}

Let's assume we have a public/private key pair alias called "myIdentity" in this key store. We can now instantiate a CertificateCredential and open a PKI document using the code below:

KeyStore ks=readKeyStore("myks.jks", "jks", "myKsPassword");

PrivateKey privateKey = (PrivateKey) ks.getKey("myIdentity", "myKeyPassword".toCharArray());
Certificate cert = ks.getCertificate("myIdentity");

CertificateCredentials openCredentials = new CertificateCredentials(privateKey, cert);

// Open the document:
PdfDocument doc=new PdfDocument("myPKIfile.pdf", credentials);

Creating a PKI document

Creating a PKI document requires access to the certificate of each individual person on the destination list.
As opposed to password security, you can pick a different permission for each individual on the distribution list.

Let's see how this can be done:

// Open the key store:
KeyStore ks=readKeyStore("myks.jks", "jks", "myKsPassword");

// Extract the identity of the author:
PrivateKey privateKey = (PrivateKey) ks.getKey("myIdentity", "myKeyPassword".toCharArray());
Certificate cert = ks.getCertificate("myIdentity");

// Instantiate the createCredential - the author is given full privileges:
CertificateCredentialsCreation createCredentials = new CertificateCredentialsCreation(privateKey, cert);

// Now build up the permissions for destinators; please note that we add public keys here:
Permissions perms = new Permissions();

// Set destinator and permissions for user1:
perms.setDenyAll();
createCredentials.addCredential(keyStore.getCertificate("publicKeyAliasForUser1"), perms);

// Set destinator and permissions for user2:
perms.setCanPrint(true);
createCredentials.addCredential(keyStore.getCertificate("publicKeyAliasForUser2"), perms);

// Finally, set how the document will be ciphered:
Preferences prefs = new Preferences();
prefs.setDefaultSecurityType(Preferences.SECURITY_CERTIFICATE_PROTECTED);
prefs.setDefaultCredentials(createCredentials);
prefs.setDefaultEncryptionType(Preferences.ENCRYPTION_AES);
prefs.setDefaultEncryptionKeyLength(128);

PdfDocument doc = new PdfDocument("myUncipheredDocument.pdf");
doc.getEncryptionModule().processTo("pkiDocument.pdf", prefs);
doc.close();