Choosing Java Cryptographic Algorithms Part 2 – Single key symmetric encryption
Abstract
This is the 2nd of a three-part blog series covering Java cryptographic algorithms. The series covers how to implement the following:
- Hashing with SHA–512
- AES–256
- RSA–4096
This 2nd post details how to implement single key, symmetric, AES–256 encryption. Let’s get started.
Disclaimer
This post is solely informative. Critically think before using any information presented. Learn from it but ultimately make your own decisions at your own risk.
Requirements
I did all of the work for this post using the following major technologies. You may be able to do the same thing with different technologies or versions, but no guarantees.
- Java 1.8.0_152_x64
- Java Cryptography Extension (JCE) Unlimited Strength
- NetBeans 8.2 (Build 201609300101)
- Maven 3.0.5 (Bundled with NetBeans)
Download
Visit my GitHub Page to see all of my open source projects. The code for this post is located in project: thoth-cryptography
Symmetric Encryption
About
Symmetric encryption algorithms are based on a single key. This one key is used for both encryption and decryption. As such, symmetric algorithms should only be used where strict controls are in place to protect the key.
Symmetric algorithms are commonly used for encryption and decryption of data in secured environments. A good example of this is securing Microservice communication. If an OAuth–2/JWT architecture is out of scope, the API Gateway can use a symmetric algorithm’s single key to encrypt a token. This token is then passed to other Microservices. The other Microservices use the same key to decrypt token. Another good example are hyperlinks embedded in emails. The hyperlinks in emails contain an encoded token which allow automatic login request processing when the hyperlink is clicked. This token is a strongly encrypted value generated by a symmetric algorithm so it can only be decoded on the application server. And of course, anytime passwords or credentials of any kind need to be protected, a symmetric algorithm is used to encrypt them and the bytes can later be decrypted with the same key.
Research done as of today seems to indicate the best and most secure single key, symmetric, encryption algorithm is the following (Sheth, 2017, “Choosing the correct algorithm”, para.2):
- Algorithm: AES
- Mode: GCM
- Padding: PKCS5Padding
- Key size: 256 bit
- IV size: 96 bit
AES–256 uses a 256-bit key which requires installation of the Java Cryptography Extension (JCE) Unlimited Strength package. Let’s take a look at an example.
NOTE: The Java Cryptography Extension (JCE) Unlimited Strength package is required for 256-bit keys. If it’s not installed, 128-bit keys are the max.
Example
If you don’t already have it, download and install the Java Cryptography Extension (JCE) Unlimited Strength package. It is required to use 256-bit keys. Otherwise, the example below must be updated to use a 128-bit key.
Listing 1 is the AesTest.java unit test. It is a full demonstration on the following:
- Generate and store an AES 256-bit key
- AES Encryption
- AES Decryption
Listing 2 shows AesSecretKeyProducer.java. This is a helper class which is responsible for producing a new key or reproducing an existing key from a byte[]
.
Listing 3 shows ByteArrayWriter.java and Listing 4 shows ByteArrayReader.java. These are helper classes responsible for reading and writing a byte[]
to a file. It’s up to you to determine how to store the byte[]
of your key, but it needs to be stored securely somewhere (file, database, git repository, etc.).
Finally, Listing 5 shows Aes.java. This is a helper class which is responsible for both encryption and decryption.
Listing 1 – AesTest.java class
package org.thoth.crypto.symmetric; import java.io.ByteArrayOutputStream; import java.nio.file.Path; import java.nio.file.Paths; import java.util.Optional; import javax.crypto.SecretKey; import org.junit.Assert; import org.junit.BeforeClass; import org.junit.Test; import org.thoth.crypto.io.ByteArrayReader; import org.thoth.crypto.io.ByteArrayWriter; /** * * @author Michael Remijan mjremijan@yahoo.com @mjremijan */ public class AesTest { static Path secretKeyFile; @BeforeClass public static void beforeClass() throws Exception { // Store the SecretKey bytes in the ./target diretory. Do // this so it will be ignore by source control. We don't // want this file committed. secretKeyFile = Paths.get("./target/Aes256.key").toAbsolutePath(); // Generate a SecretKey for the test SecretKey secretKey = new AesSecretKeyProducer().produce(); // Store the byte[] of the SecretKey. This is the // "private key file" you want to keep safe. ByteArrayWriter writer = new ByteArrayWriter(secretKeyFile); writer.write(secretKey.getEncoded()); } @Test public void encrypt_and_decrypt_using_same_Aes256_instance() { // setup SecretKey secretKey = new AesSecretKeyProducer().produce( new ByteArrayReader(secretKeyFile).read() ); Aes aes = new Aes(secretKey); String toEncrypt = "encrypt me"; // run byte[] encryptedBytes = aes.encrypt(toEncrypt, Optional.empty()); String decrypted = aes.decrypt(encryptedBytes, Optional.empty()); // assert Assert.assertEquals(toEncrypt, decrypted); } public void encrypt_and_decrypt_with_aad_using_same_Aes256_instance() { // setup SecretKey secretKey = new AesSecretKeyProducer().produce( new ByteArrayReader(secretKeyFile).read() ); Aes aes = new Aes(secretKey); String toEncrypt = "encrypt me aad"; // run byte[] encryptedBytes = aes.encrypt(toEncrypt, Optional.of("JUnit AAD")); String decrypted = aes.decrypt(encryptedBytes, Optional.of("JUnit AAD")); // assert Assert.assertEquals(toEncrypt, decrypted); } @Test public void encrypt_and_decrypt_using_different_Aes256_instance() throws Exception { // setup SecretKey secretKey = new AesSecretKeyProducer().produce( new ByteArrayReader(secretKeyFile).read() ); Aes aesForEncrypt = new Aes(secretKey); Aes aesForDecrypt = new Aes(secretKey); String toEncrypt = "encrypt me"; // run byte[] encryptedBytes = aesForEncrypt.encrypt(toEncrypt, Optional.empty()); ByteArrayOutputStream baos = new ByteArrayOutputStream(); baos.write(encryptedBytes); String decrypted = aesForDecrypt.decrypt(baos.toByteArray(), Optional.empty()); // assert Assert.assertEquals(toEncrypt, decrypted); } }
Listing 2 – AesSecretKeyProducer.java class
package org.thoth.crypto.symmetric; import javax.crypto.KeyGenerator; import javax.crypto.SecretKey; import javax.crypto.spec.SecretKeySpec; /** * * @author Michael Remijan mjremijan@yahoo.com @mjremijan */ public class AesSecretKeyProducer { /** * Generates a new AES-256 bit {@code SecretKey}. * * @return {@code SecretKey}, never null * @throws RuntimeException All exceptions are caught and re-thrown as {@code RuntimeException} */ public SecretKey produce() { KeyGenerator keyGen; try { keyGen = KeyGenerator.getInstance("AES"); keyGen.init(256); SecretKey secretKey = keyGen.generateKey(); return secretKey; } catch (Exception ex) { throw new RuntimeException(ex); } } /** * Generates an AES-256 bit {@code SecretKey}. * * @param encodedByteArray The bytes this method will use to regenerate a previously created {@code SecretKey} * * @return {@code SecretKey}, never null * @throws RuntimeException All exceptions are caught and re-thrown as {@code RuntimeException} */ public SecretKey produce(byte [] encodedByteArray) { try { return new SecretKeySpec(encodedByteArray, "AES"); } catch (Exception ex) { throw new RuntimeException(ex); } } }
Listing 3 – ByteArrayWriter.java class
package org.thoth.crypto.io; import java.io.IOException; import java.io.OutputStream; import java.io.PrintWriter; import java.nio.file.Files; import java.nio.file.Path; /** * * @author Michael Remijan mjremijan@yahoo.com @mjremijan */ public class ByteArrayWriter { protected Path outputFile; private void initOutputFile(Path outputFile) { this.outputFile = outputFile; } private void initOutputDirectory() { Path outputDirectory = outputFile.getParent(); if (!Files.exists(outputDirectory)) { try { Files.createDirectories(outputDirectory); } catch (IOException e) { throw new RuntimeException(e); } } } public ByteArrayWriter(Path outputFile) { initOutputFile(outputFile); initOutputDirectory(); } public void write(byte[] bytesArrayToWrite) { try ( OutputStream os = Files.newOutputStream(outputFile); PrintWriter writer = new PrintWriter(os); ){ for (int i=0; i<bytesArrayToWrite.length; i++) { if (i>0) { writer.println(); } writer.print(bytesArrayToWrite[i]); } } catch (IOException ex) { throw new RuntimeException(ex); } } }
Listing 4 – ByteArrayReader.java class
package org.thoth.crypto.io; import java.io.ByteArrayOutputStream; import java.io.IOException; import java.nio.file.Path; import java.util.Scanner; /** * * @author Michael Remijan mjremijan@yahoo.com @mjremijan */ public class ByteArrayReader { protected Path inputFile; public ByteArrayReader(Path inputFile) { this.inputFile = inputFile; } public byte[] read() { try ( Scanner scanner = new Scanner(inputFile); ByteArrayOutputStream baos = new ByteArrayOutputStream(); ){ while (scanner.hasNext()) { baos.write(Byte.parseByte(scanner.nextLine())); } baos.flush(); return baos.toByteArray(); } catch (IOException ex) { throw new RuntimeException(ex); } } }
Listing 5 – Aes.java class
package org.thoth.crypto.symmetric; import java.security.SecureRandom; import java.util.Optional; import javax.crypto.Cipher; import javax.crypto.SecretKey; import javax.crypto.spec.GCMParameterSpec; /** * * @author Michael Remijan mjremijan@yahoo.com @mjremijan */ public class Aes { // If you don't have the Java Cryptography Extension // (JCE) Unlimited Strength packaged installed, use // a 128 bit KEY_SIZE. public static int KEY_SIZE = 256; public static int IV_SIZE = 12; // 12bytes * 8 = 96bits public static int TAG_BIT_SIZE = 128; public static String ALGORITHM_NAME = "AES"; public static String MODE_OF_OPERATION = "GCM"; public static String PADDING_SCHEME = "PKCS5Padding"; protected SecretKey secretKey; protected SecureRandom secureRandom; public Aes(SecretKey secretKey) { this.secretKey = secretKey; this.secureRandom = new SecureRandom(); } public byte[] encrypt(String message, Optional<String> aad) { try { // Transformation specifies algortihm, mode of operation and padding Cipher c = Cipher.getInstance( String.format("%s/%s/%s",ALGORITHM_NAME,MODE_OF_OPERATION,PADDING_SCHEME) ); // Generate IV byte iv[] = new byte[IV_SIZE]; secureRandom.nextBytes(iv); // SecureRandom initialized using self-seeding // Initialize GCM Parameters GCMParameterSpec spec = new GCMParameterSpec(TAG_BIT_SIZE, iv); // Init for encryption c.init(Cipher.ENCRYPT_MODE, secretKey, spec, secureRandom); // Add AAD tag data if present aad.ifPresent(t -> { try { c.updateAAD(t.getBytes("UTF-8")); } catch (Exception e) { throw new RuntimeException(e); } }); // Add message to encrypt c.update(message.getBytes("UTF-8")); // Encrypt byte[] encryptedBytes = c.doFinal(); // Concatinate IV and encrypted bytes. The IV is needed later // in order to to decrypt. The IV value does not need to be // kept secret, so it's OK to encode it in the return value // // Create a new byte[] the combined length of IV and encryptedBytes byte[] ivPlusEncryptedBytes = new byte[iv.length + encryptedBytes.length]; // Copy IV bytes into the new array System.arraycopy(iv, 0, ivPlusEncryptedBytes, 0, iv.length); // Copy encryptedBytes into the new array System.arraycopy(encryptedBytes, 0, ivPlusEncryptedBytes, iv.length, encryptedBytes.length); // Return return ivPlusEncryptedBytes; } catch (Exception e) { throw new RuntimeException(e); } } public String decrypt(byte[] ivPlusEncryptedBytes, Optional<String> aad) { try { // Get IV byte iv[] = new byte[IV_SIZE]; System.arraycopy(ivPlusEncryptedBytes, 0, iv, 0, IV_SIZE); // Initialize GCM Parameters GCMParameterSpec spec = new GCMParameterSpec(TAG_BIT_SIZE, iv); // Transformation specifies algortihm, mode of operation and padding Cipher c = Cipher.getInstance( String.format("%s/%s/%s",ALGORITHM_NAME,MODE_OF_OPERATION,PADDING_SCHEME) ); // Get encrypted bytes byte [] encryptedBytes = new byte[ivPlusEncryptedBytes.length - IV_SIZE]; System.arraycopy(ivPlusEncryptedBytes, IV_SIZE, encryptedBytes, 0, encryptedBytes.length); // Init for decryption c.init(Cipher.DECRYPT_MODE, secretKey, spec, secureRandom); // Add AAD tag data if present aad.ifPresent(t -> { try { c.updateAAD(t.getBytes("UTF-8")); } catch (Exception e) { throw new RuntimeException(e); } }); // Add message to decrypt c.update(encryptedBytes); // Decrypt byte[] decryptedBytes = c.doFinal(); // Return return new String(decryptedBytes, "UTF-8"); } catch (Exception e) { throw new RuntimeException(e); } } }
Summary
Encryption isn’t easy. And easy examples will result in implementations with security vulnerabilities for your application. If you need a single key, symmetric, encryption algorithm, use cipher AES/GCM/PKCS5Padding with a 256 bit key and a 96 bit IV.
References
- Java Cryptography Extension (JCE) Unlimited Strength. (n.d.). Retrieved from http://www.oracle.com/technetwork/java/javase/downloads/jce8-download-2133166.html.
- Sheth, M. (2017, April 18). Encryption and Decryption in Java Cryptography. Retrieved from https://www.veracode.com/blog/research/encryption-and-decryption-java-cryptography.
- cpast[ Says GCM IV is 96bit which is 96/8 = 12 bytes]. (2015, June 4). Encrypting using AES–256, can I use 256 bits IV [Web log comment]. Retrieved from https://security.stackexchange.com/questions/90848/encrypting-using-aes-256-can-i-use-256-bits-iv.
- Bodewes[ Says GCM IV is strongly recommended to be 12 bytes (12*8 = 96) but can be of any size. Other sizes will require additional calculations], M. (2015, July 7). Ciphertext and tag size and IV transmission with AES in GCM mode [Web log comment]. Retrieved from https://crypto.stackexchange.com/questions/26783/ciphertext-and-tag-size-and-iv-transmission-with-aes-in-gcm-mode.
- Figlesquidge. (2013, October 18). What’s the difference between a ‘cipher’ and a ‘mode of operation’? [Web log comment]. Retrieved from https://crypto.stackexchange.com/questions/11132/what-is-the-difference-between-a-cipher-and-a-mode-of-operation.
- Toust, S. (2013, February 4). Why does the recommended key size between symmetric and asymmetric encryption differ greatly?. Retrieved from https://crypto.stackexchange.com/questions/6236/why-does-the-recommended-key-size-between-symmetric-and-asymmetric-encryption-di.
- Karonen, I. (2012, October 5). What is the main difference between a key, an IV and a nonce?. Retrieved from https://crypto.stackexchange.com/questions/3965/what-is-the-main-difference-between-a-key-an-iv-and-a-nonce.
- Block cipher mode of operation. (2017, November 6). Wikipedia. Retrieved from https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Initialization_vector_.28IV.29
Published on Java Code Geeks with permission by Michael Remijan, partner at our JCG program. See the original article here: Choosing Java Cryptographic Algorithms Part 2 – Single key symmetric encryption Opinions expressed by Java Code Geeks contributors are their own. |
Very helpful crystal clear article and code examples, thank you!