Code samples

Updated at:

These samples show how to use the KMS Java Cryptography Extension (JCE) provider to perform common cryptographic operations, including AES-GCM encryption and decryption using a persistent symmetric key, RSA encryption, decryption, signing, and verification using a persistent key pair, and hardware-backed random number generation using AES-CTR-DRBG.

AES key with label (persistent key)

AesKeyPersistWithLabel demonstrates how to generate a 256-bit AES key, persist it in the HSM under a label, retrieve it by label, perform AES-GCM encryption and decryption, and delete the key when done. The IV for GCM is generated locally and passed to the cipher. After encryption, retrieve the IV from the cipher using getIV() for use in decryption.

import com.cavium.cfm2.CFM2Exception;
import com.cavium.cfm2.LoginManager;
import com.cavium.cfm2.Util;
import com.cavium.key.CaviumKey;
import com.cavium.key.parameter.CaviumAESKeyGenParameterSpec;
import com.cavium.key.store.CaviumKeyStore;
import com.cavium.provider.CaviumProvider;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import javax.crypto.*;
import javax.crypto.spec.GCMParameterSpec;
import java.io.IOException;
import java.security.*;
import java.util.Arrays;
import java.util.Optional;
import java.util.Random;

public class AesKeyPersistWithLabel {
  private static final Logger logger = LogManager.getLogger("AesKeyPersistWithLabel");
  private static final String AES_KEY_LABEL = "aes_key_test";
  private static final String PLAIN_TEXT = "test_example";
  private static final int AES_KEY_SIZE = 256;

  public static void main(String[] args) {
    try {
      Security.addProvider(new CaviumProvider("Cavium", 1L, "The Cavium LiquidSecurity(tm) JCA Provider"));
      logger.info("**** Add Provider ****");
      LoginManager lm = LoginManager.getInstance();
      lm.login();
      logger.info("**** Login Success ****");
      // generate AESKey with label and persist key
      Key key = generateAesKeyAndPersist(AES_KEY_LABEL);
      Optional.ofNullable(key).orElseThrow(() -> new RuntimeException("generate key failed. "));
      // get key with label
      Key keyWithLabel = getKeyWithLabel(AES_KEY_LABEL);
      Optional.ofNullable(keyWithLabel).orElseThrow(() -> new RuntimeException("get key failed. label: " + keyWithLabel));
      // encrypt and decrypt
      encDecGcm((SecretKey) keyWithLabel);
      // delete key by label
      boolean b = deleteKeyWithLabel(AES_KEY_LABEL);
      logger.info("**** Key has been deleted? : " + b + " ****");
      lm.logout();
      logger.info("**** Logout ****");
    } catch (IOException | CFM2Exception e) {
      e.printStackTrace();
    }
  }

  private static Key getKeyWithLabel(String label) {
    logger.info("**** Get Key With Label ****");
    try {
      CaviumKeyStore keyStore = new CaviumKeyStore();
      return keyStore.engineGetKey(label, null);
    } catch (NoSuchAlgorithmException | UnrecoverableKeyException e) {
      e.printStackTrace();
    }
    return null;
  }

  private static boolean deleteKeyWithLabel(String label) {
    logger.info("**** Delete Key With Label ****");
    try {
      Key keyWithLabel = getKeyWithLabel(label);
      Util.deleteKey((CaviumKey) keyWithLabel);
      return true;
    } catch (CFM2Exception e) {
      e.printStackTrace();
    }
    return false;
  }

  private static Key generateAesKeyAndPersist(String label) {
    try {
      KeyGenerator kg = KeyGenerator.getInstance("AES", "Cavium");
      kg.init(new CaviumAESKeyGenParameterSpec(AES_KEY_SIZE, AES_KEY_LABEL, true, true));
      SecretKey secretKey = kg.generateKey();
      logger.info("**** Generate Aes Key And Persist Success ****");
      return secretKey;
    } catch (NoSuchAlgorithmException | NoSuchProviderException | InvalidAlgorithmParameterException e) {
      e.printStackTrace();
    }
    return null;
  }

  private static void encDecGcm(SecretKey k) {
    try {
      Cipher cp = Cipher.getInstance("AES/GCM/NoPadding", "Cavium");
      byte[] iv = new byte[12];
      Random r = new Random();
      r.nextBytes(iv);
      byte[] p = new byte[]{1};
      byte[] aad = new byte[]{2};
      //GCMParameterSpec specify 128-bit tag length and a 12-byte IV.
      logger.info("**** Encrypt ****");
      cp.init(Cipher.ENCRYPT_MODE, k, new GCMParameterSpec(128, iv));
      cp.updateAAD(aad);
      byte[] c = cp.doFinal(p);
      logger.info("**** Decrypt ****");
      byte[] newiv = cp.getIV();
      cp.init(Cipher.DECRYPT_MODE, k, new GCMParameterSpec(128, newiv));
      cp.updateAAD(aad);
      byte[] v = cp.doFinal(c);
      if (Arrays.equals(p, v)) {
        logger.info("**** Encrypt And Decrypt Success ****");
      } else {
        logger.error("**** Encrypt And Decrypt Failed ****");
      }
    } catch (NoSuchAlgorithmException | NoSuchProviderException | NoSuchPaddingException | InvalidKeyException | InvalidAlgorithmParameterException | IllegalBlockSizeException | BadPaddingException e) {
      e.printStackTrace();
    }
  }
}

