Using the NinthTest JCA Provider

The following sections show code examples of common/recommended usage scenarios by algorithm.

These examples are not exhaustive; please refer to the Java™ Cryptography Architecture Core Classes and Interfaces and the NinthTest JCA Provider API documentation for more information.

Please refer to Security services provided by the NinthTest JCA provider for more detailed information about the supported algorithms and services.

Helix

Creating Helix secret keys

Generate a 256-bit random secret key

The recommended Helix key size is 256 bits (which is also the maximum key size). The NinthTest JCA Provider uses a 256-bit key size as the default when generating a random secret key.

KeyGenerator keyGenerator = KeyGenerator.getInstance("Helix", "NinthTest");
SecretKey secretKey = keyGenerator.generateKey();
Generate a random secret key of a specified size

Initialize the key generator with a size in bits (must be less than 256 and a multiple of eight) to create a secret key with a specified size.

Key sizes less than 128 bits are not recommended.

KeyGenerator keyGenerator = KeyGenerator.getInstance("Helix", "NinthTest");
keyGenerator.init(192);
SecretKey secretKey = keyGenerator.generateKey();
Generate a secret key from key material

Store the raw bytes in a Helix key specification, then use a secret key factory to create the secret key.

byte[] keyMaterial = "KeepMeSecret".getBytes("UTF-8");
HelixKeySpec keySpec = new HelixKeySpec(keyMaterial);
SecretKeyFactory keyFactory = SecretKeyFactory.getInstance("Helix", "NinthTest");
SecretKey secretKey = keyFactory.generateSecret(keySpec);

See:

Helix encryption

Initialize the Helix cipher with a randomly-generated nonce

Initializing the cipher for encryption without specifying a nonce causes the NinthTest JCA Provider to generate a random nonce. Be sure to save the generated nonce, as it will be required for decryption!

Cipher cipher = Cipher.getInstance("Helix", "NinthTest");
cipher.init(Cipher.ENCRYPT_MODE, secretKey);
byte[] randomNonce = cipher.getIV();
Initialize the Helix cipher with an explicit nonce

Store the nonce bytes in a Helix parameter specification, then initialize the cipher for encryption. The nonce must be 16 bytes in length.

byte[] nonce = "MustBe16Bytes!!!".getBytes("UTF-8");
HelixParameterSpec paramSpec = new HelixParameterSpec(nonce);
Cipher cipher = Cipher.getInstance("Helix", "NinthTest");
cipher.init(Cipher.ENCRYPT_MODE, secretKey, paramSpec);
Retrieve the generated MAC after encryption

Use the algorithm parameters returned by the cipher after a successful encryption operation (but before calling Cipher#init() again) to obtain the generated MAC bytes.

...
byte[] cipherText = cipher.doFinal(plainText);
AlgorithmParameters params = cipher.getParameters();
HelixParameterSpec paramSpec = params.getParameterSpec(HelixParameterSpec.class);
byte[] generatedMac = paramSpec.getMac();

See:

Helix message authentication

Note: It is not possible to initialize a Helix Mac without a Helix parameter specification, because Helix requires a nonce.

Generate a Helix MAC using a random nonce

Use a secure random number generator to generate the random nonce. Be sure to save this generated nonce; you must use the same nonce for encryption/decryption in order for the generated MAC to be useful.

SecureRandom prng = new SecureRandom();
byte[] randomNonce = new byte[16];
prng.nextBytes(randomNonce);
HelixParameterSpec paramSpec = new HelixParameterSpec(randomNonce);
Mac macFunction = Mac.getInstance("Helix", "NinthTest");
macFunction.init(secretKey, paramSpec);
byte[] mac = macFunction.doFinal(plainText);
Generate a Helix MAC using a specified nonce
byte[] nonce = "MustBe16Bytes!!!".getBytes("UTF-8");
HelixParameterSpec paramSpec = new HelixParameterSpec(nonce);
Mac macFunction = Mac.getInstance("Helix", "NinthTest");
macFunction.init(secretKey, paramSpec);
byte[] mac = macFunction.doFinal(plainText);

See:

Helix decryption

Decrypt and authenticate a message

Specify the expected MAC as part of the Helix parameter specification. If message authentication fails, an exception is thrown.

HelixParameterSpec paramSpec = new HelixParameterSpec(nonce, expectedMac);
Cipher cipher = Cipher.getInstance("Helix", "NinthTest");
cipher.init(Cipher.DECRYPT_MODE, secretKey, paramSpec);
// throws MessageAuthenticationException if message authentication fails
byte[] plainText = cipher.doFinal(cipherText);
Decrypt only

Do not include the expected MAC as part of the Helix parameter specification. Message authentication will be bypassed (i.e. Helix will be used as a pure stream cipher).

HelixParameterSpec paramSpec = new HelixParameterSpec(nonce);
Cipher cipher = Cipher.getInstance("Helix", "NinthTest");
cipher.init(Cipher.DECRYPT_MODE, secretKey, paramSpec);
// message authentication is not attempted
byte[] plainText = cipher.doFinal(cipherText);

See:

Helix pseudo-random number generation (PRNG)

Generate pseudo-random numbers using Helix
SecureRandom prng = SecureRandom.getInstance("Helix");
byte bytes[] = new byte[16];
prng.nextBytes(bytes);

See:

Non-provider usage of Helix

The Helix cryptographic primitive may also be used independently of the JCA by using the classes defined in the net.ninthtest.crypto.helix package.

Non-provider Helix encryption
HelixPrimitive helixEncryption = new HelixEncryption(key, nonce);
byte[] cipherText = helixEncryption.finish(plainText);
byte[] generatedMac = helixEncryption.getGeneratedMac();
Non-provider Helix decryption with MAC verification

Specify the expected MAC when constructing HelixDecryption. If message authentication fails, an exception is thrown.

HelixPrimitive helixDecryption = new HelixDecryption(key, nonce, expectedMac);
// throws MessageAuthenticationException if expected MAC != generated MAC
byte[] plaintText = helixEncryption.finish(cipherText);
Non-provider Helix decryption only

Do not include the expected MAC when constructing HelixDecryption. Message authentication will be bypassed (i.e. Helix will be used as a pure stream cipher).

HelixPrimitive helixDecryption = new HelixDecryption(key, nonce);
// message authentication is not attempted
byte[] plaintText = helixEncryption.finish(cipherText);
Non-provider Helix pseudo-random number generation

The HelixRandom class is a subclass of java.util.Random.

Random rand = new HelixRandom();
int digit = rand.nextInt(10);

See: