Skip to main content

JCE Setup and Code Snippets

Introduction​

Pi Soft JCE Provider helps Java developers using the Pi Soft system for encryption and decryption through standard Java JCE interfaces.
At this time, there are two Pi Soft JCE provider implementations available for developers:

  • Pi Soft Offline JCE Provider  - Not dependent on any other kS components, this provider can load exported secure keys from a local key store file and perform fast encryption and decryption operations inside client runtime environment.

  • Pi Soft Online JCE Provider -  Besides providing same functions as offline provider, Pi Soft online JCE provider can serve new or existing secure keys from kS server and save these secure keys in a local key store.

Pi Soft JCE Provider currently supports following cryptographic algorithms, modes and paddings:

  • AES/CTR/NoPadding
  • AES/CBC/PKCS5Padding

The default algorithm as displayed in the kS Manager will be the one used.

Java​

The Java Runtime Environment must be Eclipse Temurin 8 (baseline jdk8u492-b09) or later, and must support TLS 1.3.  Current Temurin JDKs ship with the unlimited-strength cryptographic policy enabled by default; no separate JCE policy files are required.

Key Store Provider Artifacts​

  • Pi Soft Offline JCE Provider:

    • ErucesOfflineJce.jar: Eruces JCE provider implementation
    • erucesjce.dll/ liberucesjce.so: Native cryptographic library.

  • Eruces Online JCE Provider:

    • ErucesOnlineJce.jar: Eruces JCE provider implementation.
    • erucesjce.dll/ liberucesjce.so: Native cryptographic library.
    • TEAdmin.jar: appServer Agent for Java library.

Setup Procedure​

Both Pi Soft online and offline JCE providers follow the same procedures for setup.

  1. Runtime Environment Setup

For Windows, update PATH environment including the folder where erucesjce.dl is located.
For Linux/Unix, update LD_LIBRARY_PATH including the folder where liberucesjce.so is located.
The java.library.path Java runtime system property can also be used for specifying locations of native libraries.

2.  Java classpath Setup

Include corresponding Pi Soft JCE provider jars into Java application's classpath.

3.  JCE Provider Configuration

The java.security properties file must be updated to include Pi Soft JCE provider. The java.security file is located at:

    • Linux/Unix: $JAVA_HOME/lib/security/java.security
    • Windows: %JAVA_HOME%/lib/security/java.security

Using a text editor open this security properties file and add Pi Soft JCE provider at the end of provider section as:

Security.provider.=com.eruces.security.JniProvider

Below is an example of updated provider section:

#
#List of providers and their preference orders (see above):
#
security.provider.1=sun.security.provider.Sun
security.provider.2=sun.security.rsa.SunRsaSign
security.provider.3=sun.security.ec.SunEC
security.provider.4=com.sun.net.ssl.internal.ssl.Provider
security.provider.5=com.sun.crypto.provider.SunJCE
security.provider.6=sun.security.jgss.SunProvider
security.provider.7=com.sun.security.sasl.Provider
security.provider.8=org.jcp.xml.dsig.internal.dom.XMLDSigRI
security.provider.9=sun.security.smartcardio.SunPCSC
security.provider.10=sun.security.mscapi.SunMSCAPI
security.provider.11=com.eruces.security.JniProvider

Developers can use standard JCE interfaces to develop security solutions with Pi Soft JCE providers. During development, mostly developers take advantage of key store for retrieving secure keys. Pi Soft system defines T-tag and secure key pair for key management. Pi Soft JCE provider keeps base64-encoded T-tag as key's alias name in key store.

Development with Pi Soft Offline JCE Provider​

Loading Key Store​

The first step to use Pi Soft offline JCE provider is loading key store:

1. Getting an instance of Pi Soft JCE key store:

KeyStore ks = KeyStore.getInstance("EJOffline");

  1. Loading existing key store:

ks.load(new FileInputStream(KEY_FILE), password);

Getting Secure Key from Key Store​

Secure keys can be retrieved from key store through getKey() method:

SecretKey key = (SecretKey)ks.getKey(ttag, null);

There are several other methods useful for checking loaded key store:

Retrieving all alias (T-tags):

Enumeration ens = ks.aliases();

Check if an alias (T-tag) exist in key store:

ks.containsAlias(ttag);

Cipher Instance​

For encryption/decryption operations, an instance of Cipher must be retrieved first. There are several ways to retrieve an Pi Soft JCE Cipher instance:

Instantiate Cipher with cryptographic algorithm, mode and padding that only supported by Pi Soft JCE provider:

Cipher cipher = Cipher.getInstance("AES/CTR/NoPadding");

Instantiate Cipher with Pi Soft JCE provider Name:

Cipher cipher = Cipher.getInstance("AES/CTR/NoPadding", "Pi SoftJCE");

Instantiate Cipher with Pi Soft JCE provider instance:

Provider provider = new JniProvider();

Cipher cipher = Cipher.getInstance("AES/CTR/NoPadding", provider);

Of course the most standard and convenient way is the first approach listed above, which let Java run-time figure out which JCE provider to use.

Encryption/Decryption​

After instantiated a Cipher object, it can be initialized with a secure key to perform encryption or decryption:

Cipher Initialization

For encryption: cipher.init(Cipher.ENCRYPT_MODE, key, new CtrParameterSpec(0));

For decryption: cipher.init(Cipher.DECRYPT_MODE, key, new CtrParameterSpec(0));