RSA key with label (persistent key)

RsaKeyPersistWithLabel demonstrates how to generate a 2048-bit RSA key pair, persist both the public and private keys in the HSM under separate labels, encrypt with the public key using RSA/ECB/OAEPPADDING, decrypt with the private key retrieved by label, sign a message with SHA256WithRSA/PSS, verify the signature, and delete both keys.

import com.cavium.cfm2.LoginManager;
import com.cavium.cfm2.Util;
import com.cavium.key.CaviumKey;
import com.cavium.key.parameter.CaviumRSAKeyGenParameterSpec;
import com.cavium.key.store.CaviumKeyStore;
import com.cavium.provider.CaviumProvider;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import javax.crypto.BadPaddingException;
import javax.crypto.Cipher;
import javax.crypto.IllegalBlockSizeException;
import javax.crypto.NoSuchPaddingException;
import java.math.BigInteger;
import java.security.*;
import java.util.Arrays;

public class RsaKeyPersistWithLabel {
  private static final Logger logger = LogManager.getLogger("RsaKeyPersistWithLabel");
  private static final String TRANSFORMATION = "RSA/ECB/OAEPPADDING";
  private static final String SIGN_ALGORITHM = "SHA256WithRSA/PSS";
  private static final String PUBLIC_KEY_LABEL = "rsa_test_publickey";
  private static final String PRIVATE_KEY_LABEL = "rsa_test_privatekey";

  public static void main(String[] args) {
    try {
      Security.addProvider(new CaviumProvider("Cavium", 1L, "The Cavium LiquidSecurity(tm) JCA Provider"));
      logger.info("**** Add Provider ****");
      LoginManager lm = LoginManager.getInstance();
      lm.login();
      logger.info("**** Login Success ****");
      // Generate an Rsa key.
      KeyPair keyPair = generateRSAKeyPair();
      PrivateKey pk = keyPair.getPrivate();
      PublicKey puk = keyPair.getPublic();
      if (pk == null || puk == null) {
        logger.error("**** RSA Key Generate failed ****");
      }
      logger.info("**** RSA Key Generated ****");
      // pub key encrypt
      byte[] plaintext = "test".getBytes();
      CaviumKeyStore keyStore = new CaviumKeyStore();
      byte[] encryptResult = encrypt(TRANSFORMATION, puk, plaintext);
      if (encryptResult != null) {
        logger.info("**** RSA Encrypt Success ****");
      } else {
        logger.error("**** RSA Encrypt Failed ****");
        return;
      }
      // get privateKey by label
      Key privateKey = keyStore.engineGetKey(PRIVATE_KEY_LABEL, null);
      // pri key decrypt
      byte[] decryptResult = decrypt(TRANSFORMATION, privateKey, encryptResult);
      if (decryptResult != null && Arrays.equals(decryptResult, plaintext)) {
        logger.info("**** RSA Decrypt Success ****");
      } else {
        logger.error("**** RSA Decrypt Failed ****");
        return;
      }
      // sign
      byte[] signResult = sign(plaintext, (PrivateKey) privateKey, SIGN_ALGORITHM);
      // verify
      boolean verify = verify(plaintext, signResult, puk, SIGN_ALGORITHM);
      if (verify) {
        logger.info("**** Signature verified ****");
      } else {
        logger.error("**** Signature is invalid! ****");
      }
      // delete key
      Util.deleteKey((CaviumKey) privateKey);
      Util.deleteKey((CaviumKey) puk);
      KeyStore.Entry entry = keyStore.engineGetEntry(PRIVATE_KEY_LABEL, null);
      if (entry != null) {
        logger.error("**** Delete Failed ****");
      } else {
        logger.info("**** Key Deleted ****");
      }
      lm.logout();
      logger.info("**** Logout ****");
    } catch (Exception e) {
      e.printStackTrace();
    }
  }

  public static byte[] encrypt(String transformation, Key key, byte[] plainText) {
    logger.info("**** RSA Key Encrypt ****");
    try {
      Cipher encCipher = Cipher.getInstance(transformation, "Cavium");
      encCipher.init(Cipher.ENCRYPT_MODE, key);
      return encCipher.doFinal(plainText);
    } catch (NoSuchAlgorithmException | NoSuchProviderException | NoSuchPaddingException | InvalidKeyException | BadPaddingException | IllegalBlockSizeException e) {
      e.printStackTrace();
    }
    return null;
  }

