cryptomator/siv-mode

RFC 5297 SIV mode of operation in Java

Java RFC 5297 SIV Authenticated Encryption

Features

• No dependencies (required BouncyCastle classes are repackaged)
• Passes official RFC 5297 test vectors
• Constant time authentication
• Defaults on AES, but supports any block cipher with a 128-bit block size.
• Supports any key sizes that the block cipher supports (e.g. 128/192/256-bit keys for AES)
• Thread-safe
• Fast
• Requires JDK 8+ or Android API Level 24+ (since version 1.4.0)

Audits

• Version 1.0.8 audit by Tim McLean (Issues fixed with 1.1.0)
• Version 1.2.1 audit by Cure53

Finding	Comment
1u1-22-001	The GPG key is used exclusively for the Maven repositories, is designed for signing only and is protected by a 30-character generated password (alphabet size: 96 chars). It is iterated and salted (SHA1 with 20971520 iterations). An offline attack is also very unattractive. Apart from that, this finding has no influence on the Tresor apps1. This was not known to Cure53 at the time of reporting.
1u1-22-002	As per contract of BlockCipher#processBlock(byte[], int, byte[], int), JceAesBlockCipher is designed to encrypt or decrypt just one single block at a time. JCE doesn't allow us to retrieve the plain cipher without a mode, so we explicitly request AES/ECB/NoPadding. This is by design, because we want the plain cipher for a single 128 bit block without any mode. We're not actually using ECB mode.

Usage

private static final SivMode AES_SIV = new SivMode();

public void encrypt() {
  byte[] encrypted = AES_SIV.encrypt(ctrKey, macKey, "hello world".getBytes());
  byte[] decrypted = AES_SIV.decrypt(ctrKey, macKey, encrypted);
}

public void encryptWithAssociatedData() {
  byte[] encrypted = AES_SIV.encrypt(ctrKey, macKey, "hello world".getBytes(), "associated".getBytes(), "data".getBytes());
  byte[] decrypted = AES_SIV.decrypt(ctrKey, macKey, encrypted, "associated".getBytes(), "data".getBytes());
}

Maven integration

<dependencies>
  <dependency>
    <groupId>org.cryptomator</groupId>
    <artifactId>siv-mode</artifactId>
    <version>1.4.0</version>
  </dependency>
</dependencies>

Java Module

From version 1.3.2 onwards this library is an explicit module with the name org.cryptomator.siv. You can use it by adding the following line to your module-info.java.

requires org.cryptomator.siv;

Because BouncyCastle classes are shaded, this library only depends on java.base.

Reproducible Builds

This is a Maven project that can be built using mvn install. However, if you want to build this reproducibly, please make sure:

1. Use the same build environment
   • The same JDK as our CI builds
   • Ideally the same same arch and OS (x86_64 Linux)
   • Same locale (en_US) and linebreaks (POSIX)
2. Use ./mvnw install instead (or ./mvnw verify or ./mvnw package -DskipTests, depending on your intentions)

License

Distributed under the MIT X Consortium license. See the LICENSE file for more info.

---

¹ The Cure53 pentesting was performed during the development of the apps for 1&1 Mail & Media GmbH.

siv-mode's Issues

S2V operation

I'm writing my own implementation of Cryptomator based on Architecture - Cryptomator and I've noticed that there's a difference in S2V operation in your code and the reference specification provided by RFC 5297

Is there a specific reason why you ignore a case when n is equal to zero

if n = 0 then
    return V = AES-CMAC(K, <one>)
fi

Thanks

Dev Feature Request: Allow for providing a JCE provider in JceAesBlockCipher

A developer may implement her own adaption of block cipher with BlockCipherFactory but if she only wants to change the used security provider with the default AES impl this is quiet cumbersome as the BC dependencies have to be satisfied to copy the impl.

I propose to let JceAesBlockCipher and SivMode accept a Provider argument.

PR follows.

ThreadLocal.withInitial(...) unavailable on Android 7.x

As described in cryptomator/android#335, this method is not available before API Level 26. Wen can increase compatibility of siv-mode by avoiding this method call.

Exception java.lang.NoClassDefFoundError: org/cryptomator/siv/org/bouncycastle/crypto/BlockCipher

Running the tests in cryptolib with siv-mode:1.5.1, an implementation test fails with java.lang.NoClassDefFoundError: org/cryptomator/siv/org/bouncycastle/crypto/BlockCipher.

Inspecting the siv-mode jar, it shows, that the shaded bouncycastle package is empty. This is due to a config bug in the POM after updating the bouncy-castle dependency in #45

Reviews of the SIV mode lib

Hi Sebastian,

Have there been any independent reviews of the SIV mode lib?

I consider using it in a OpenID Connect SDK for generating reversible pairwise user IDs
(http://www.javadoc.io/doc/com.nimbusds/oauth2-oidc-sdk/5.14)

Thanks,

Vladimir

Migrate to JUnit 5

Make the tests run on Java 8 and use JUnit 5, especially to make use of parameterized tests.

Performance optimizations

We used to manually generate a keystream and XOR it with the plaintext.

While this implemenation was correct, easy to review (and actually reviewed in two independent audits), it is not necessary.

It got therefore replaced with an easy-to-use BouncyCastle high-level API in commit 620a9ad:

siv-mode/src/main/java/org/cryptomator/siv/CustomCtrComputer.java

Lines 24 to 35 in 90b8cb6

	public byte[] computeCtr(byte[] input, byte[] key, byte[] iv) {
	SICBlockCipher cipher = new SICBlockCipher(blockCipherSupplier.get());
	CipherParameters params = new ParametersWithIV(new KeyParameter(key), iv);
	cipher.init(true, params);
	try {
	byte[] output = new byte[input.length];
	cipher.processBytes(input, 0, input.length, output, 0);
	return output;
	} catch (OutputLengthException e) {
	throw new IllegalStateException("In CTR mode output length must be equal to input length", e);
	}
	}

Furthermore we added a JCE-based implementation in 90b8cb6:

siv-mode/src/main/java/org/cryptomator/siv/JceAesCtrComputer.java

Lines 39 to 51 in 90b8cb6

	public byte[] computeCtr(byte[] input, byte[] key, final byte[] iv) {
	try {
	Cipher cipher = threadLocalCipher.get();
	cipher.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(key, "AES"), new IvParameterSpec(iv));
	return cipher.doFinal(input);
	} catch (InvalidKeyException | InvalidAlgorithmParameterException e) {
	throw new IllegalArgumentException("Key or IV invalid.");
	} catch (BadPaddingException e) {
	throw new IllegalStateException("Cipher doesn't require padding.", e);
	} catch (IllegalBlockSizeException e) {
	throw new IllegalStateException("Block size irrelevant for stream ciphers.", e);
	}
	}

The immediate effect is a significant 20% speedup on JDK 8:

Benchmark                               Mode  Cnt   Score    Error  Units
SivModeBenchmark.benchmarkJce (old)     avgt    4  21,904 ± 10,101  us/op

Benchmark                               Mode  Cnt   Score   Error  Units
SivModeBenchmark.benchmarkJce (new)     avgt    4  17,327 ± 1,357  us/op

More importantly, this directly benefits from further optimizations in the JRE. With JDK 14 I get even faster computation times:

Benchmark                               Mode  Cnt   Score    Error  Units
SivModeBenchmark.benchmarkJce           avgt    4  11,586 ±  2,245  us/op

Benchmark results on CI server:
old vs new.

Add documentation on how to build the project

Even with the travis.yml, adding the profile and servers to the maven settings I didn't get to fully run the project through maven (i.e. mvn clean install) - I'd suggest adding a paragraph to your readme explaining what needs to be done to build the project.