1.0 Download

The {{glossary.Fortanix-Data-Security-Manager}} (DSM) JCE Provider for all platforms can be downloaded here.

2.0 Operating System (OS) Compatibility Matrix

For information on the JCE client OS compatibility matrix, refer to Clients: Compatibility Matrix.

3.0 Installation

3.1 System-wide Install

Move the downloaded bundled provider jar file sdkms-jce-provider-bundled-x.xx.xxxx.jar to ${JAVA_HOME}/jre/lib/ext directory.
Apply Unlimited Strength Jurisdiction Policy Files by downloading the Policy file from the Java website. Extract the downloaded zip file, and copy the following files to the ${JAVA_HOME}/jre/lib/security directory.
- local_policy.jar
- US_export_policy.jar

Add the provider to your code:

import com.fortanix.sdkms.jce.provider.SdkmsJCE;
SdkmsJCE provider = new SdkmsJCE();
Security.addProvider(provider);

Alternatively, the provider can be added in ${JAVA_HOME}/jre/lib/security/java.security file, as the last provider in the list. This will allow integration with non-program-based usage, for example, keytool, jarsigner, and so on.
An example java.security file would look like

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=com.fortanix.sdkms.jce.provider.SdkmsJCE

3.2 Maven Based Install

NOTE
This option is available starting from 3.19.1352 version.

Maven projects define dependencies within the pom.xml file in source under the tag. This file is located in the base directory of the maven project.

Add the following dependency to JCE provider in the pom.xml file:

<dependency>
 <groupId>com.fortanix</groupId>
 <artifactId>sdkms-jce-provider</artifactId>
 <version>x.xx.xxxx</version>
</dependency>

Add the following provider to your code:

import com.fortanix.sdkms.jce.provider.SdkmsJCE;
SdkmsJCE provider = new SdkmsJCE();
Security.addProvider(provider);

4.0 Configuration

For the JCE Provider to connect to Fortanix DSM, one needs to provide the server URL and an API key of an application used for authentication. These can be set as environment variables. For example:

export FORTANIX_API_ENDPOINT=https://<fortanix_dsm_url>
export FORTANIX_API_KEY=<your API key>
export FORTANIX_ADD_KEY_OPS_OVERRIDE="EXPORT"

In this configuration, FORTANIX_ADD_KEY_OPS_OVERRIDE ensures that the EXPORT key operation is always included during key creation by the JCE provider.

NOTE
The allowed key operations list will include KeyOperations.EXPORT along with other key operations.
If the cryptographic policy on the Fortanix DSM account disallows the EXPORT operation, the key creation request in JCE Provider will result in the error: Some requested operations (EXPORT) is not allowed by policy.

4.1 Certificated Based Authentication (mTLS)

Alternatively, the application can authenticate using a Client Certificate instead of an API key for Mutual TLS verified connection.

For more information on certificate based authentication, refer to the User's Guide: Authentication.

If the client's private key and certificate are in PEM format (provided by your CA or openssl), convert them into Java KeyStore (JKS) format using the following command:

NOTE
Certificate import can fail if it includes unknown critical X.509 extensions. Fortanix DSM complies with RFC 5280, which mandates rejection of certificates with unrecognized extensions marked as critical. To ensure compatibility, avoid marking custom or non-standard extensions as critical.

openssl pkcs12 -export -in client-cert.pem -inkey client-key.pem -name "my-sdkms-app" -out client-sdkms.p12

NOTE
This command asks for a password to be set for the local KeyStore. Enter any password of your choice, for example, 'PASSWORD'.

Provide the above generated KeyStore as a JVM argument to your Java program.

java -Djavax.net.ssl.keyStoreType=pkcs12 -Djavax.net.ssl.keyStore=client-sdkms.p12 -Djavax.net.ssl.keyStorePassword=PASSWORD MyJCEProgram.java

Or programmatically set as system properties:

System.setProperty("javax.net.ssl.trustStoreType", "jks");
System.setProperty("javax.net.ssl.trustStore", <path to sdkms-truststore.jks file>);
System.setProperty("javax.net.ssl.trustStorePassword, "PASSWORD");

Java tools like keytooland jarsigner take JVM arguments as follows:

jarsigner -J-Djavax.net.ssl.keyStoreType=pkcs12 -J-Djavax.net.ssl.keyStore=client-sdkms.p12 -J-Djavax.net.ssl.keyStorePassword=PASSWORD ...

4.2 Custom CA Configuration

For on-premise Fortanix DSM installations, one may need to add the Organization CA to TrustStore for successful TLS communication with API.

Create a Java TrustStore which saves the CA certificate (PEM format)

keytool -import -alias SDKMS_CA -file sdkms-root-ca.crt -keystore sdkms-truststore.jks -deststorepass PASSWORD

Provide the TrustStore as a JVM argument to your Java program

java -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStore=sdkms-truststore.jks - Djavax.net.ssl.trustStorePassword=PASSWORD MyJCEProgram.java

Or programmatically set as system properties:

System.setProperty("javax.net.ssl.trustStoreType", "jks");
System.setProperty("javax.net.ssl.trustStore", );
System.setProperty("javax.net.ssl.trustStorePassword, "PASSWORD");

Java tools like keytooland jarsigner take JVM arguments as follows:

jarsigner -J-Djavax.net.ssl.trustStoreType=jks -J-Djavax.net.ssl.trustStore=client-sdkms.p12 -J-Djavax.net.ssl.trustStorePassword=PASSWORD ...

5.0 Supported Algorithms

Encrypt - Single Part
Decrypt - Single Part

Crypto	Algorithm	Mode/Method	Key Size/Curve	Padding Support	Use
Symmetric	AES	ECB	128, 192, 256 bits	NOPADDING, PKCS5PADDING	Data Encryption or Decryption
		CBC
		CTR
		CFB
		GCM
		FF1		NOPADDING
		FPE		NOPADDING
					Key Generation
	DES	ECB	56 bits	NOPADDING, PKCS5PADDING	Data Encryption or Decryption
		CBC		NOPADDING, PKCS5PADDING	Data Encryption or Decryption
					Key Generation
	DES3	CBC ECB	168 bits	NOPADDING, PKCS5PADDING	Data Encryption or Decryption


	DESede	ECB	168 bits	NOPADDING, PKCS5PADDING	Data Encryption or Decryption
		CBC	168 bits	NOPADDING, PKCS5PADDING	Data Encryption or Decryption
					Key Generation
	HmacSHA1				Mac Generate and Mac Verify Key Generation
	HmacSHA256
	HmacSHA384
	HmacSHA512
Asymmetric	RSA		1024, 2048 bits	PKCS5PADDING,OAEPPADDING	Data Encryption or Decryption
	RSA		1024, 2048, 4096, 8192 bits		Asymmetric Key Pairs Generation
	EC	SecP192K1			Asymmetric Key Pairs Generation
		SecP224K1
		NistP-192
		SecP256K1
		NistP-224
		NistP-256
		NistP-384
		NistP-512
		Ed25519
	RSA with SHA	SHA1withRSA			Digital Signature Sign or Verify
		SHA256withRSA
		SHA384withRSA
		SHA512withRSA
	EC with SHA	SHA1withECDSA			Digital Signature Sign or Verify
		SHA256withECDSA
		SHA384withECDSA
		SHA512withECDSA
	DSA with SHA	SHA1withDSA			Digital Signature Sign or Verify
		SHA256withDSA
		SHA384withDSA
		SHA512withDSA
	RSA-PSS	SHA1withRSAandMGF1			Digital Signature Sign or Verify
		SHA256withRSAandMGF1
		SHA384withRSAandMGF1
		SHA512withRSAandMGF1
	RSA-PKCS1V15	SHA1withRSAandPKCS1V15			Digital Signature Sign or Verify
		SHA256withRSAandPKCS1V15
		SHA384withRSAandPKCS1V15
		SHA512withRSAandPKCS1V15

For a full list of supported algorithms refer to Algorithm Support.

6.0 Connection Pooling

Fortanix DSM version 3.21 and above supports a new feature called Connection Pooling.

Connection pooling allows restriction and reuse of connections with a maximum limit specified.
This allows setting some safe limits on each JCE application so that no single application can overwhelm the server.

6.1 With JCE Connection Pooling

The environment variable FORTANIX_CONN_MAX is set to the maximum number of connections from that instance of the JCE application.

6.2 Without JCE Connection Pooling

When the environment variable FORTANIX_CONN_MAX is not exported or is set to `0`, JCE will behave without any connection pooling/limit. This is similar to JCE behavior prior to version 3.21.

6.3 Scenarios

FORTANIX_CONN_MAX = 0.
- Existing behavior: number of sockets is equal to the number of concurrent threads.
FORTANIX_CONN_MAX = X, Concurrent threads less than X.
- Behavior: Less than X sockets open at a time.
- Observation: The sockets are also being reused.
FORTANIX_CONN_MAX = X, Concurrent threads greater than X.
- Behavior: Maximum X sockets open with reuse.
- Observation: higher latency, which is expected since threads are now waiting for connections to get free.

6.4 Connection Pooling Keep-Alive

The environment variable FORTANIX_CONN_KEEPALIVE is a configurable property that is used to keep the duration of a live connection open for reuse in case of subsequent requests.

The default value is 5000 milliseconds (5 seconds) in case it is not configured.

6.4.1 Configuration

To configure keep-alive, declare it as a system environment variable. For example,

export FORTANIX_CONN_KEEPALIVE=4000

7.0 Client Side Failover

This feature in the Fortanix JCE Provider enables automatic retry of requests on alternative endpoints if the initial request does not complete within a specified timeout. This enhances resilience and availability in distributed or clustered deployments.

7.1 Enable Client Side Failover

To enable this feature, set the following environment variable:

FORTANIX_DSM_ENABLE_CLIENT_SIDE_FAILOVER=true

In addition, configure the following environment variables to define failover behavior:

7.1.1 Endpoint Configuration

The JCE Provider application needs to be aware of all the available endpoints for request retries. Endpoint resolution behavior is controlled by the environment variable FORTANIX_DSM_NAME_RESOLUTION_STRATEGY, which determines how failover endpoints are derived from FORTANIX_API_ENDPOINT.

Static Resolution: Set FORTANIX_DSM_NAME_RESOLUTION_STRATEGY=static. In this case, FORTANIX_API_ENDPOINT must contain multiple comma-separated endpoint URLs.
Example:
```
FORTANIX_DSM_NAME_RESOLUTION_STRATEGY=static
FORTANIX_API_ENDPOINT="https://cluster1.dsm.com,https://cluster2.dsm.com"
```
Dynamic Resolution: Set FORTANIX_DSM_NAME_RESOLUTION_STRATEGY=dynamic. In this case, FORTANIX_API_ENDPOINT should be a single endpoint. The application uses the system DNS resolver to resolve this endpoint into multiple IPs or hostnames.
Example:
```
FORTANIX_DSM_NAME_RESOLUTION_STRATEGY=dynamic
FORTANIX_API_ENDPOINT="https://cluster.dsm.com"
```
In this case, https://cluster.dsm.com must resolve to multiple valid hostnames.

NOTE
All resolved hostnames must be present in the TLS certificates presented by the corresponding servers.

7.1.2 Retry Configuration

Set the retry interval in milliseconds using the following environment variable:
```
FORTANIX_DSM_REQUEST_RETRY_INTERVAL=<milliseconds>
```
This defines how long the client waits before retrying the request on a different endpoint.
Set the maximum number of retries per request using the following environment variable:
```
FORTANIX_DSM_MAX_REQUEST_RETRIES=<maximum retry number>
```
If this value exceeds the number of currently healthy endpoints, the number of healthy endpoints is used instead.
All endpoints are considered healthy initially. An endpoint is removed from the healthy list if a non-API exception occurs (For example, connection failure, SSL handshake failure).

7.1.3 Health Check Configuration

Optionally, you can enable periodic health checks for all endpoints using the following environment variable:

FORTANIX_DSM_HEALTH_CHECK_INTERVAL=<milliseconds>

Health checks will only be performed if the value of FORTANIX_DSM_HEALTH_CHECK_INTERVAL is greater than 0.

A GET /sys/v1/health API call is made to each endpoint according to the resolution strategy. Endpoints that respond successfully are added back to the healthy list.

NOTE
Only the following cryptographic operations support automatic retries: sign, verify, encrypt, decrypt, wrapkey, digest, and mac.
Operations not listed above are executed on a single endpoint determined by the resolution strategy.
For static resolution, the first endpoint in FORTANIX_API_ENDPOINT is used.
For dynamic resolution, the single endpoint specified in FORTANIX_API_ENDPOINT is used.
When a request is retried on a different endpoint, the original request is not canceled. The JCE Provider application awaits responses from all outstanding requests and uses the response from the first one that completes.
Example:
If FORTANIX_DSM_REQUEST_RETRY_INTERVAL elapses before the first request (request1) completes, the request is retried on the next endpoint (request2). If request1 finishes before request2, its response is used and returned.

8.0 Logging

With the 3.21 release, by default the logging option is disabled, and in order to enable it export the following environment variables:

To enable debug logs, set the environment variable:
```
export FORTANIX_LOG_DEBUG=true
```
To enable only API logs, set the environment variable:
```
export FORTANIX_LOG_API=true
```
To set a file location for local logs, set the environment variable:
```
export FORTANIX_LOG_FOLDER="/path/to/logfile-folder"
```

This will create a log file /path/to/logfile-folder/sdkms-jce.log.

9.0 Local Digest

Local Digest is now set as the default behavior in the Fortanix DSM JCE Provider from the 4.10 release onwards. By default, Fortanix DSM makes API calls to DSM for performing message digest operations, but from the 4.10 release onwards, it will not make the API calls and will perform the message digest operations locally without the user’s intervention through the SUN provider’s implementation. This reduces the overhead of the digest API calls to Fortanix DSM while performing sign and verify operations.
To enable or disable the local digest, use the environment variable FORTANIX_USE_LOCAL_DIGEST.
Set the environment variable to false to perform the digest operations through the DSM API calls.

10.0 Keytool and KeyStores

The keytool utility can now use the Fortanix DSM JCE provider for the management of key pairs and certificates which are backed by the Fortanix DSM service.

KeyStore is used to store the generated keys and certificates to Fortanix DSM.

Fortanix DSM JCE supports two types of KeyStores:

SDKMS-local
SDKMS

10.1 SDKMS-local

This KeyStore can be used by clients who expect more-or-less JKS (the default KeyStore) semantics. All metadata will be stored locally and imported to Fortanix DSM when keystore.store is called.

To use keytool with the KeyStore SDKMS-local, provide the following :

storetype must be provided as SDKMS-local
providerName must be sdkms-jce

Different keytool operations that can performed using the local KeyStore are as follows (Refer to Section 10.1.1: Usage with keytool for setup):

10.1.1 Usage

keytool <operations> -storetype SDKMS-local -providerName sdkms-jce -storepass passwd -keypass passwd

Generate Asymmetric keys

keytool -genkeypair -alias alias -keyalg RSA -keystore keystore_file -keysize 1024 -providerName sdkms-jce -storetype SDKMS-local -storepass passwd -keypass passwd -dname "CN=fortanix,OU=fortanix,O=fortanix,L=Mountain View,ST=California,C=US"

Import Certificate

keytool -importcert -trustcacerts -alias alias -file certificate-path -keystore keystore_file -providerName sdkms-jce -storetype SDKMS-local -storepass passwd -noprompt -trustcacerts

Import Keystore

keytool -importkeystore -srcstoretype SDKMS-local -deststoretype SDKMS-local -srcalias alias -srcProviderName sdkms-jce -destProviderName sdkms-jce -srckeystore source_keystore_file -destkeystore dest_keystore_file -srcstorepass passwd -deststorepass passwd -srckeypass passwd -destkeypass passwd

Generate AES Symmetric Keys

keytool -genseckey -alias alias -keyalg AES -keysize 256 -storepass passwd -keypass passwd -keystore keystore_file -providerName sdkms-jce -storetype SDKMS-local

Import Password as Secret Keys

keytool -importpassword -alias alias -storepass passwd -keystore keystore_file -providerName sdkms-jce -storetype SDKMS-local

List

keytool -list -v -keystore keystore_file -providerName sdkms-jce -storetype SDKMS-local -storepass passwd

Delete

keytool -delete -alias alias -keystore keystore_file -providerName sdkms-jce -storetype SDKMS-local -storepass passwd

10.2 SDKMS

This KeyStore can be used when a user needs to interact with Fortanix DSM directly. No metadata is stored locally. The Fortanix DSM groups are an abstraction for different KeyStores for a user, hence a groupId will be used while storing and retrieving the keys for this KeyStore type.

To use keytool with keystore type SDKMS, provide the following :

storetype must be SDKMS.
providerName must be sdkms-jce.
key and store password must be provided as groupId to store the corresponding key in that group.

Unsupported scenarios in KeyStore type SDKMS:

AES transient keys are supported to be imported in a different group than the group used to create the key.
RSA, EC, DES, and DES3 keys are persistent keys and cannot be updated to different groupId.
Importing a KeyStore is not supported as all the keys cannot be updated to a different groupId.

Different keytool operations that can be performed using the local KeyStore are as follows (Refer to Section 10.2.1: Usage with keytool for setup) :

10.2.1 Usage

keytool <operation> -storetype SDKMS -providerName sdkms-jce -keypass <groupId> -storepass <groupId>`

Import Certificate

keytool -importcert -trustcacerts -alias alias -file certificate-path -keystore keystore_file -providerName sdkms-jce -storetype SDKMS -storepass 2ff36949-ee70-4145-bd57-7de1ada5c050 -noprompt -trustcacerts

Generate AES Symmetric Keys

keytool -genseckey -alias alias -keyalg AES -keysize 256 -storepass 2ff36949-ee70-4145-bd57-7de1ada5c050 -keypass 2ff36949-ee70-4145-bd57-7de1ada5c050 -keystore keystore_file -providerName sdkms-jce -storetype SDKMS

Import Password as Secret Key

keytool -importpassword -alias alias -storepass groupId -keystore keystore_file -providerName sdkms-jce -storetype SDKMS

List the above generated AES Key

keytool -list -v -keystore keystore_file -providerName sdkms-jce -storetype SDKMS -storepass 2ff36949-ee70-4145-bd57-7de1ada5c050

Delete the above AES Key

keytool -delete -alias alias -keystore keystore_file -providerName sdkms-jce -storetype SDKMS -storepass 2ff36949-ee70-4145-bd57-7de1ada5c050

11.0 Jarsigner

To generate an entity's signature for a file, the entity must first have a public/private key pair associated with it and one or more certificates that authenticate its public key. The jarsignercommand uses key and certificate information from a keystore to generate digital signatures for JAR files.

For more information, refer to Oracle jarsigner.

11.1 Syntax

jarsigner -keystore <keystore_file> -storepass <storepassword> <filenameTosigned> <alias>

11.2 Examples

jarsigner -keystore $KEYSTORE_PATH -storepass $JCE_SIGNING_PASSWD $JARFILE $ALIAS

jarsigner -keystore $KEYSTORE -providerName $PROVIDER_NAME -sigalg SHA256withRSA -storetype $TYPE -storepass $PASSWD $RESOURCES_PATH"/JCETest-0.0.1.jar" jcetest

jarsigner -verify $RESOURCES_PATH"/JCETest-0.0.1.jar" -providerName $PROVIDER_NAME -sigalg SHA256withRSA

11.3 Environment Setup

Set the environment variables FORTANIX_API_ENDPOINT and FORTANIX_API_KEY using the following commands:

export FORTANIX_API_ENDPOINT=https://<FORTANIX_DSM_URL>
export FORTANIX_API_KEY=<API Key>

Add the sdkms-jce-provider JAR inside the folder $JAVA_HOME/jre/lib/ext/ .

You can generate a private key and its public certificate using the keytool command as shown below. This command will generate the file keystore1 locally and a private key named jcetest in Fortanix DSM.
You must provide the Fortanix DSM Group ID as the storepass option.

keytool -genkey -alias jcetest -keyalg RSA -keystore keystore1 -keysize 1024 -providername sdkms-jce -storetype SDKMS -storepass d7e89ac7-f0dc-49d1-9196-75aaf6afc47c

Sign the JAR using the following command:

jarsigner -keystore keystore1 -providerName sdkms-jce -sigalg SHA256withRSA -storetype SDKMS -storepass d7e89ac7-f0dc-49d1-9196-75aaf6afc47c a.jar jcetest

11.4 Jarsigner Using Existing Keys

To sign the JAR using existing keys, import the existing private key along with its certificate chain into Fortanix DSM using the sdkms-cli tool, and then use the private key alias for signing the JAR.

12.0 Java Examples

12.1 Generate RSA Keys

//Generate RSA Keys:
SdkmsJCE provider = SdkmsJCE.getInstance();
String algorithm = AlgorithmParameters.RSA;
KeyPairGenerator kpg = KeyPairGenerator.getInstance(algorithm, provider);
SecurityObjectParameterSpec parameterSpec = new SecurityObjectParameterSpec(false);
kpg.initialize(keySize);
kpg.initialize(parameterSpec, null);
KeyPair keyPair = kpg.genKeyPair();

12.2 RSA Sign and Verify

...
String algorithm = AlgorithmParameters.RSA;
KeyPair rsaKeyPair = keyGenerator.generateKeyPair();
Signature sig = Signature.getInstance(algorithm, provider);
sig.initSign(rsaKeyPair.getPrivate());

//sign
byte[] data = "test".getBytes("UTF8");
Signature sig = Signature.getInstance(“SHA256withRSA”, provider);
sig.initSign(keyPair.getPrivate());
sig.update(data);
byte[] signatureBytes = sig.sign();

//verify
sig.initVerify(keyPair.getPublic());
sig.update(data);
assertEquals(true, sig.verify(signatureBytes));

12.3 Generate AES Keys

SdkmsJCE provider = SdkmsJCE.getInstance();
String algorithm = AlgorithmParameters.AES;
KeyPairGenerator keyGenerator = KeyPairGenerator.getInstance(algorithm, provider);
keyGenerator.initialize(256);
SecretKey aesKey = keyGenerator.generateKey();

12.4 AES Cipher Encryption and Decryption

...
String algorithm = AlgorithmParameters.AES;
String mode = CipherMode.ECB.toString();
String padding = ProviderConstants.PKCS5PADDING

SecretKey secretKey = keyGenerator.generateKey();

Cipher cipher = Cipher.getInstance(algorithm, provider);
cipher.init(Cipher.ENCRYPT_MODE, secretKey);

String PLAIN = "testData";
// encryption
byte[] cipherBytes = cipher.doFinal(PLAIN.getBytes());

// decryption
cipher.init(Cipher.DECRYPT_MODE, key, params);
byte[] plainBytes = cipher.doFinal(cipherBytes);

// verify
assertEquals(new String(plainBytes), PLAIN);

12.5 AES Cipher Encryption and Decryption Using Existing Keys in DSM

Instantiate an SobjectDescriptor with either key name or key ID.

@ApiModel(
    description = "This uniquely identifies a persisted or transient sobject. Exactly one of `kid`, `name`, and `transient_key` must be present. "
)
public class SobjectDescriptor {
    @JsonProperty("kid")
    private String kid = null;
    @JsonProperty("name")
    private String name = null;
    @JsonProperty("transient_key")
    private String transientKey = null;

Instantiate SdkmsAESKey object using the Sobjectdescriptor.

public SdkmsAESKey(SobjectDescriptor descriptor) {
    super(descriptor);
}

Or, if you have the key ID, use the following constructor without instantiating the SobjectDescriptor.

public SdkmsAESKey(String keyId, Integer keySize, String transientKey) {
    this(new SobjectDescriptor().kid(keyId).transientKey(transientKey));
    this.keySize = keySize;
}

After the key object (let's say key ) has been instantiated, it can be supplied for encryption as shown below:

cipher.init(Cipher.ENCRYPT_MODE, key, params);

// Encrypted content 
byte[] cipherBytes = cipher.doFinal(PLAIN.getBytes());
// decrypt the same content 
cipher.init(Cipher.DECRYPT_MODE, key, params);
byte[] plainBytes = cipher.doFinal(cipherBytes);

12.6 AES Cipher Encryption and Decryption Multipart

private void testAesGcmCcmPkcs5(Integer keySize, CryptMode mode, boolean multiPart, byte[] blob) throws InvalidKeyException, NoSuchAlgorithmException, NoSuchPaddingException, IllegalBlockSizeException, BadPaddingException, InvalidAlgorithmParameterException, IOException {
    String algorithm = String.format("AES_%d/%s/%s", keySize, mode.toString(), ProviderConstants.PKCS5PADDING);
    Cipher cipher = Cipher.getInstance(algorithm, provider);
    SecretKey secretKey = generateAESKey(keySize);
    AlgorithmParameters params = cipher.getParameters();

    int chunkSize = 1024; // 1KB

    ByteArrayOutputStream cipherStream = new ByteArrayOutputStream();
    cipher.init(Cipher.ENCRYPT_MODE, secretKey, params);
    cipher.updateAAD("TestAAD".getBytes());
    if (!multiPart) {
        cipherStream.write(cipher.update(blob));
    }
    else {
        int offset = 0;
        int size  = chunkSize;
        int remaining = blob.length - size;
        cipherStream.write(cipher.update(blob, offset, size));
        while(remaining > 0) {
            offset = size;
            int nextChunk  = Math.min(remaining, chunkSize);
            cipherStream.write(cipher.update(blob, offset, nextChunk));
            size += nextChunk;
            remaining = blob.length - size;
        }
    }
    cipherStream.write(cipher.doFinal());
    byte[] cipherBytes = cipherStream.toByteArray();

    ByteArrayOutputStream plainStream = new ByteArrayOutputStream();
    cipher.init(Cipher.DECRYPT_MODE, secretKey, params);
    cipher.updateAAD("TestAAD".getBytes());
    if (!multiPart) {
        plainStream.write(cipher.doFinal(cipherBytes));
    }
    else {
        int offset = 0;
        int size  = chunkSize;
        int remaining = cipherBytes.length - size;
        plainStream.write(cipher.update(cipherBytes, offset, size));
        while(remaining > chunkSize) {
            offset = size;
            plainStream.write(cipher.update(cipherBytes, offset, chunkSize));
            size += chunkSize;
            remaining = cipherBytes.length - size;
        }
        // while decrypting, the final chunk need to be passed to doFinal for extracting the tag.
        plainStream.write(cipher.doFinal(cipherBytes, size, remaining));
    }

    // after going through encryption and decryption we should get same plain text back
    assertEquals(plainStream.toString(), new String(blob));
}

12.7 Storing RSA Key in KeyStore

KeyStore keyStore = KeyStore.getInstance("SDKMS", provider); // here can you either use SDKMS or sdkms-local as provider 

keyStore.load(null, null);
KeyPairGenerator gen = KeyPairGenerator.getInstance("RSA", provider);
gen.initialize(2048);
KeyPair keyPair = gen.generateKeyPair();
keyStore.load(null, null);
keyStore.setKeyEntry(alias, keyPair.getPrivate(), SDKMS_GROUPID.toCharArray(), null);

12.8 Storing Secret Key in KeyStore

KeyGenerator gen = KeyGenerator.getInstance("AES", provider);
gen.init(128);
Key key = gen.generateKey();
keyStore.load(null, null);
keyStore.setKeyEntry(alias, key, SDKMS_GROUPID.toCharArray(), null);

12.9 Storing Certificate in KeyStore

...
 CertificateFactory certificateFactory = CertificateFactory.getInstance("X.509");
 InputStream certificateInputStream = new FileInputStream("certificate.crt");
 Certificate certificate = certificateFactory.generateCertificate(certificateInputStream);
 keyStore.setCertificateEntry("certName", cert);

12.10 Listing Alias of KeyStore

...
Enumeration keys = keyStore.aliases();
while (keys.hasMoreElements()) {
    keys.nextElement(); 
}

12.11 Deleting an Alias from KeyStore

...
keyStore.deleteEntry(alias);

12.12 Creating KeyStore for SSL/TLS

FileInputStream keyInputStream = new FileInputStream(PRIVATE_KEY_PATH);
byte[] keyBytes = new byte[keyInputStream.available()];
keyInputStream.read(keyBytes);

keyInputStream.close();

String privateKey = new String(keyBytes, "UTF-8");
privateKey = privateKey.replaceAll("(-+BEGIN PRIVATE KEY-+\\r?\\n|-+END PRIVATE KEY-+\\r?\\n?)", "");

BASE64Decoder decoder = new BASE64Decoder();
keyBytes = decoder.decodeBuffer(privateKey);

PKCS8EncodedKeySpec privKeySpec = new PKCS8EncodedKeySpec(keyBytes);
KeyFactory kf = KeyFactory.getInstance("RSA", provider);
PrivateKey pk = kf.generatePrivate(privKeySpec);

CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
FileInputStream certInputStream = new FileInputStream(CERTIFICATE_PATH);
Certificate cert = certFactory.generateCertificate(certInputStream);
Certificate[] chain = new Certificate[1];

KeyStore keyStore = KeyStore.getInstance("SDKMS-local", provider);
keyStore.load(null,null);
keyStore.setKeyEntry(TLS_CLIENT_KEY_NAME, pk, null, chain);

OutputStream stream = new FileOutputStream(TLS_KEYSTOR_PATH);
keyStore.store(stream, null);

12.13 Setting SSL/TLS context

KeyStore keyStore = KeyStore.getInstance("SDKMS-local", provider);
InputStream inputStream = new FileInputStream(TLS_KEYSTORE_PATH);
keyStore.load(inputStream,null);
Enumeration<String> aliases = keyStore.aliases();
final String alias = aliases.nextElement();

// set ssl context
SSLContext sslContext = SSLContexts.custom()
    .loadKeyMaterial(keyStore, null, new PrivateKeyStrategy() {
        public String chooseAlias(Map<String, PrivateKeyDetails> aliases, Socket socket) {
            return alias;
        }
    }).loadTrustMaterial(null, new TrustStrategy() {
        public boolean isTrusted(X509Certificate[] x509Certificates, String s) throws CertificateException {
            return true;
        }
    })
    .build();

SSLConnectionSocketFactory sslConnectionSocketFactory = new SSLConnectionSocketFactory(sslContext,
    new String[]{"TLSv1.2", "TLSv1.1"},
    null,
    SSLConnectionSocketFactory.getDefaultHostnameVerifier());

CloseableHttpClient client = HttpClients.custom()
    .setSSLSocketFactory(sslConnectionSocketFactory)
    .build();
HttpGet httpget = new HttpGet(TLS_ENDPOINT);
CloseableHttpResponse response = client.execute(httpget);
HttpEntity entity = response.getEntity();

12.14 Import DSA Keys

import com.fortanix.sdkms.jce.provider; 
import java.security.*; 
import java.security.spec.DSAGenParameterSpec;

12.15 Generate DSA Keys

int keySize = 2048; 
int subGroupSize = 224; 
KeyPairGenerator kpg = KeyPairGenerator.getInstance("DSA", provider); 
DSAGenParameterSpec dsaGenParameterSpec = new DSAGenParameterSpec(keySize, subGroupSize); 
SecurityObjectParameterSpec parameterSpec = new SecurityObjectParameterSpec(dsaGenParameterSpec, false); 
kpg.initialize(parameterSpec, null); 
KeyPair keyPair = kpg.genKeyPair();

12.16 DSA Sign

byte[] data = "test".getBytes("UTF8");
Signature sig = Signature.getInstance("SHA1withDSA", provider);
sig.initSign(keyPair.getPrivate());
sig.update(data);
byte[] signatureBytes = sig.sign();

12.17 DSA Verify

sig.initVerify(keyPair.getPublic());
sig.update(data);

assertNotNull(sig);
assertEquals(true, sig.verify(signatureBytes));

12.18 Format Preserving Encryption (FPE)

The following is the sample code for generating tokenization objects.

FpeOptionsBasic basic = new FpeOptionsBasic();
basic.minLength(5).maxLength(5).radix(10);
int size = 256;
KeyGenerator keyGenerator = KeyGenerator.getInstance("AES",provider);
FpeParameterSpec fpeParameterSpec = new FpeParameterSpec(basic);
SecurityObjectParameterSpec parameterSpec = new SecurityObjectParameterSpec(fpeParameterSpec,false);
keyGenerator.init(size);
keyGenerator.init(parameterSpec);
SecretKey key = keyGenerator.generateKey();

The following is the sample code for encryption and decryption using tokenization. A tokenization object of a custom type is created.

int size = 256;
String mode= FPE;
String padding=NOPADDING;
String algorithm = String.format("AES_256/FPE/NOPADDING", keySize, mode, padding);
Cipher cipher = Cipher.getInstance(algorithm, provider);
SobjectDescriptor sobjDesc = new SobjectDescriptor().name("key_name");
KeyObject keyObj = SdkmsKeyService.getKeyObject(sobjDesc);
SdkmsAESKey key = new SdkmsAESKey(keyObj);
AlgorithmParameters params = cipher.getParameters();
cipher.init(Cipher.ENCRYPT_MODE, key, params);
String PLAIN = "123456789000";
// Encrypted content
byte[] cipherBytes = cipher.doFinal(PLAIN.getBytes());
// decrypt the same content
cipher.init(Cipher.DECRYPT_MODE, key, params);
byte[] plainBytes = cipher.doFinal(cipherBytes);;

DSM Java SDK and JCE Provider Documentation