  public static byte[] decrypt(String transformation, Key key, byte[] cipherText) {
    logger.info("**** RSA Key Decrypt ****");
    try {
      Cipher decCipher = Cipher.getInstance(transformation, "Cavium");
      decCipher.init(Cipher.DECRYPT_MODE, key);
      return decCipher.doFinal(cipherText);
    } catch (NoSuchAlgorithmException | NoSuchProviderException | NoSuchPaddingException | InvalidKeyException | IllegalBlockSizeException | BadPaddingException e) {
      e.printStackTrace();
    }
    return null;
  }

  public static byte[] sign(byte[] message, PrivateKey key, String signingAlgorithm) {
    logger.info("**** RSA Key Sign ****");
    try {
      Signature sig = Signature.getInstance(signingAlgorithm, "Cavium");
      sig.initSign(key);
      sig.update(message);
      return sig.sign();
    } catch (NoSuchAlgorithmException | NoSuchProviderException | InvalidKeyException | SignatureException e) {
      e.printStackTrace();
    }
    return null;
  }

  public static boolean verify(byte[] message, byte[] signature, PublicKey publicKey, String signingAlgorithm) {
    logger.info("**** RSA Key Verify ****");
    try {
      Signature sig = Signature.getInstance(signingAlgorithm, "Cavium");
      sig.initVerify(publicKey);
      sig.update(message);
      return sig.verify(signature);
    } catch (NoSuchAlgorithmException | NoSuchProviderException | InvalidKeyException | SignatureException e) {
      e.printStackTrace();
    }
    return false;
  }

  private static KeyPair generateRSAKeyPair() throws
      Exception {
    KeyPairGenerator kpg = KeyPairGenerator.getInstance("RSA", "Cavium");
    kpg.initialize(new CaviumRSAKeyGenParameterSpec(2048, new
        BigInteger("65537"), PUBLIC_KEY_LABEL, PRIVATE_KEY_LABEL, true, true));
    return kpg.generateKeyPair();
  }
}

Generate a random number with SecureRandom

SecureRandomGenerateSeed demonstrates how to generate hardware-backed random bytes using the AES-CTR-DRBG algorithm provided by the HSM. Two methods are shown: nextBytes() fills a pre-allocated byte array, and generateSeed() returns a new byte array. Both produce 16 bytes of random data and print the result as a hex string.

import com.cavium.cfm2.CFM2Exception;
import com.cavium.cfm2.LoginManager;
import com.cavium.provider.CaviumProvider;
import com.sun.org.apache.xerces.internal.impl.dv.util.HexBin;
import org.apache.logging.log4j.LogManager;
import org.apache.logging.log4j.Logger;

import java.io.IOException;
import java.security.NoSuchAlgorithmException;
import java.security.NoSuchProviderException;
import java.security.SecureRandom;
import java.security.Security;
import java.util.Arrays;

public class SecureRandomGenerateSeed {
 private static final Logger logger = LogManager.getLogger("TestSecureRandom");

 public static void main(String[] args) throws NoSuchProviderException, NoSuchAlgorithmException, IOException, CFM2Exception {
  Security.addProvider(new CaviumProvider("Cavium", 1L, "The Cavium LiquidSecurity(tm) JCA Provider"));
  logger.info("**** Add Provider ****");
  LoginManager lm = LoginManager.getInstance();
  lm.login();
  logger.info("**** Login Success ****");
  SecureRandom random = SecureRandom.getInstance("AES-CTR-DRBG", "Cavium");
  try {
   generateRandomNumberByNextBytes(random);
   generateRandomNumberByGenerateSeed(random);
   logger.info("**** AES-CTR-DRBG by Cavium generateSeed with 16 bytes ****");
  } catch (Exception e) {
   logger.error("**** Failed ****");
   e.printStackTrace();
  }
 }

 public static void generateRandomNumberByNextBytes(SecureRandom random) {
  logger.info("**** Generate Random Number With SecureRandom.nextBytes() ****");
  byte[] bytes = new byte[16];
  random.nextBytes(bytes);
  System.out.println("nextBytes: " + Arrays.toString(bytes));
  System.out.println("HexString: " + HexBin.encode(bytes));
 }

 public static void generateRandomNumberByGenerateSeed(SecureRandom random) {
  logger.info("**** Generate Random Number With SecureRandom.generateSeed() ****");
  byte[] seed = random.generateSeed(16);
  System.out.println("generateSeed: " + Arrays.toString(seed));
  System.out.println("HexString: " + HexBin.encode(seed));
 }
}

Compile and run the sample code

The following steps use AesKeyPersistWithLabel as an example. Apply the same commands to the other sample classes.

  1. Set the library path. Replace /opt/hsm/lib/ with the path to your HSM library if it differs.

    export LD_LIBRARY_PATH=/opt/hsm/lib/:$LD_LIBRARY_PATH
  2. Compile the sample.

    javac -classpath .:/opt/hsm/java/* AesKeyPersistWithLabel.java

    If compilation succeeds, AesKeyPersistWithLabel.class is created in the current directory.

  3. Run the sample.

    java -classpath .:/opt/hsm/java/* AesKeyPersistWithLabel