(info) There is no Java standard interface or class defined for CTR parameter. Usually developers have to develop their own mechanism converting CTR counter into IVParameterSpec. Pi Soft JCE Provider provides a convenient helper CtrParameterSpec class, which can take offset as parameter, finding corresponding counter value for encryption/decryption.

Encryption/Decryption

After an Cipher object is initialized, encryption/decryption can be performed easily with several methods such as update() or doFinal():

byte[] encrypted_data = cipher.doFinal(data);

Storing Key Store​

A key store can be persisted into streams as:

FileOutputStream out = new FileOutputStream(KEY_FILE);

ks.store(out, password);

The persisted key store contains both encrypted secure keys and their protector information. Currently, the key provider can only generate XML formatted stream. Appendix section shows an example of persisted key store In XML format.

Development with Pi Soft Online JCE Provider​

This section only lists differences between online and offline providers which lie on key store initialization and key retrieval.

Loading Key Store​

An online key store is initialized/loaded in two steps:

1. Configure kS server properties:

In order to instantiate an online key store through key store's load() method, two system properties must be specified first to configure kS server location:

com.eruces.security.ServerName:

Specifies server name or IP address where kS server is running

com.eruces.security.ServerPort:

Specifies IP port which kS server is listening

These two properties can be set either in Java command-line parameters or programmable as:

System.setProperty("com.eruces.security.ServerName", "192.168.0.1");

System.setProperty("com.eruces.security.ServerPort", "8888");

2.  Configure authentication properties:

Unless PKCS data is used to authenticate, how the key store will authenticate to the kS must be specified. 

com.eruces.security.KeyStoreAuthenticationType:

Specifies the authentication type. Values can be:

      • PKCS12
      • Token
      • Kerberos
      • Native

 If this system property is not specified, by default, JCE Online KeyStore uses PKCS12.

This property can be set either in Java command-line parameters or programmable as

System.setProperty("com.eruces.security.KeyStoreAuthenticationType", "Native");

3.  Optionally, configure the key cache property:

The number of keys to retrieve in a single retrieve new key request can be set:

com.eruces.security.BatchKeyNumber:

Specifies the number of keys to retrieve in each call.

This property can be set either in Java command-line parameters or programmable as:

System.setProperty("com.eruces.security.BatchKeyNumber", "1");

The default initial key cache size is 100.  Subsequent calls increase the number of keys retrieved up to a maximum of 1000.

4.  After kS properties have been specified, a key store can be initialized/loaded as follows:KeyStore ks = KeyStore.getInstance("EJOnline");

4a. Initialize key store with PKCS #12 data. The PKCS #12 data must contains private key and certificate that can be authenticated by the kS.

ks.load(new FileInputStream(certificate_stream, password_char_array);

4b. Initialize key store with Token data. (which can be generated using the CLI utility efereg)

ks.load(new FileInputStream(token_stream, null);

4c. Initialize key store with Kerberos data which can be authenticated by the kS.

ks.load(new FileInputStream(user_name_stream, null);

4d. Initialize key store with a native user name and password..

ks.load(new FileInputStream(user_name_stream, password_char_array);

When running load() method, Pi Soft online provider establishes a connection with a kS for authentication and later key export.

Retrieve New Key​

New secure keys can be served from online key store through the same getKey() method with null or empty alias string as input parameter as:

SecureKey key = (SecureKey)ks.getKey(null, null);

When serving new keys, online key store retrieves them from kS server, caches them locally in memory, and returns SecureKey references to caller.

The first argument is for the T-Tag and so remains null.  The second argument can be the name of an ACL Template or it can be null, only the owner is listed on the ACL.

Retrieve Non-Cached Key​

Existing non-cached secure keys can be served from online key store as well through the same getKey() method with T-tag/alias string as input parameter as:

SecureKey key = (SecureKey)ks.getKey(ttag, null);

When serving existing keys, online key store retrieves them from kS server, caches them locally in memory, and returns SecureKey references to caller.

Reference​

JCA Reference Guide http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/CryptoSpec.html

Eruces Technology http://www.eruces.com/node/21

JCE Provider Implementation Guide http://docs.oracle.com/javase/6/docs/technotes/guides/security/crypto/HowToImplAProvider.html#Step6

Appendix​

<?xml version="1.0" encoding="UTF-8" ?> 
<KeyStore>
<Protector type="PKCS12">
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
</Protector> 
<SecretKeys>
<SecretKey T-tag="AAAAEyJBizfsx+tOXM951qHcWGNGKScfvgcI1mAeUEHKr68WDwTf8Q==">d0fDRB4qK/tKTbPDTnM5f2MNV0JMTx7qZ0OGf13qw46WsNXWAUul8Dy5SdleXw1V0s+ZmhRiVkdspxPJhCB+xIWqQK5h5OEwzuH3rAWjcOu9/5pNyyb1CGTkeLeH9AyhhoN0g0+8Pchkq/AkQtWHAm4w/dUwB/uk/afbjn2B0d4=
</SecretKey> 
<SecretKey T-tag="AAAAExkR33rjKgEg4MA/hm8A9TOXcmGHoCavBwuVRw8uuGa7e3prUA==">NV1lBtWbCUYTuuZ5mY6PuK7SX3DQowLkKC/hQpgmER/VduyacJnjnV2I6gb0deloG6KwIAaGh6wFgZcnCUAIvUOeAo7Nd89ytHLvtfaw1eB7kOdv4L0VMg1W88XKnGSN3wjQzTw4ScsmEPLtuwJR0pbJrOmAr6qD7LwiBEgnq/A=
</SecretKey> 
</SecretKeys>
</KeyStore>