From a076e4e30aec16794ed06fd9148e37c5479b8a10 Mon Sep 17 00:00:00 2001
From: Thai Duong <thaidn@google.com>
Date: Mon, 26 Mar 2018 11:16:26 -0700
Subject: [PATCH] Fixing Javadoc errors.
PiperOrigin-RevId: 190494125
GitOrigin-RevId: 4e767c8dbc7927ee7f143d42c5eb7db6dc45ebae
---
README.md | 22 +--
.../crypto/tink/BinaryKeysetReader.java | 13 +-
.../crypto/tink/BinaryKeysetWriter.java | 2 +
.../com/google/crypto/tink/Catalogue.java | 9 +-
.../crypto/tink/CleartextKeysetHandle.java | 9 +-
.../com/google/crypto/tink/HybridDecrypt.java | 12 +-
.../com/google/crypto/tink/HybridEncrypt.java | 12 +-
.../google/crypto/tink/JsonKeysetReader.java | 36 +++--
.../google/crypto/tink/JsonKeysetWriter.java | 13 +-
.../com/google/crypto/tink/KeysetHandle.java | 4 +-
.../com/google/crypto/tink/KeysetManager.java | 4 +-
.../crypto/tink/NoSecretKeysetHandle.java | 2 +-
.../java/com/google/crypto/tink/Registry.java | 6 +-
.../android/AndroidKeysetManager.java | 31 ++--
.../android/AndroidKeystoreAesGcm.java | 6 +-
.../android/AndroidKeystoreKmsClient.java | 2 +-
.../tink/integration/awskms/AwsKmsAead.java | 5 +-
.../tink/integration/awskms/AwsKmsClient.java | 2 +-
.../tink/integration/gcpkms/GcpKmsAead.java | 3 +-
.../tink/integration/gcpkms/GcpKmsClient.java | 5 +-
.../com/google/crypto/tink/mac/MacConfig.java | 2 +-
.../crypto/tink/mac/MacKeyTemplates.java | 57 ++++---
.../tink/signature/SignatureKeyTemplates.java | 94 +++++++-----
.../streamingaead/StreamingAeadConfig.java | 10 +-
.../streamingaead/StreamingAeadFactory.java | 8 +-
.../StreamingAeadKeyTemplates.java | 38 ++---
.../google/crypto/tink/subtle/AesCmac.java | 4 +-
.../tink/subtle/AesCtrHmacStreaming.java | 86 +++++------
.../crypto/tink/subtle/AesCtrJceCipher.java | 7 +-
.../google/crypto/tink/subtle/AesEaxJce.java | 8 +-
.../com/google/crypto/tink/subtle/AesSiv.java | 2 +-
.../com/google/crypto/tink/subtle/Base64.java | 5 +-
.../google/crypto/tink/subtle/ChaCha20.java | 2 +-
.../crypto/tink/subtle/ChaCha20Poly1305.java | 4 +-
.../crypto/tink/subtle/EcdsaSignJce.java | 2 +-
.../crypto/tink/subtle/EcdsaVerifyJce.java | 2 +-
.../google/crypto/tink/subtle/Ed25519.java | 14 +-
.../crypto/tink/subtle/Ed25519Sign.java | 4 +-
.../crypto/tink/subtle/Ed25519Verify.java | 8 +-
.../tink/subtle/EncryptThenAuthenticate.java | 8 +-
.../crypto/tink/subtle/EngineWrapper.java | 7 +-
.../google/crypto/tink/subtle/Field25519.java | 15 +-
.../com/google/crypto/tink/subtle/Hkdf.java | 4 +-
.../crypto/tink/subtle/IndCpaCipher.java | 6 +-
.../com/google/crypto/tink/subtle/MacJce.java | 2 +-
.../tink/subtle/NonceBasedStreamingAead.java | 6 +-
.../google/crypto/tink/subtle/Poly1305.java | 6 +-
.../com/google/crypto/tink/subtle/Random.java | 2 +-
.../subtle/RewindableReadableByteChannel.java | 11 +-
.../crypto/tink/subtle/SnufflePoly1305.java | 4 +-
.../tink/subtle/StreamSegmentDecrypter.java | 9 +-
.../tink/subtle/StreamSegmentEncrypter.java | 20 ++-
.../StreamingAeadDecryptingChannel.java | 4 +-
.../subtle/StreamingAeadDecryptingStream.java | 3 +-
.../StreamingAeadEncryptingChannel.java | 2 +-
.../subtle/StreamingAeadEncryptingStream.java | 2 +-
...treamingAeadSeekableDecryptingChannel.java | 4 +-
.../com/google/crypto/tink/subtle/X25519.java | 3 +-
.../google/crypto/tink/subtle/XSalsa20.java | 140 ------------------
59 files changed, 379 insertions(+), 434 deletions(-)
delete mode 100644 java/src/main/java/com/google/crypto/tink/subtle/XSalsa20.java
diff --git a/README.md b/README.md
index 861bd4b69..5fafacefb 100644
--- a/README.md
+++ b/README.md
@@ -52,12 +52,12 @@ a replacement or successor of [Keyczar](https://github.com/google/keyczar).
**Current Status**
-* [Tink for Java](g3doc/JAVA-HOWTO.md) is field tested and ready for production --
+* [Tink for Java](doc/JAVA-HOWTO.md) is field tested and ready for production --
it is used in several Google products such as AdMob, Android Pay, and Google
Android Search App.
-* [Tink for C++](g3doc/CPP-HOWTO.md) is catching up with
- [Tink for Java](g3doc/JAVA-HOWTO.md) in terms of features and stability,
+* [Tink for C++](doc/CPP-HOWTO.md) is catching up with
+ [Tink for Java](doc/JAVA-HOWTO.md) in terms of features and stability,
and the offered functionality is 100%-compatible with Java
(cf. [cross-language tests](tools/testing/cross_language/).
We plan to make a first C++ release soon.
@@ -70,11 +70,11 @@ a replacement or successor of [Keyczar](https://github.com/google/keyczar).
[Bazel](https://docs.bazel.build/versions/master/install.html), then build, run
and study the [`hello world samples`](https://github.com/google/tink/tree/master/examples/helloworld).
-Tink performs cryptographic tasks via so-called [primitives](g3doc/PRIMITIVES.md),
+Tink performs cryptographic tasks via so-called [primitives](doc/PRIMITIVES.md),
each of which is defined via a corresponding interface that specifies the
functionality of the primitive. For example, _symmetric key encryption_ is
offered via an [_AEAD-primitive_ (Authenticated Encryption with Associated
-Data)](g3doc/PRIMITIVES.md#authenticated-encryption-with-associated-data), that
+Data)](doc/PRIMITIVES.md#authenticated-encryption-with-associated-data), that
supports two operations:
* `encrypt(plaintext, associated_data)`, which encrypts the given `plaintext`
@@ -122,7 +122,7 @@ AEAD primitive in Java:
byte[] ciphertext = aead.encrypt(plaintext, aad);
```
-See the [Java HOWTO](g3doc/JAVA-HOWTO.md#obtaining-and-using-a-primitive) for how
+See the [Java HOWTO](doc/JAVA-HOWTO.md#obtaining-and-using-a-primitive) for how
to obtain and use other primitives.
## Important Warnings
@@ -134,11 +134,11 @@ testing.
## Learn More
-* [Tink Primitives](g3doc/PRIMITIVES.md)
-* [Key Management](g3doc/KEY-MANAGEMENT.md)
-* [Java HOW-TO](g3doc/JAVA-HOWTO.md)
-* [C++ HOW-TO](g3doc/CPP-HOWTO.md)
-* [Tinkey](g3doc/TINKEY.md)
+* [Tink Primitives](doc/PRIMITIVES.md)
+* [Key Management](doc/KEY-MANAGEMENT.md)
+* [Java HOW-TO](doc/JAVA-HOWTO.md)
+* [C++ HOW-TO](doc/CPP-HOWTO.md)
+* [Tinkey](doc/TINKEY.md)
## Contact and mailing list
diff --git a/java/src/main/java/com/google/crypto/tink/BinaryKeysetReader.java b/java/src/main/java/com/google/crypto/tink/BinaryKeysetReader.java
index 749bc8796..c6eb6600e 100644
--- a/java/src/main/java/com/google/crypto/tink/BinaryKeysetReader.java
+++ b/java/src/main/java/com/google/crypto/tink/BinaryKeysetReader.java
@@ -32,20 +32,25 @@ public final class BinaryKeysetReader implements KeysetReader {
private final InputStream inputStream;
/**
- * Note: the input stream won't be read until {@link BinaryKeysetReader#read} or
- * {@link BinaryKeysetReader#readEncrypted} is called.
+ * Static method to create a BinaryKeysetReader from an {@link InputStream}.
+ *
+ * <p>Note: the input stream won't be read until {@link BinaryKeysetReader#read} or {@link
+ * BinaryKeysetReader#readEncrypted} is called.
*/
public static KeysetReader withInputStream(InputStream stream) {
return new BinaryKeysetReader(stream);
}
+ /** Static method to create a BinaryKeysetReader from a byte arrary. */
public static KeysetReader withBytes(final byte[] bytes) {
return new BinaryKeysetReader(new ByteArrayInputStream(bytes));
}
/**
- * Note: the input file won't be read until {@link BinaryKeysetReader#read} or
- * {@link BinaryKeysetReader#readEncrypted} is called.
+ * Static method to create a BinaryKeysetReader from a file.
+ *
+ * <p>Note: the input file won't be read until {@link BinaryKeysetReader#read} or {@link
+ * BinaryKeysetReader#readEncrypted} is called.
*/
public static KeysetReader withFile(File file) throws IOException {
return new BinaryKeysetReader(new FileInputStream(file));
diff --git a/java/src/main/java/com/google/crypto/tink/BinaryKeysetWriter.java b/java/src/main/java/com/google/crypto/tink/BinaryKeysetWriter.java
index 2131dc6ed..13bbaf685 100644
--- a/java/src/main/java/com/google/crypto/tink/BinaryKeysetWriter.java
+++ b/java/src/main/java/com/google/crypto/tink/BinaryKeysetWriter.java
@@ -34,10 +34,12 @@ public final class BinaryKeysetWriter implements KeysetWriter {
outputStream = stream;
}
+ /** Static method to create a BinaryKeysetWriter that writes to an {@link OutputStream}. */
public static KeysetWriter withOutputStream(OutputStream stream) {
return new BinaryKeysetWriter(stream);
}
+ /** Static method to create a BinaryKeysetWriter that writes to a file. */
public static KeysetWriter withFile(File file) throws IOException {
return new BinaryKeysetWriter(new FileOutputStream(file));
}
diff --git a/java/src/main/java/com/google/crypto/tink/Catalogue.java b/java/src/main/java/com/google/crypto/tink/Catalogue.java
index c2fcb38cf..825343a97 100644
--- a/java/src/main/java/com/google/crypto/tink/Catalogue.java
+++ b/java/src/main/java/com/google/crypto/tink/Catalogue.java
@@ -21,15 +21,14 @@ import java.security.GeneralSecurityException;
/**
* A catalogue of {@link KeyManager} objects.
*
- * <p>It is basically a map from a (key type, primitive name)-tuple to {@link
- * com.google.crypto.tink.KeyManager}-objects, that determine the implementation that handles the
- * keys of the given key type.
+ * <p>It is basically a map from a (key type, primitive name)-tuple to {@link KeyManager}-objects,
+ * that determines the implementation that handles the keys of the given key type.
*
* <p>Tink includes default per-primitive catalogues, but it also supports custom catalogues to
* enable user-defined configuration of run-time environment via {@link Registry}.
*
- * <p>The template parameter {@code P} denotes the primitive corresponding to the {@link
- * com.google.crypto.tink.KeyManager} handled by this catalogue.
+ * <p>The template parameter {@code P} denotes the primitive corresponding to the {@link KeyManager}
+ * handled by this catalogue.
*/
public interface Catalogue<P> {
/**
diff --git a/java/src/main/java/com/google/crypto/tink/CleartextKeysetHandle.java b/java/src/main/java/com/google/crypto/tink/CleartextKeysetHandle.java
index a1453c561..77a6d8df5 100644
--- a/java/src/main/java/com/google/crypto/tink/CleartextKeysetHandle.java
+++ b/java/src/main/java/com/google/crypto/tink/CleartextKeysetHandle.java
@@ -27,14 +27,13 @@ import java.security.GeneralSecurityException;
* <p><b>Warning</b>
*
* <p>Reading or writing cleartext keysets is a bad practice, usage of this API should be
- * restricted. Users can read (write) encrypted keysets using {@link KeysetHandle#read} ( {@link
- * KeysetHandle#write}.
+ * restricted. Users can read encrypted keysets using {@link KeysetHandle#read}.
*/
public final class CleartextKeysetHandle {
/**
* @return a new {@link KeysetHandle} from {@code serialized} that is a serialized {@link Keyset}
* @throws GeneralSecurityException
- * @deprecated use {@link CleartextKeysetHandle#read} instead
+ * @deprecated use {@link #read} instead
*/
@Deprecated
public static final KeysetHandle parseFrom(final byte[] serialized)
@@ -48,7 +47,7 @@ public final class CleartextKeysetHandle {
}
/**
- * @return a new {@link KeysetHandle} from a keyset obtained from {@code reader}.
+ * @return a new {@link KeysetHandle} from a {@link Keyset} read with {@code reader}.
* @throws GeneralSecurityException
*/
public static KeysetHandle read(KeysetReader reader)
@@ -57,7 +56,7 @@ public final class CleartextKeysetHandle {
}
/**
- * Serializes and writes the keyset managed by {@code handle} to {@code keysetWriter}.
+ * Serializes and writes the {@link Keyset} managed by {@code handle} to {@code keysetWriter}.
*
* @throws IOException
*/
diff --git a/java/src/main/java/com/google/crypto/tink/HybridDecrypt.java b/java/src/main/java/com/google/crypto/tink/HybridDecrypt.java
index ca63852cf..e9eb86781 100644
--- a/java/src/main/java/com/google/crypto/tink/HybridDecrypt.java
+++ b/java/src/main/java/com/google/crypto/tink/HybridDecrypt.java
@@ -27,11 +27,13 @@ import java.security.GeneralSecurityException;
* symmetric key only, and the final ciphertext consists of the symmetric ciphertext and the
* encrypted symmetric key.
*
- * <p><b>WARNING</b>: Hybrid Encryption does not provide authenticity, that is the recipient of an
- * encrypted message does not know the identity of the sender. Similar to general public-key
- * encryption schemes the security goal of Hybrid Encryption is to provide privacy only. In other
- * words, Hybrid Encryption is secure if and only if the recipient can accept anonymous messages or
- * can rely on other mechanisms to authenticate the sender.
+ * <p><b>WARNING</b>
+ *
+ * <p>Hybrid Encryption does not provide authenticity, that is the recipient of an encrypted message
+ * does not know the identity of the sender. Similar to general public-key encryption schemes the
+ * security goal of Hybrid Encryption is to provide privacy only. In other words, Hybrid Encryption
+ * is secure if and only if the recipient can accept anonymous messages or can rely on other
+ * mechanisms to authenticate the sender.
*
* <p>The functionality of Hybrid Encryption is represented as a pair of primitives (interfaces):
* {@link HybridEncrypt} for encryption of data, and {@link HybridDecrypt} for decryption.
diff --git a/java/src/main/java/com/google/crypto/tink/HybridEncrypt.java b/java/src/main/java/com/google/crypto/tink/HybridEncrypt.java
index 7098376ab..49fd2d3f3 100644
--- a/java/src/main/java/com/google/crypto/tink/HybridEncrypt.java
+++ b/java/src/main/java/com/google/crypto/tink/HybridEncrypt.java
@@ -27,11 +27,13 @@ import java.security.GeneralSecurityException;
* symmetric key only, and the final ciphertext consists of the symmetric ciphertext and the
* encrypted symmetric key.
*
- * <p><b>WARNING</b>: Hybrid Encryption does not provide authenticity, that is the recipient of an
- * encrypted message does not know the identity of the sender. Similar to general public-key
- * encryption schemes the security goal of Hybrid Encryption is to provide privacy only. In other
- * words, Hybrid Encryption is secure if and only if the recipient can accept anonymous messages or
- * can rely on other mechanisms to authenticate the sender.
+ * <p><b>WARNING</b>
+ *
+ * <p>Hybrid Encryption does not provide authenticity, that is the recipient of an encrypted message
+ * does not know the identity of the sender. Similar to general public-key encryption schemes the
+ * security goal of Hybrid Encryption is to provide privacy only. In other words, Hybrid Encryption
+ * is secure if and only if the recipient can accept anonymous messages or can rely on other
+ * mechanisms to authenticate the sender.
*
* <p>The functionality of Hybrid Encryption is represented as a pair of primitives (interfaces):
* {@link HybridEncrypt} for encryption of data, and {@link HybridDecrypt} for decryption.
diff --git a/java/src/main/java/com/google/crypto/tink/JsonKeysetReader.java b/java/src/main/java/com/google/crypto/tink/JsonKeysetReader.java
index dffff6e98..1cdfccb98 100644
--- a/java/src/main/java/com/google/crypto/tink/JsonKeysetReader.java
+++ b/java/src/main/java/com/google/crypto/tink/JsonKeysetReader.java
@@ -39,8 +39,9 @@ import org.json.JSONException;
import org.json.JSONObject;
/**
- * A {@link KeysetReader} that can read from source source cleartext or encrypted keysets in proto
- * JSON format.
+ * A {@link KeysetReader} that can read from source source cleartext or encrypted keysets in <a
+ * href="https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/util/JsonFormat">proto
+ * JSON format</a>.
*/
public final class JsonKeysetReader implements KeysetReader {
private static final Charset UTF_8 = Charset.forName("UTF-8");
@@ -60,44 +61,59 @@ public final class JsonKeysetReader implements KeysetReader {
}
/**
- * Note: the input stream won't be read until {@link JsonKeysetReader#read} or
- * {@link JsonKeysetReader#readEncrypted} is called.
+ * Static method to create a JsonKeysetReader from an {@link InputStream}.
+ *
+ * <p>Note: the input stream won't be read until {@link JsonKeysetReader#read} or {@link
+ * JsonKeysetReader#readEncrypted} is called.
*/
public static KeysetReader withInputStream(InputStream input) throws IOException {
return new JsonKeysetReader(input);
}
+ /** Static method to create a JsonKeysetReader from an {@link JSONObject}. */
public static JsonKeysetReader withJsonObject(JSONObject input) {
return new JsonKeysetReader(input);
}
+ /** Static method to create a JsonKeysetReader from a string. */
public static JsonKeysetReader withString(String input) {
return new JsonKeysetReader(new ByteArrayInputStream(input.getBytes(UTF_8)));
}
+ /** Static method to create a JsonKeysetReader from a byte array. */
public static JsonKeysetReader withBytes(final byte[] bytes) {
return new JsonKeysetReader(new ByteArrayInputStream(bytes));
}
/**
- * Note: the file won't be read until {@link JsonKeysetReader#read} or
- * {@link JsonKeysetReader#readEncrypted} is called.
+ * Static method to create a JsonKeysetReader from a file.
+ *
+ * <p>Note: the file won't be read until {@link JsonKeysetReader#read} or {@link
+ * JsonKeysetReader#readEncrypted} is called.
*/
public static JsonKeysetReader withFile(File file) throws IOException {
return new JsonKeysetReader(new FileInputStream(file));
}
/**
- * Note: the file path won't be read until {@link JsonKeysetReader#read} or
- * {@link JsonKeysetReader#readEncrypted} is called.
+ * Static method to create a JsonKeysetReader from a {@link Path}.
+ *
+ * <p>Note: the file path won't be read until {@link JsonKeysetReader#read} or {@link
+ * JsonKeysetReader#readEncrypted} is called.
+ *
+ * <p>This method only works on Android API level 26 or newer.
*/
public static JsonKeysetReader withPath(String path) throws IOException {
return withFile(new File(path));
}
/**
- * Note: the file path won't be read until {@link JsonKeysetReader#read} or
- * {@link JsonKeysetReader#readEncrypted} is called.
+ * Static method to create a JsonKeysetReader from a {@link Path}.
+ *
+ * <p>Note: the file path won't be read until {@link JsonKeysetReader#read} or {@link
+ * JsonKeysetReader#readEncrypted} is called.
+ *
+ * <p>This method only works on Android API level 26 or newer.
*/
public static JsonKeysetReader withPath(Path path) throws IOException {
return withFile(path.toFile());
diff --git a/java/src/main/java/com/google/crypto/tink/JsonKeysetWriter.java b/java/src/main/java/com/google/crypto/tink/JsonKeysetWriter.java
index 78fce9ef2..835abcc77 100644
--- a/java/src/main/java/com/google/crypto/tink/JsonKeysetWriter.java
+++ b/java/src/main/java/com/google/crypto/tink/JsonKeysetWriter.java
@@ -34,8 +34,9 @@ import org.json.JSONException;
import org.json.JSONObject;
/**
- * A {@link KeysetWriter} that can write to some source cleartext or encrypted keysets in proto JSON
- * format.
+ * A {@link KeysetWriter} that can write to some source cleartext or encrypted keysets in <a
+ * href="https://developers.google.com/protocol-buffers/docs/reference/java/com/google/protobuf/util/JsonFormat">proto
+ * JSON format</a>.
*/
public final class JsonKeysetWriter implements KeysetWriter {
private static final Charset UTF_8 = Charset.forName("UTF-8");
@@ -46,18 +47,26 @@ public final class JsonKeysetWriter implements KeysetWriter {
outputStream = stream;
}
+ /** Static method to create a JsonKeysetWriter that writes to an {@link OutputStream}. */
public static KeysetWriter withOutputStream(OutputStream stream) {
return new JsonKeysetWriter(stream);
}
+ /** Static method to create a JsonKeysetWriter that writes to a file. */
public static KeysetWriter withFile(File file) throws IOException {
return new JsonKeysetWriter(new FileOutputStream(file));
}
+ /** Static method to create a JsonKeysetWriter that writes to a file path. */
public static KeysetWriter withPath(String path) throws IOException {
return withFile(new File(path));
}
+ /**
+ * Static method to create a JsonKeysetWriter that writes to a file path.
+ *
+ * <p>This method only works on Android API level 26 or newer.
+ */
public static KeysetWriter withPath(Path path) throws IOException {
return withFile(path.toFile());
}
diff --git a/java/src/main/java/com/google/crypto/tink/KeysetHandle.java b/java/src/main/java/com/google/crypto/tink/KeysetHandle.java
index 3e0e4868f..5e8e9f201 100644
--- a/java/src/main/java/com/google/crypto/tink/KeysetHandle.java
+++ b/java/src/main/java/com/google/crypto/tink/KeysetHandle.java
@@ -27,8 +27,8 @@ import java.io.IOException;
import java.security.GeneralSecurityException;
/**
- * A KeysetHandle provides abstracted access to {@link com.google.crypto.tink.proto.Keyset}, to
- * limit the exposure of actual protocol buffers that hold sensitive key material.
+ * A KeysetHandle provides abstracted access to {@link Keyset}, to limit the exposure of actual
+ * protocol buffers that hold sensitive key material.
*
* <p>This class allows reading and writing encrypted keysets. Users that want to read or write can
* use the restricted API {@link CleartextKeysetHandle}. Users can also load keysets that don't
diff --git a/java/src/main/java/com/google/crypto/tink/KeysetManager.java b/java/src/main/java/com/google/crypto/tink/KeysetManager.java
index f7662b242..69ca7a4d4 100644
--- a/java/src/main/java/com/google/crypto/tink/KeysetManager.java
+++ b/java/src/main/java/com/google/crypto/tink/KeysetManager.java
@@ -26,8 +26,8 @@ import java.security.SecureRandom;
import javax.annotation.concurrent.GuardedBy;
/**
- * Manages a {@link com.google.crypto.tink.proto.Keyset} proto, with convenience methods that
- * rotate, disable, enable or destroy keys.
+ * Manages a {@link Keyset} proto, with convenience methods that rotate, disable, enable or destroy
+ * keys.
*/
public final class KeysetManager {
@GuardedBy("this")
diff --git a/java/src/main/java/com/google/crypto/tink/NoSecretKeysetHandle.java b/java/src/main/java/com/google/crypto/tink/NoSecretKeysetHandle.java
index 33e2b8baf..764f4f735 100644
--- a/java/src/main/java/com/google/crypto/tink/NoSecretKeysetHandle.java
+++ b/java/src/main/java/com/google/crypto/tink/NoSecretKeysetHandle.java
@@ -25,7 +25,7 @@ import java.security.GeneralSecurityException;
/** Static methods for reading cleartext keysets that don't contain any secret key material. */
public final class NoSecretKeysetHandle {
/**
- * @return a new keyset handle from {@code serialized} which is a serialized {@code Keyset}.
+ * @return a new keyset handle from {@code serialized} which is a serialized {@link Keyset}.
* @throws GeneralSecurityException
* @deprecated use {@link NoSecretKeysetHandle#read} instead
*/
diff --git a/java/src/main/java/com/google/crypto/tink/Registry.java b/java/src/main/java/com/google/crypto/tink/Registry.java
index f8639d86a..48732d752 100644
--- a/java/src/main/java/com/google/crypto/tink/Registry.java
+++ b/java/src/main/java/com/google/crypto/tink/Registry.java
@@ -43,7 +43,7 @@ import java.util.logging.Logger;
* for specific KeyManagers. Registry is public though, to enable configurations with custom
* catalogues, primitives or KeyManagers.
*
- * <p>To initialize the Registery with all key managers in Tink 1.0.0, one can do as follows:
+ * <p>To initialize the Registry with all key managers in Tink 1.0.0, one can do as follows:
*
* <pre>{@code
* Config.register(TinkConfig.TINK_1_0_0);
@@ -228,7 +228,7 @@ public final class Registry {
}
/**
- * Convenience method for generating a new {@code KeyData} for the specified {@code template}.
+ * Convenience method for generating a new {@link KeyData} for the specified {@code template}.
*
* <p>It looks up a {@link KeyManager} identified by {@code keyTemplate.type_url}, and calls
* {@link KeyManager#newKeyData}.
@@ -288,7 +288,7 @@ public final class Registry {
* serializedPrivateKey}.
*
* <p>It looks up a {@link PrivateKeyManager} identified by {@code typeUrl}, and calls {@link
- * KeyManager#getPublicKeyData} with {@code serializedPrivateKey} as the parameter.
+ * PrivateKeyManager#getPublicKeyData} with {@code serializedPrivateKey} as the parameter.
*
* @return a new key
*/
diff --git a/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeysetManager.java b/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeysetManager.java
index 254745209..7c0cd7329 100644
--- a/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeysetManager.java
+++ b/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeysetManager.java
@@ -32,16 +32,17 @@ import java.security.GeneralSecurityException;
import javax.annotation.concurrent.GuardedBy;
/**
- * A wrapper of {@link KeysetManager} that supports reading/writing
- * {@link com.google.crypto.tink.proto.Keyset} to/from private shared preferences on Android.
+ * A wrapper of {@link KeysetManager} that supports reading/writing {@link
+ * com.google.crypto.tink.proto.Keyset} to/from private shared preferences on Android.
*
- * <p><b>Warning</b>:
- * This class reads and writes to shared preferences, thus is best not to run on the UI thread.
+ * <p><b>Warning</b>: This class reads and writes to shared preferences, thus is best not to run on
+ * the UI thread.
*
- * <p>On Android M or newer, the keysets are encrypted with master keys generated and stored in
- * <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore</a>.
+ * <p>On Android M or newer, the keysets are encrypted with master keys generated and stored in <a
+ * href="https://developer.android.com/training/articles/keystore.html">Android Keystore</a>.
*
* <p>Sample usage:
+ *
* <pre>{@code
* String masterKeyUri = "android-keystore://my_master_key_id";
* AndroidKeysetManager manager = AndroidKeysetManager.Builder()
@@ -52,23 +53,23 @@ import javax.annotation.concurrent.GuardedBy;
* PublicKeySign signer = PublicKeySignFactory.getPrimitive(manager.getKeysetHandle());
* }</pre>
*
- * <p>This will read a keyset stored in the
- * {@code my_keyset_name} preference of the {@code my_pref_file_name} shared preferences file. If
- * the preference file name is null, it uses the default shared preferences file.
+ * <p>This will read a keyset stored in the {@code my_keyset_name} preference of the {@code
+ * my_pref_file_name} shared preferences file. If the preference file name is null, it uses the
+ * default shared preferences file.
*
- * <p>If the keyset is not found or invalid, and a valid {@link KeyTemplate} is set with
- * {@link AndroidKeysetManager.Builder#withKeyTemplate}, a fresh keyset is generated and is
- * written to the {@code my_keyset_name} preference of the {@code my_pref_file_name} shared
- * preferences file.
+ * <p>If the keyset is not found or invalid, and a valid {@link KeyTemplate} is set with {@link
+ * AndroidKeysetManager.Builder#withKeyTemplate}, a fresh keyset is generated and is written to the
+ * {@code my_keyset_name} preference of the {@code my_pref_file_name} shared preferences file.
*
* <p>If a master key URI is set with {@link AndroidKeysetManager.Builder#withKeyTemplate}, the
* keyset will be encrypted when written to storage and decrypted when read. The master key URI must
* start with {@code android-keystore://}. If the master key doesn't exist, a fresh one is
- * generated. Usage of Android Keystore can be disabled with
- * {@link AndroidKeysetManager.Builder#doNotUseKeyStore}.
+ * generated. Usage of Android Keystore can be disabled with {@link
+ * AndroidKeysetManager.Builder#doNotUseKeystore}.
*
* <p>The resulting manager supports all operations that supported by {@link KeysetManager}. For
* example to rotate the keyset, one can do:
+ *
* <pre>{@code
* manager.rotate(SignatureKeyTemplates.ECDSA_P256);
* }</pre>
diff --git a/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeystoreAesGcm.java b/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeystoreAesGcm.java
index 341a6e32e..c42d2b166 100644
--- a/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeystoreAesGcm.java
+++ b/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeystoreAesGcm.java
@@ -27,10 +27,10 @@ import javax.crypto.SecretKey;
import javax.crypto.spec.GCMParameterSpec;
/**
- * An {@link Aead} that does AES-GCM encryption with a key stored in
- * <a href="https://developer.android.com/training/articles/keystore.html">Android Keystore</a>.
+ * An {@link Aead} that does AES-GCM encryption with a key stored in <a
+ * href="https://developer.android.com/training/articles/keystore.html">Android Keystore</a>.
*
- * <p>This class requires Android M or newer.
+ * <p>This class requires Android M (API level 23) or newer.
*/
@TargetApi(VERSION_CODES.M)
public final class AndroidKeystoreAesGcm implements Aead {
diff --git a/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeystoreKmsClient.java b/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeystoreKmsClient.java
index 756fa0d50..9639000b8 100644
--- a/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeystoreKmsClient.java
+++ b/java/src/main/java/com/google/crypto/tink/integration/android/AndroidKeystoreKmsClient.java
@@ -33,7 +33,7 @@ import javax.crypto.KeyGenerator;
* An implementation of {@link KmsClient} for <a
* href="https://developer.android.com/training/articles/keystore.html">Android Keystore</a>.
*
- * <p>This class requires Android M or newer.
+ * <p>This class requires Android M (API level 23) or newer.
*/
@TargetApi(VERSION_CODES.M)
public final class AndroidKeystoreKmsClient implements KmsClient {
diff --git a/java/src/main/java/com/google/crypto/tink/integration/awskms/AwsKmsAead.java b/java/src/main/java/com/google/crypto/tink/integration/awskms/AwsKmsAead.java
index a5929ef0f..19d6ca5e6 100644
--- a/java/src/main/java/com/google/crypto/tink/integration/awskms/AwsKmsAead.java
+++ b/java/src/main/java/com/google/crypto/tink/integration/awskms/AwsKmsAead.java
@@ -26,7 +26,10 @@ import com.google.crypto.tink.Aead;
import java.nio.ByteBuffer;
import java.security.GeneralSecurityException;
-/** A {@link Aead} that forwards encryption/decryption requests to a key in AWS KMS. */
+/**
+ * A {@link Aead} that forwards encryption/decryption requests to a key in <a
+ * href="https://aws.amazon.com/kms/">AWS KMS</a>.
+ */
public final class AwsKmsAead implements Aead {
/** This client knows how to talk to AWS KMS. */
diff --git a/java/src/main/java/com/google/crypto/tink/integration/awskms/AwsKmsClient.java b/java/src/main/java/com/google/crypto/tink/integration/awskms/AwsKmsClient.java
index 708feec2d..52697566b 100644
--- a/java/src/main/java/com/google/crypto/tink/integration/awskms/AwsKmsClient.java
+++ b/java/src/main/java/com/google/crypto/tink/integration/awskms/AwsKmsClient.java
@@ -28,7 +28,7 @@ import com.google.crypto.tink.KmsClient;
import com.google.crypto.tink.subtle.Validators;
import java.security.GeneralSecurityException;
-/** An implementation of {@code KmsClient} for AWS KMS. */
+/** An implementation of {@link KmsClient} for <a href="https://aws.amazon.com/kms/">AWS KMS</a>. */
@AutoService(KmsClient.class)
public final class AwsKmsClient implements KmsClient {
/** The prefix of all keys stored in AWS KMS. */
diff --git a/java/src/main/java/com/google/crypto/tink/integration/gcpkms/GcpKmsAead.java b/java/src/main/java/com/google/crypto/tink/integration/gcpkms/GcpKmsAead.java
index 695274278..421b03a9a 100644
--- a/java/src/main/java/com/google/crypto/tink/integration/gcpkms/GcpKmsAead.java
+++ b/java/src/main/java/com/google/crypto/tink/integration/gcpkms/GcpKmsAead.java
@@ -26,7 +26,8 @@ import java.io.IOException;
import java.security.GeneralSecurityException;
/**
- * A {@link Aead} that forwards encryption/decryption requests to a key in Google Cloud KMS.
+ * A {@link Aead} that forwards encryption/decryption requests to a key in <a
+ * href="https://cloud.google.com/kms/">Google Cloud KMS</a>.
*
* <p>As of August 2017, Google Cloud KMS supports only AES-256-GCM keys.
*/
diff --git a/java/src/main/java/com/google/crypto/tink/integration/gcpkms/GcpKmsClient.java b/java/src/main/java/com/google/crypto/tink/integration/gcpkms/GcpKmsClient.java
index a07a2e353..d993ab072 100644
--- a/java/src/main/java/com/google/crypto/tink/integration/gcpkms/GcpKmsClient.java
+++ b/java/src/main/java/com/google/crypto/tink/integration/gcpkms/GcpKmsClient.java
@@ -30,7 +30,10 @@ import java.io.FileInputStream;
import java.io.IOException;
import java.security.GeneralSecurityException;
-/** An implementation of {@code KmsClient} for Google Cloud KMS. */
+/**
+ * An implementation of {@code KmsClient} for <a href="https://cloud.google.com/kms/">Google Cloud
+ * KMS</a>.
+ */
@AutoService(KmsClient.class)
public final class GcpKmsClient implements KmsClient {
/** The prefix of all keys stored in Google Cloud KMS. */
diff --git a/java/src/main/java/com/google/crypto/tink/mac/MacConfig.java b/java/src/main/java/com/google/crypto/tink/mac/MacConfig.java
index 026a58de9..7caaf0eae 100644
--- a/java/src/main/java/com/google/crypto/tink/mac/MacConfig.java
+++ b/java/src/main/java/com/google/crypto/tink/mac/MacConfig.java
@@ -73,7 +73,7 @@ public final class MacConfig {
* <p>Deprecated-yet-still-supported key types are registered in so-called "no new key"-mode,
* which allows for usage of existing keys forbids generation of new key material.
*
- * @deprecated
+ * @deprecated use {@link Config#register}
*/
@Deprecated
public static void registerStandardKeyTypes() throws GeneralSecurityException {
diff --git a/java/src/main/java/com/google/crypto/tink/mac/MacKeyTemplates.java b/java/src/main/java/com/google/crypto/tink/mac/MacKeyTemplates.java
index 3ea2d7bf1..e9241da82 100644
--- a/java/src/main/java/com/google/crypto/tink/mac/MacKeyTemplates.java
+++ b/java/src/main/java/com/google/crypto/tink/mac/MacKeyTemplates.java
@@ -23,39 +23,48 @@ import com.google.crypto.tink.proto.KeyTemplate;
import com.google.crypto.tink.proto.OutputPrefixType;
/**
- * Pre-generated {@code KeyTemplate} for {@code Mac}. One can use these templates
- * to generate new {@code Keyset} with {@code KeysetHandle}. To generate a new keyset
- * that contains a single {@code HmacKey}, one can do:
- * <pre>
- * Config.register(Mac.TINK_1_0_0);
- * KeysetHandle handle = KeysetHandle.generateNew(MacKeyTemplates.HMAC_SHA256_128BITTAG);
- * Mac mac = MacFactory.getPrimitive(handle);
- * </pre>
+ * Pre-generated {@link KeyTemplate} for {@link com.google.crypto.tink.Mac}.
+ *
+ * <p>One can use these templates to generate new {@link com.google.crypto.tink.proto.Keyset} with
+ * {@link com.google.crypto.tink.KeysetHandle}. To generate a new keyset that contains a single
+ * {@link com.google.crypto.tink.proto.HmacKey}, one can do:
+ *
+ * <pre>{@code
+ * Config.register(Mac.TINK_1_0_0);
+ * KeysetHandle handle = KeysetHandle.generateNew(MacKeyTemplates.HMAC_SHA256_128BITTAG);
+ * Mac mac = MacFactory.getPrimitive(handle);
+ * }</pre>
*/
public final class MacKeyTemplates {
/**
- * A {@code KeyTemplate} that generates new instances of {@code HmacKey} with the following
- * parameters:
- * - Key size: 32 bytes
- * - Tag size: 16 bytes
- * - Hash function: SHA256
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.HmacKey} with the following parameters:
+ *
+ * <ul>
+ * <li>Key size: 32 bytes
+ * <li>Tag size: 16 bytes
+ * <li>Hash function: SHA256
+ * </ul>
*/
- public static final KeyTemplate HMAC_SHA256_128BITTAG = createHmacKeyTemplate(
- 32, 16, HashType.SHA256);
+ public static final KeyTemplate HMAC_SHA256_128BITTAG =
+ createHmacKeyTemplate(32, 16, HashType.SHA256);
/**
- * A {@code KeyTemplate} that generates new instances of {@code HmacKey} with the following
- * parameters:
- * - Key size: 32 bytes
- * - Tag size: 32 bytes
- * - Hash function: SHA256
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.HmacKey} with the following parameters:
+ *
+ * <ul>
+ * <li>Key size: 32 bytes
+ * <li>Tag size: 32 bytes
+ * <li>Hash function: SHA256
+ * </ul>
*/
- public static final KeyTemplate HMAC_SHA256_256BITTAG = createHmacKeyTemplate(
- 32, 32, HashType.SHA256);
+ public static final KeyTemplate HMAC_SHA256_256BITTAG =
+ createHmacKeyTemplate(32, 32, HashType.SHA256);
/**
- * @return a {@code KeyTemplate} containing a {@code HmacKeyFormat} with some specified
- * parameters.
+ * @return a {@link KeyTemplate} containing a {@link HmacKeyFormat} with some specified
+ * parameters.
*/
public static KeyTemplate createHmacKeyTemplate(int keySize, int tagSize, HashType hashType) {
HmacParams params = HmacParams.newBuilder()
diff --git a/java/src/main/java/com/google/crypto/tink/signature/SignatureKeyTemplates.java b/java/src/main/java/com/google/crypto/tink/signature/SignatureKeyTemplates.java
index 72ee05d08..8fd38b098 100644
--- a/java/src/main/java/com/google/crypto/tink/signature/SignatureKeyTemplates.java
+++ b/java/src/main/java/com/google/crypto/tink/signature/SignatureKeyTemplates.java
@@ -26,61 +26,79 @@ import com.google.crypto.tink.proto.KeyTemplate;
import com.google.crypto.tink.proto.OutputPrefixType;
/**
- * Pre-generated {@code KeyTemplate} for {@code PublicKeySign} and {@code PublicKeyVerify}.
- * One can use these templates to generate new {@code Keyset} with {@code KeysetHandle}.
- * To generate a new keyset that contains a single {@code EcdsaPrivateKey}, one can do:
- * <pre>
- * Config.register(SignatureConfig.TINK_1_0_0);
- * KeysetHandle handle = KeysetHandle.generateNew(SignatureKeyTemplates.ECDSA_P256);
- * PublicKeySign signer = PublicKeySignFactory.getPrimitive(handle);
- * </pre>
+ * Pre-generated {@link KeyTemplate} for {@link com.google.crypto.tink.PublicKeySign} and {@link
+ * com.google.crypto.tink.PublicKeyVerify}.
+ *
+ * <p>One can use these templates to generate new {@link com.google.crypto.tink.proto.Keyset} with
+ * {@link com.google.crypto.tink.KeysetHandle}. To generate a new keyset that contains a single
+ * {@code EcdsaPrivateKey}, one can do:
+ *
+ * <pre>{@code
+ * Config.register(SignatureConfig.TINK_1_0_0);
+ * KeysetHandle handle = KeysetHandle.generateNew(SignatureKeyTemplates.ECDSA_P256);
+ * PublicKeySign signer = PublicKeySignFactory.getPrimitive(handle);
+ * }</pre>
*/
public final class SignatureKeyTemplates {
/**
- * A {@code KeyTemplate} that generates new instances of {@code EcdsaPrivateKey} with the
- * following parameters:
- * - Hash function: SHA256
- * - Curve: NIST P-256
- * - Signature encoding: DER
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.EcdsaPrivateKey} with the following parameters:
+ *
+ * <ul>
+ * <li>Hash function: SHA256
+ * <li>Curve: NIST P-256
+ * <li>Signature encoding: DER (this is the encoding that Java uses).
+ * </ul>
*/
- public static final KeyTemplate ECDSA_P256 = createEcdsaKeyTemplate(
- HashType.SHA256, EllipticCurveType.NIST_P256, EcdsaSignatureEncoding.DER);
+ public static final KeyTemplate ECDSA_P256 =
+ createEcdsaKeyTemplate(
+ HashType.SHA256, EllipticCurveType.NIST_P256, EcdsaSignatureEncoding.DER);
/**
- * A {@code KeyTemplate} that generates new instances of {@code EcdsaPrivateKey} with the
- * following parameters:
- * - Hash function: SHA512
- * - Curve: NIST P-384
- * - Signature encoding: DER
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.EcdsaPrivateKey} with the following parameters:
+ *
+ * <ul>
+ * <li>Hash function: SHA512
+ * <li>Curve: NIST P-384
+ * <li>Signature encoding: DER (this is the encoding that Java uses).
+ * </ul>
*/
- public static final KeyTemplate ECDSA_P384 = createEcdsaKeyTemplate(
- HashType.SHA512, EllipticCurveType.NIST_P384, EcdsaSignatureEncoding.DER);
+ public static final KeyTemplate ECDSA_P384 =
+ createEcdsaKeyTemplate(
+ HashType.SHA512, EllipticCurveType.NIST_P384, EcdsaSignatureEncoding.DER);
/**
- * A {@code KeyTemplate} that generates new instances of {@code EcdsaPrivateKey} with the
- * following parameters:
- * - Hash function: SHA512
- * - Curve: NIST P-521
- * - Signature encoding: DER
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.EcdsaPrivateKey} with the following parameters:
+ *
+ * <ul>
+ * <li>Hash function: SHA512
+ * <li>Curve: NIST P-384
+ * <li>Signature encoding: DER (this is the encoding that Java uses).
+ * </ul>
*/
- public static final KeyTemplate ECDSA_P521 = createEcdsaKeyTemplate(
- HashType.SHA512, EllipticCurveType.NIST_P521, EcdsaSignatureEncoding.DER);
+ public static final KeyTemplate ECDSA_P521 =
+ createEcdsaKeyTemplate(
+ HashType.SHA512, EllipticCurveType.NIST_P521, EcdsaSignatureEncoding.DER);
/**
- * A {@code KeyTemplate} that generates new instances of {@code Ed25519PrivateKey}.
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.Ed25519PrivateKey}.
*/
@Alpha
- public static final KeyTemplate ED25519 = KeyTemplate.newBuilder()
- .setTypeUrl(Ed25519PrivateKeyManager.TYPE_URL)
- .setOutputPrefixType(OutputPrefixType.TINK)
- .build();
+ public static final KeyTemplate ED25519 =
+ KeyTemplate.newBuilder()
+ .setTypeUrl(Ed25519PrivateKeyManager.TYPE_URL)
+ .setOutputPrefixType(OutputPrefixType.TINK)
+ .build();
/**
- * @return a {@code KeyTemplate} containing a {@code HmacKeyFormat} with some specified
- * parameters.
+ * @return a {@link KeyTemplate} containing a {@link HmacKeyFormat} with some specified
+ * parameters.
*/
- public static KeyTemplate createEcdsaKeyTemplate(HashType hashType, EllipticCurveType curve,
- EcdsaSignatureEncoding encoding) {
+ public static KeyTemplate createEcdsaKeyTemplate(
+ HashType hashType, EllipticCurveType curve, EcdsaSignatureEncoding encoding) {
EcdsaParams params = EcdsaParams.newBuilder()
.setHashType(hashType)
.setCurve(curve)
diff --git a/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadConfig.java b/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadConfig.java
index 92b7659e4..4e7d734d6 100644
--- a/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadConfig.java
+++ b/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadConfig.java
@@ -22,17 +22,17 @@ import com.google.crypto.tink.proto.RegistryConfig;
import java.security.GeneralSecurityException;
/**
- * Static methods and constants for registering with the {@link Registry} all instances
- * of {@link com.google.crypto.tink.StreamingAead} key types supported in a particular
- * release of Tink.
+ * Static methods and constants for registering with the {@link Registry} all instances of {@link
+ * com.google.crypto.tink.StreamingAead} key types supported in a particular release of Tink.
*
* <p>To register all StreamingAead key types provided in Tink release 1.1.0 one can do:
+ *
* <pre>{@code
* Config.register(StreamingAeadConfig.TINK_1_1_0);
* }</pre>
*
- * <p>For more information on how to obtain and use instances of StreamingAead,
- * see {@link StreamingAeadFactory}.
+ * <p>For more information on how to obtain and use instances of StreamingAead, see {@link
+ * StreamingAeadFactory}.
*/
public final class StreamingAeadConfig {
public static final String AES_CTR_HMAC_STREAMINGAEAD_TYPE_URL =
diff --git a/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadFactory.java b/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadFactory.java
index f05afcabe..4e473b240 100644
--- a/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadFactory.java
+++ b/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadFactory.java
@@ -28,6 +28,7 @@ import java.util.logging.Logger;
* Static methods for obtaining {@link StreamingAead} instances.
*
* <p>Usage:
+ *
* <pre>{@code
* KeysetHandle keysetHandle = ...;
* StreamingAead streamingAead = StreamingAeadFactory.getPrimitive(keysetHandle);
@@ -43,10 +44,9 @@ import java.util.logging.Logger;
* encryptingChannel.close();
* }</pre>
*
- * <p>The returned primitive works with a keyset (rather than a single key).
- * To encrypt a plaintext, it uses the primary key in the keyset.
- * To decrypt, the primitive tries the enabled keys from the keyset to select
- * the right key for decryption. All keys in a keyset of StreamingAead have type
+ * <p>The returned primitive works with a keyset (rather than a single key). To encrypt a plaintext,
+ * it uses the primary key in the keyset. To decrypt, the primitive tries the enabled keys from the
+ * keyset to select the right key for decryption. All keys in a keyset of StreamingAead have type
* {@link com.google.crypto.tink.proto.OutputPrefixType#RAW}.
*/
public final class StreamingAeadFactory {
diff --git a/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadKeyTemplates.java b/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadKeyTemplates.java
index a6cf6cf33..88fe63c50 100644
--- a/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadKeyTemplates.java
+++ b/java/src/main/java/com/google/crypto/tink/streamingaead/StreamingAeadKeyTemplates.java
@@ -32,16 +32,16 @@ import com.google.crypto.tink.proto.OutputPrefixType;
* {@code KeysetHandle}. To generate a new keyset that contains a {@link AesGcmHkdfStreamingKey},
* one can do:
*
- * <pre>
- * Config.register(StreamingAeadConfig.TINK_1_0_0);
- * KeysetHandle handle = KeysetHandle.generateNew(StreamingAeadKeyTemplates.AES128_GCM_HKDF_4KB);
- * StreamingAead ags = StreamingAeadFactory.getPrimitive(handle);
- * </pre>
+ * <pre>{@code
+ * Config.register(StreamingAeadConfig.TINK_1_0_0);
+ * KeysetHandle handle = KeysetHandle.generateNew(StreamingAeadKeyTemplates.AES128_GCM_HKDF_4KB);
+ * StreamingAead ags = StreamingAeadFactory.getPrimitive(handle);
+ * }</pre>
*/
public final class StreamingAeadKeyTemplates {
/**
- * A {@code KeyTemplate} that generates new instances of {@code AesCtrHmacStreamingKey} with the
- * following parameters:
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.AesCtrHmacStreamingKey} with the following parameters:
*
* <ul>
* <li>Size of the main key: 16 bytes
@@ -56,8 +56,8 @@ public final class StreamingAeadKeyTemplates {
createAesCtrHmacStreamingKeyTemplate(16, HashType.SHA256, 16, HashType.SHA256, 32, 4096);
/**
- * A {@code KeyTemplate} that generates new instances of {@code AesCtrHmacStreamingKey} with the
- * following parameters:
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.AesCtrHmacStreamingKey} with the following parameters:
*
* <ul>
* <li>Size of the main key: 32 bytes
@@ -72,8 +72,8 @@ public final class StreamingAeadKeyTemplates {
createAesCtrHmacStreamingKeyTemplate(32, HashType.SHA256, 32, HashType.SHA256, 32, 4096);
/**
- * A {@code KeyTemplate} that generates new instances of {@code AesGcmHkdfStreamingKey} with the
- * following parameters:
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.AesGcmHkdfStreamingKey} with the following parameters:
*
* <ul>
* <li>Size of the main key: 16 bytes
@@ -86,8 +86,8 @@ public final class StreamingAeadKeyTemplates {
createAesGcmHkdfStreamingKeyTemplate(16, HashType.SHA256, 16, 4096);
/**
- * A {@code KeyTemplate} that generates new instances of {@code AesGcmHkdfStreamingKey} with the
- * following parameters:
+ * A {@link KeyTemplate} that generates new instances of {@link
+ * com.google.crypto.tink.proto.AesGcmHkdfStreamingKey} with the following parameters:
*
* <ul>
* <li>Size of the main key: 32 bytes
@@ -99,12 +99,16 @@ public final class StreamingAeadKeyTemplates {
public static final KeyTemplate AES256_GCM_HKDF_4KB =
createAesGcmHkdfStreamingKeyTemplate(32, HashType.SHA256, 32, 4096);
- /**
- * @return a {@code KeyTemplate} containing a {@code AesCtrHmacStreamingKeyFormat} with some
+ /**
+ * @return a {@link KeyTemplate} containing a {@link AesCtrHmacStreamingKeyFormat} with some
* specified parameters.
*/
- public static KeyTemplate createAesCtrHmacStreamingKeyTemplate(int mainKeySize,
- HashType hkdfHashType, int derivedKeySize, HashType macHashType, int tagSize,
+ public static KeyTemplate createAesCtrHmacStreamingKeyTemplate(
+ int mainKeySize,
+ HashType hkdfHashType,
+ int derivedKeySize,
+ HashType macHashType,
+ int tagSize,
int ciphertextSegmentSize) {
HmacParams hmacParams = HmacParams.newBuilder()
.setHash(macHashType)
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/AesCmac.java b/java/src/main/java/com/google/crypto/tink/subtle/AesCmac.java
index c86b35ee6..1bb2e4996 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/AesCmac.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/AesCmac.java
@@ -27,7 +27,9 @@ import javax.crypto.Cipher;
import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;
-/** An implementation of CMAC following https://tools.ietf.org/html/rfc4493 */
+/**
+ * An implementation of CMAC following <a href="https://tools.ietf.org/html/rfc4493">RFC 4493</a>.
+ */
@Alpha
public final class AesCmac implements Mac {
static final int MIN_TAG_SIZE_IN_BYTES = 10;
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/AesCtrHmacStreaming.java b/java/src/main/java/com/google/crypto/tink/subtle/AesCtrHmacStreaming.java
index d9b17b9ff..f068651cf 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/AesCtrHmacStreaming.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/AesCtrHmacStreaming.java
@@ -29,21 +29,18 @@ import javax.crypto.spec.SecretKeySpec;
/**
* Streaming encryption using AES-CTR and HMAC.
*
- * Each ciphertext uses a new AES-CTR key and HMAC key that ared derived from the key derivation
+ * <p>Each ciphertext uses a new AES-CTR key and HMAC key that ared derived from the key derivation
* key, a randomly chosen salt of the same size as the key and a nonce prefix using HKDF.
*
- * The the format of a ciphertext is
- * header || segment_0 || segment_1 || ... || segment_k.
- * The header has size this.getHeaderLength(). Its format is
- * headerLength || salt || prefix.
- * where headerLength is 1 byte determining the size of the header, salt is a salt used in the
- * key derivation and prefix is the prefix of the nonce.
- * In principle headerLength is redundant information, since the length of the header can be
- * determined from the key size.
+ * <p>The the format of a ciphertext is header || segment_0 || segment_1 || ... || segment_k. The
+ * header has size this.getHeaderLength(). Its format is headerLength || salt || prefix. where
+ * headerLength is 1 byte determining the size of the header, salt is a salt used in the key
+ * derivation and prefix is the prefix of the nonce. In principle headerLength is redundant
+ * information, since the length of the header can be determined from the key size.
*
- * segment_i is the i-th segment of the ciphertext. The size of segment_1 .. segment_{k-1}
- * is ciphertextSegmentSize. segment_0 is shorter, so that segment_0, the header
- * and other information of size firstSegmentOffset align with ciphertextSegmentSize.
+ * <p>segment_i is the i-th segment of the ciphertext. The size of segment_1 .. segment_{k-1} is
+ * ciphertextSegmentSize. segment_0 is shorter, so that segment_0, the header and other information
+ * of size firstSegmentOffset align with ciphertextSegmentSize.
*/
public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
// TODO(bleichen): Some things that are not yet decided:
@@ -81,6 +78,7 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
/**
* Initializes a streaming primitive with a key derivation key and encryption parameters.
+ *
* @param ikm input keying material used to derive sub keys.
* @param hkdfAlg the JCE MAC algorithm name, e.g., HmacSha256, used for the HKDF key derivation.
* @param keySizeInBytes the key size of the sub keys
@@ -88,9 +86,9 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
* @param tagSizeInBytes the size authentication tags
* @param ciphertextSegmentSize the size of ciphertext segments.
* @param firstSegmentOffset the offset of the first ciphertext segment. That means the first
- * segment has size ciphertextSegmentSize - getHeaderLength() - firstSegmentOffset
+ * segment has size ciphertextSegmentSize - getHeaderLength() - firstSegmentOffset
* @throws InvalidAlgorithmParameterException if ikm is too short, the key size not supported or
- * ciphertextSegmentSize is to short.
+ * ciphertextSegmentSize is to short.
*/
public AesCtrHmacStreaming(
byte[] ikm,
@@ -99,9 +97,15 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
String tagAlgo,
int tagSizeInBytes,
int ciphertextSegmentSize,
- int firstSegmentOffset) throws InvalidAlgorithmParameterException {
- validateParameters(ikm.length, keySizeInBytes, tagAlgo, tagSizeInBytes, ciphertextSegmentSize,
- firstSegmentOffset);
+ int firstSegmentOffset)
+ throws InvalidAlgorithmParameterException {
+ validateParameters(
+ ikm.length,
+ keySizeInBytes,
+ tagAlgo,
+ tagSizeInBytes,
+ ciphertextSegmentSize,
+ firstSegmentOffset);
this.ikm = Arrays.copyOf(ikm, ikm.length);
this.hkdfAlgo = hkdfAlgo;
this.keySizeInBytes = keySizeInBytes;
@@ -118,7 +122,8 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
String tagAlgo,
int tagSizeInBytes,
int ciphertextSegmentSize,
- int firstSegmentOffset) throws InvalidAlgorithmParameterException {
+ int firstSegmentOffset)
+ throws InvalidAlgorithmParameterException {
if (ikmSize < keySizeInBytes) {
throw new InvalidAlgorithmParameterException("ikm to short");
}
@@ -135,8 +140,13 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
throw new InvalidAlgorithmParameterException("tag size too big");
}
- int firstPlaintextSegment = ciphertextSegmentSize - firstSegmentOffset - tagSizeInBytes
- - keySizeInBytes - NONCE_PREFIX_IN_BYTES - 1;
+ int firstPlaintextSegment =
+ ciphertextSegmentSize
+ - firstSegmentOffset
+ - tagSizeInBytes
+ - keySizeInBytes
+ - NONCE_PREFIX_IN_BYTES
+ - 1;
if (firstPlaintextSegment <= 0) {
throw new InvalidAlgorithmParameterException("ciphertextSegmentSize too small");
}
@@ -149,8 +159,7 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
}
@Override
- public AesCtrHmacStreamDecrypter newStreamSegmentDecrypter()
- throws GeneralSecurityException {
+ public AesCtrHmacStreamDecrypter newStreamSegmentDecrypter() throws GeneralSecurityException {
return new AesCtrHmacStreamDecrypter();
}
@@ -184,8 +193,8 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
}
/**
- * Returns the expected size of the ciphertext for a given plaintext
- * The returned value includes the header and offset.
+ * Returns the expected size of the ciphertext for a given plaintext The returned value includes
+ * the header and offset.
*/
public long expectedCiphertextSize(long plaintextSize) {
long offset = getCiphertextOffset();
@@ -224,11 +233,9 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
return Random.randBytes(NONCE_PREFIX_IN_BYTES);
}
- private byte[] deriveKeyMaterial(
- byte[] salt,
- byte[] aad) throws GeneralSecurityException {
+ private byte[] deriveKeyMaterial(byte[] salt, byte[] aad) throws GeneralSecurityException {
int keyMaterialSize = keySizeInBytes + HMAC_KEY_SIZE_IN_BYTES;
- return Hkdf.computeHkdf(hkdfAlgo, ikm, salt, aad, keyMaterialSize);
+ return Hkdf.computeHkdf(hkdfAlgo, ikm, salt, aad, keyMaterialSize);
}
private SecretKeySpec deriveKeySpec(byte[] keyMaterial) throws GeneralSecurityException {
@@ -236,15 +243,13 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
}
private SecretKeySpec deriveHmacKeySpec(byte[] keyMaterial) throws GeneralSecurityException {
- return new SecretKeySpec(keyMaterial, keySizeInBytes, HMAC_KEY_SIZE_IN_BYTES,
- tagAlgo);
+ return new SecretKeySpec(keyMaterial, keySizeInBytes, HMAC_KEY_SIZE_IN_BYTES, tagAlgo);
}
/**
- * An instance of a crypter used to encrypt a plaintext stream.
- * The instances have state: encryptedSegments counts the number of encrypted
- * segments. This state is used to generate the IV for each segment.
- * By enforcing that only the method encryptSegment can increment this state,
+ * An instance of a crypter used to encrypt a plaintext stream. The instances have state:
+ * encryptedSegments counts the number of encrypted segments. This state is used to generate the
+ * IV for each segment. By enforcing that only the method encryptSegment can increment this state,
* we can guarantee that the IV does not repeat.
*/
class AesCtrHmacStreamEncrypter implements StreamSegmentEncrypter {
@@ -278,8 +283,8 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
}
/**
- * Encrypts the next plaintext segment.
- * This uses encryptedSegments as the segment number for the encryption.
+ * Encrypts the next plaintext segment. This uses encryptedSegments as the segment number for
+ * the encryption.
*/
@Override
public synchronized void encryptSegment(
@@ -301,9 +306,8 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
}
/**
- * Encrypt a segment consisting of two parts.
- * This method simplifies the case where one part of the plaintext is buffered
- * and the other part is passed in by the caller.
+ * Encrypt a segment consisting of two parts. This method simplifies the case where one part of
+ * the plaintext is buffered and the other part is passed in by the caller.
*/
@Override
public synchronized void encryptSegment(
@@ -332,9 +336,7 @@ public final class AesCtrHmacStreaming extends NonceBasedStreamingAead {
}
}
- /**
- * An instance of a crypter used to decrypt a ciphertext stream.
- */
+ /** An instance of a crypter used to decrypt a ciphertext stream. */
class AesCtrHmacStreamDecrypter implements StreamSegmentDecrypter {
private SecretKeySpec keySpec;
private SecretKeySpec hmacKeySpec;
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/AesCtrJceCipher.java b/java/src/main/java/com/google/crypto/tink/subtle/AesCtrJceCipher.java
index fc1aad0d7..cde5b3160 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/AesCtrJceCipher.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/AesCtrJceCipher.java
@@ -22,9 +22,10 @@ import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
/**
- * The primitive implements AES counter mode with random IVs, using JCE. It is safe against
- * chosen-plaintext attacks, but does not provide ciphertext integrity, thus is unsafe against
- * chosen-ciphertext attacks.
+ * The primitive implements AES counter mode with random IVs, using JCE.
+ *
+ * <p>It is safe against chosen-plaintext attacks, but does not provide ciphertext integrity, thus
+ * is unsafe against chosen-ciphertext attacks.
*/
public final class AesCtrJceCipher implements IndCpaCipher {
private static final String KEY_ALGORITHM = "AES";
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/AesEaxJce.java b/java/src/main/java/com/google/crypto/tink/subtle/AesEaxJce.java
index 9afed32f8..34868fd1a 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/AesEaxJce.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/AesEaxJce.java
@@ -27,9 +27,11 @@ import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
/**
- * This class implements the EAX mode using AES. EAX is an encryption mode proposed by Bellare,
- * Rogaway and Wagner (http://web.cs.ucdavis.edu/~rogaway/papers/eax.pdf). The encryption mode is an
- * alternative to CCM and has been proposed as a NIST standard:
+ * This class implements the EAX mode using AES.
+ *
+ * <p>EAX is an encryption mode proposed by Bellare, Rogaway and Wagner
+ * (http://web.cs.ucdavis.edu/~rogaway/papers/eax.pdf). The encryption mode is an alternative to CCM
+ * and has been proposed as a NIST standard:
* http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/eax/eax-spec.pdf
*
* <p>The parameter choices have been restricted to a small set of options:
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/AesSiv.java b/java/src/main/java/com/google/crypto/tink/subtle/AesSiv.java
index 775f070f1..dacf8932c 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/AesSiv.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/AesSiv.java
@@ -28,7 +28,7 @@ import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
/**
- * AES-SIV per https://tools.ietf.org/html/rfc5297.
+ * AES-SIV, as described in <a href="https://tools.ietf.org/html/rfc5297">RFC 5297</a>.
*
* <p>To meet the security requirements of {@link DeterministicAead}, this cipher can only be used
* with 192-bit or 256-bit keys.
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/Base64.java b/java/src/main/java/com/google/crypto/tink/subtle/Base64.java
index 3843e4c3c..dc2de06f3 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/Base64.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/Base64.java
@@ -20,8 +20,9 @@ import java.io.UnsupportedEncodingException;
import java.nio.charset.Charset;
/**
- * Utilities for encoding and decoding the Base64 representation of binary data. See RFCs <a
- * href="http://www.ietf.org/rfc/rfc2045.txt">2045</a> and <a
+ * Utilities for encoding and decoding the Base64 representation of binary data.
+ *
+ * <p>See RFCs <a href="http://www.ietf.org/rfc/rfc2045.txt">2045</a> and <a
* href="http://www.ietf.org/rfc/rfc3548.txt">3548</a>.
*
* <p>This is a copy of android.util.Base64, with minor modifications to to fix style and ErrorProne
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/ChaCha20.java b/java/src/main/java/com/google/crypto/tink/subtle/ChaCha20.java
index cb18fff63..5d0561dd3 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/ChaCha20.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/ChaCha20.java
@@ -21,7 +21,7 @@ import java.nio.ByteOrder;
import java.security.InvalidKeyException;
/**
- * A stream cipher based on RFC7539 (i.e., uses 96-bit random nonces).
+ * A stream cipher based on RFC7539 (i.e., uses 96-bit random nonces)
* https://tools.ietf.org/html/rfc7539
*
* <p>This cipher is meant to be used to construct an AEAD with Poly1305.
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/ChaCha20Poly1305.java b/java/src/main/java/com/google/crypto/tink/subtle/ChaCha20Poly1305.java
index c70427aea..cfc0f4afb 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/ChaCha20Poly1305.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/ChaCha20Poly1305.java
@@ -19,8 +19,8 @@ package com.google.crypto.tink.subtle;
import java.security.InvalidKeyException;
/**
- * ChaCha20-Poly1305 AEAD construction, compatible with <a
- * href="https://tools.ietf.org/html/rfc7539#section-2.8">RFC 7539, section 2.8</a>.
+ * ChaCha20-Poly1305, as described in <a href="https://tools.ietf.org/html/rfc7539#section-2.8">RFC
+ * 7539, section 2.8</a>.
*/
public final class ChaCha20Poly1305 extends SnufflePoly1305 {
public ChaCha20Poly1305(final byte[] key) throws InvalidKeyException {
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/EcdsaSignJce.java b/java/src/main/java/com/google/crypto/tink/subtle/EcdsaSignJce.java
index 3264bef1e..b4e1d2409 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/EcdsaSignJce.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/EcdsaSignJce.java
@@ -21,7 +21,7 @@ import java.security.GeneralSecurityException;
import java.security.Signature;
import java.security.interfaces.ECPrivateKey;
-/** Ecdsa signature's signing in JCE. */
+/** ECDSA signing with JCE. */
public final class EcdsaSignJce implements PublicKeySign {
private final ECPrivateKey privateKey;
private final String signatureAlgorithm;
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/EcdsaVerifyJce.java b/java/src/main/java/com/google/crypto/tink/subtle/EcdsaVerifyJce.java
index c4e390eed..208777078 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/EcdsaVerifyJce.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/EcdsaVerifyJce.java
@@ -21,7 +21,7 @@ import java.security.GeneralSecurityException;
import java.security.Signature;
import java.security.interfaces.ECPublicKey;
-/** Ecdsa signature's verification in JCE. */
+/** ECDSA verifying with JCE. */
public final class EcdsaVerifyJce implements PublicKeyVerify {
private final ECPublicKey publicKey;
private final String signatureAlgorithm;
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/Ed25519.java b/java/src/main/java/com/google/crypto/tink/subtle/Ed25519.java
index 18cf37d36..36fc24332 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/Ed25519.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/Ed25519.java
@@ -31,13 +31,17 @@ import java.util.Arrays;
/**
* This implementation is based on the ed25519/ref10 implementation in NaCl.
- * The twisted Edwards curve implemented:
+ *
+ * <p>It implements this twisted Edwards curve:
+ *
+ * <pre>
* -x^2 + y^2 = 1 + (-121665 / 121666 mod 2^255-19)*x^2*y^2
+ * </pre>
*
- * See
- * Bernstein D.J., Birkner P., Joye M., Lange T., Peters C. (2008) Twisted Edwards Curves.
- * Hisil H., Wong K.KH., Carter G., Dawson E. (2008) Twisted Edwards Curves Revisited.
- * for more information.
+ * @see <a href="https://eprint.iacr.org/2008/013.pdf">Bernstein D.J., Birkner P., Joye M., Lange
+ * T., Peters C. (2008) Twisted Edwards Curves</a>
+ * @see <a href="https://eprint.iacr.org/2008/522.pdf">Hisil H., Wong K.KH., Carter G., Dawson E.
+ * (2008) Twisted Edwards Curves Revisited</a>
*/
@Alpha
public final class Ed25519 {
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/Ed25519Sign.java b/java/src/main/java/com/google/crypto/tink/subtle/Ed25519Sign.java
index c37fef060..13120fc82 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/Ed25519Sign.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/Ed25519Sign.java
@@ -26,12 +26,12 @@ import java.util.Arrays;
*
* <p>Usage:
*
- * <pre>
+ * <pre>{@code
* Ed25519Sign.KeyPair keyPair = Ed25519Sign.KeyPair.newKeyPair();
* // securely store keyPair and share keyPair.getPublicKey()
* Ed25519Sign signer = new Ed25519Sign(keyPair.getPrivateKey());
* byte[] signature = signer.sign(message);
- * </pre>
+ * }</pre>
*/
@Alpha
public final class Ed25519Sign implements PublicKeySign {
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/Ed25519Verify.java b/java/src/main/java/com/google/crypto/tink/subtle/Ed25519Verify.java
index ef300b307..6ca089b77 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/Ed25519Verify.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/Ed25519Verify.java
@@ -26,19 +26,15 @@ import java.security.GeneralSecurityException;
*
* <p>Usage:
*
- * <pre>
+ * <pre>{@code
* // get the publicKey from the other party.
* Ed25519Verify verifier = new Ed25519Verify(publicKey);
* try {
* verifier.verify(signature, message);
- * } catch (SignatureException se) {
- * // handle signature check failure.
* } catch (GeneralSecurityException e) {
* // all the rest of security exceptions.
* }
- * </pre>
- * TODO(bleichen): Actually, the implementation does not follow the above description:
- * an invalid signature does not throw a SignatureException.
+ * }</pre>
*/
@Alpha
@Immutable
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/EncryptThenAuthenticate.java b/java/src/main/java/com/google/crypto/tink/subtle/EncryptThenAuthenticate.java
index a5c8d3883..c4e112bff 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/EncryptThenAuthenticate.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/EncryptThenAuthenticate.java
@@ -24,9 +24,11 @@ import java.util.Arrays;
/**
* This primitive performs an encrypt-then-Mac operation on plaintext and additional authenticated
- * data (aad). The Mac is computed over (aad || ciphertext || size of aad), thus it doesn't violate
- * the <a href="https://en.wikipedia.org/wiki/Horton_Principle">Horton Principle</a>. This
- * implementation is based on <a
+ * data (aad).
+ *
+ * <p>The Mac is computed over (aad || ciphertext || size of aad), thus it doesn't violate the <a
+ * href="https://en.wikipedia.org/wiki/Horton_Principle">Horton Principle</a>. This implementation
+ * is based on <a
* href="http://tools.ietf.org/html/draft-mcgrew-aead-aes-cbc-hmac-sha2-05">Authenticated Encryption
* with AES-CBC and HMAC-SHA</a>.
*/
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/EngineWrapper.java b/java/src/main/java/com/google/crypto/tink/subtle/EngineWrapper.java
index 36d41643d..6cba1e35d 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/EngineWrapper.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/EngineWrapper.java
@@ -27,9 +27,10 @@ import javax.crypto.KeyAgreement;
import javax.crypto.Mac;
/**
- * Interface and its implentations to make JCE Engines have a common parent. There's no expected
- * reason to directly import this for users of Tink, but it might be needed to implement it (say, if
- * someone wants a new type of engine).
+ * Interface and its implentations to make JCE Engines have a common parent.
+ *
+ * <p>There's no expected reason to directly import this for users of Tink, but it might be needed
+ * to implement it (say, if someone wants a new type of engine).
*/
public interface EngineWrapper<T> {
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/Field25519.java b/java/src/main/java/com/google/crypto/tink/subtle/Field25519.java
index afeda7e07..179500839 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/Field25519.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/Field25519.java
@@ -20,14 +20,17 @@ import com.google.crypto.tink.annotations.Alpha;
import java.util.Arrays;
/**
- * Defines field 25519 function based on curve25519-donna C implementation (mostly identical).
- * <p>See https://github.com/agl/curve25519-donna/blob/master/curve25519-donna.c
- *
- * <p>Field element mixed radix representation:
+ * Defines field 25519 function based on <a
+ * href="https://github.com/agl/curve25519-donna/blob/master/curve25519-donna.c">curve25519-donna C
+ * implementation</a> (mostly identical).
*
* <p>Field elements are written as an array of signed, 64-bit limbs (an array of longs), least
- * significant first. The value of the field element is: x[0] + 2^26·x[1] + 2^51·x[2] + 2^77·x[3] +
- * 2^102·x[4] + 2^128·x[5] + 2^153·x[6] + 2^179·x[7] + 2^204·x[8] + 2^230·x[9]
+ * significant first. The value of the field element is:
+ *
+ * <pre>
+ * x[0] + 2^26·x[1] + 2^51·x[2] + 2^77·x[3] + 2^102·x[4] + 2^128·x[5] + 2^153·x[6] + 2^179·x[7] +
+ * 2^204·x[8] + 2^230·x[9],
+ * </pre>
*
* <p>i.e. the limbs are 26, 25, 26, 25, ... bits wide.
*/
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/Hkdf.java b/java/src/main/java/com/google/crypto/tink/subtle/Hkdf.java
index 86d258cd2..b10b72afd 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/Hkdf.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/Hkdf.java
@@ -21,8 +21,8 @@ import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
/**
- * This class implements HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
- * https://tools.ietf.org/html/rfc5869.
+ * This class implements HMAC-based Extract-and-Expand Key Derivation Function (HKDF), as described
+ * in <a href="https://tools.ietf.org/html/rfc5869">RFC 5869</a>.
*/
public final class Hkdf {
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/IndCpaCipher.java b/java/src/main/java/com/google/crypto/tink/subtle/IndCpaCipher.java
index 80d728b3b..2667d448c 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/IndCpaCipher.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/IndCpaCipher.java
@@ -20,8 +20,10 @@ import java.security.GeneralSecurityException;
/**
* This interface for symmetric key ciphers that are indistinguishable against chosen-plaintext
- * attacks. Said primitives do not provide authentication, thus should not be used directly, but
- * only to construct safer primitives such as Aead.
+ * attacks.
+ *
+ * <p>Said primitives do not provide authentication, thus should not be used directly, but only to
+ * construct safer primitives such as {@link com.google.crypto.tink.Aead}.
*/
public interface IndCpaCipher {
/**
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/MacJce.java b/java/src/main/java/com/google/crypto/tink/subtle/MacJce.java
index 79190bd9d..afe1609ef 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/MacJce.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/MacJce.java
@@ -21,7 +21,7 @@ import java.security.GeneralSecurityException;
import java.security.InvalidAlgorithmParameterException;
import java.security.NoSuchAlgorithmException;
-/** Mac implementations in JCE. */
+/** {@link Mac} implementations in JCE. */
public final class MacJce implements Mac {
static final int MIN_TAG_SIZE_IN_BYTES = 10;
static final int MIN_KEY_SIZE_IN_BYTES = 16;
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/NonceBasedStreamingAead.java b/java/src/main/java/com/google/crypto/tink/subtle/NonceBasedStreamingAead.java
index 2fb31bc11..31235b9a0 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/NonceBasedStreamingAead.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/NonceBasedStreamingAead.java
@@ -26,9 +26,9 @@ import java.nio.channels.WritableByteChannel;
import java.security.GeneralSecurityException;
/**
- * An abstract class for StreamingAead using the nonce based online encryption scheme proposed in
- * "Online Authenticated-Encryption and its Nonce-Reuse Misuse-Resistance" by Hoang, Reyhanitabar,
- * Rogaway and Vizár https://eprint.iacr.org/2015/189.pdf
+ * An abstract class for StreamingAead using the nonce based online encryption scheme proposed in <a
+ * href="https://eprint.iacr.org/2015/189.pdf">Online Authenticated-Encryption and its Nonce-Reuse
+ * Misuse-Resistance</a> by Hoang, Reyhanitabar, Rogaway and Vizár.
*/
abstract class NonceBasedStreamingAead implements StreamingAead {
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/Poly1305.java b/java/src/main/java/com/google/crypto/tink/subtle/Poly1305.java
index e59945c69..0ad6fad5d 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/Poly1305.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/Poly1305.java
@@ -20,8 +20,10 @@ import java.security.GeneralSecurityException;
import java.util.Arrays;
/**
- * Poly1305 one-time MAC based on RFC 7539 This is not an implementation of the MAC interface on
- * purpose and it is not equivalent to HMAC.
+ * Poly1305 one-time MAC based on RFC 7539.
+ *
+ * <p>This is not an implementation of the MAC interface on purpose and it is not equivalent to
+ * HMAC.
*
* <p>The implementation is based on poly1305 implementation by Andrew Moon
* (https://github.com/floodyberry/poly1305-donna) and released as public domain.
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/Random.java b/java/src/main/java/com/google/crypto/tink/subtle/Random.java
index 6eabe1a8f..25c83e081 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/Random.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/Random.java
@@ -18,7 +18,7 @@ package com.google.crypto.tink.subtle;
import java.security.SecureRandom;
-/** A simple wrapper of SecureRandom. */
+/** A simple wrapper of {@link SecureRandom}. */
public final class Random {
private static final ThreadLocal<SecureRandom> localRandom = new ThreadLocal<SecureRandom>() {
@Override
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/RewindableReadableByteChannel.java b/java/src/main/java/com/google/crypto/tink/subtle/RewindableReadableByteChannel.java
index 19738f688..0576087cd 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/RewindableReadableByteChannel.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/RewindableReadableByteChannel.java
@@ -22,12 +22,11 @@ import java.nio.channels.ReadableByteChannel;
import javax.annotation.concurrent.GuardedBy;
/**
- * A wrapper around {@link ReadableByteChannel} that provides rewinding feature:
- * it caches the read bytes so that after reading some initial part of the channel,
- * one can "rewind" the channel and again read the bytes from the beginning.
- * Once the rewinding feature is not needed any more, it can be disabled via
- * {@link disableRewinding()}: this frees the cache memory and forwadrds
- * the subsequent read()-calls directly to the wrapped channel.
+ * A wrapper around {@link ReadableByteChannel} that provides rewinding feature: it caches the read
+ * bytes so that after reading some initial part of the channel, one can "rewind" the channel and
+ * again read the bytes from the beginning. Once the rewinding feature is not needed any more, it
+ * can be disabled via {@link #disableRewinding}: this frees the cache memory and forwadrds the
+ * subsequent {@link #read}-calls directly to the wrapped channel.
*/
public final class RewindableReadableByteChannel implements ReadableByteChannel {
@GuardedBy("this")
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/SnufflePoly1305.java b/java/src/main/java/com/google/crypto/tink/subtle/SnufflePoly1305.java
index 46662f9e7..3fe3a377c 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/SnufflePoly1305.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/SnufflePoly1305.java
@@ -28,8 +28,8 @@ import java.security.InvalidKeyException;
import javax.crypto.AEADBadTagException;
/**
- * An {@link Aead} construction with a {@link com.google.crypto.tink.subtle.Snuffle} and {@link
- * com.google.crypto.tink.subtle.Poly1305}, following RFC 7539, section 2.8.
+ * An {@link Aead} construction with a {@link Snuffle} and {@link Poly1305}, following RFC 7539,
+ * section 2.8.
*
* <p>This implementation produces ciphertext with the following format: {@code nonce ||
* actual_ciphertext || tag} and only decrypts the same format.
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/StreamSegmentDecrypter.java b/java/src/main/java/com/google/crypto/tink/subtle/StreamSegmentDecrypter.java
index d77f8cb79..78a2290a5 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/StreamSegmentDecrypter.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/StreamSegmentDecrypter.java
@@ -16,16 +16,15 @@
package com.google.crypto.tink.subtle;
-import com.google.crypto.tink.annotations.Alpha;
import java.nio.ByteBuffer;
import java.security.GeneralSecurityException;
/**
- * StreamSegmentDecrypter is a helper class that decrypts individual segments of a stream. Instances
- * of this interfaces are passed to ...DecryptingChannel. Each instance must be initialized with the
- * header of the ciphertext.
+ * StreamSegmentDecrypter is a helper class that decrypts individual segments of a stream.
+ *
+ * <p>Instances of this interfaces are passed to {@link StreamingAeadDecryptingChannel}. Each
+ * instance must be initialized with the header of the ciphertext.
*/
-@Alpha
public interface StreamSegmentDecrypter {
void init(ByteBuffer header, byte[] aad) throws GeneralSecurityException;
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/StreamSegmentEncrypter.java b/java/src/main/java/com/google/crypto/tink/subtle/StreamSegmentEncrypter.java
index 2c71735d9..2ea9adbe6 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/StreamSegmentEncrypter.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/StreamSegmentEncrypter.java
@@ -16,24 +16,22 @@
package com.google.crypto.tink.subtle;
-import com.google.crypto.tink.annotations.Alpha;
import java.nio.ByteBuffer;
import java.security.GeneralSecurityException;
/**
* StreamSegmentEncrypter is a helper class that encrypts individual segments of a stream.
- * Instances of this interfaces are passed to ...EncryptingChannel.
- * Each instance of a segment encrypter is used to encrypt one stream.
- * Typically, constructing a new StreamSegmentEncrypter results in the generation of a new
- * symmetric key. This new symmetric key is used to encrypt the segments of the stream.
- * The key itself wrapped with or derived from the key from StreamingAead instance.
- * The wrapped key or the salt used to derive the symmetric key is part of the header.
*
- * A StreamSegmentEncrypter has a state: it keeps the number of segments encrypted so far.
- * This state is used to encrypt each segment with different parameters, so that segments
- * in the ciphertext cannot be switched.
+ * <p>Instances of this interfaces are passed to ...EncryptingChannel. Each instance of a segment
+ * encrypter is used to encrypt one stream. Typically, constructing a new StreamSegmentEncrypter
+ * results in the generation of a new symmetric key. This new symmetric key is used to encrypt the
+ * segments of the stream. The key itself wrapped with or derived from the key from StreamingAead
+ * instance. The wrapped key or the salt used to derive the symmetric key is part of the header.
+ *
+ * <p>A StreamSegmentEncrypter has a state: it keeps the number of segments encrypted so far. This
+ * state is used to encrypt each segment with different parameters, so that segments in the
+ * ciphertext cannot be switched.
*/
-@Alpha
public interface StreamSegmentEncrypter {
/**
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadDecryptingChannel.java b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadDecryptingChannel.java
index 6c401828a..e1f38663a 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadDecryptingChannel.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadDecryptingChannel.java
@@ -22,9 +22,7 @@ import java.nio.channels.ReadableByteChannel;
import java.security.GeneralSecurityException;
import java.util.Arrays;
-/**
- * An instance of a ReadableByteChannel that returns the plaintext for some ciphertext.
- */
+/** An instance of {@link ReadableByteChannel} that returns the plaintext for some ciphertext. */
class StreamingAeadDecryptingChannel implements ReadableByteChannel {
// Each plaintext segment has 16 bytes more of memory than the actual plaintext that it contains.
// This is a workaround for an incompatibility between Conscrypt and OpenJDK in their
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadDecryptingStream.java b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadDecryptingStream.java
index 42ed8520b..40ab8a8b7 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadDecryptingStream.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadDecryptingStream.java
@@ -25,7 +25,8 @@ import java.util.Arrays;
/**
* An instance of a InputStream that returns the plaintext for some ciphertext.
- * TODO(bleichen): define what the state is after an IOException.
+ *
+ * <p>TODO(bleichen): define what the state is after an IOException.
*/
class StreamingAeadDecryptingStream extends FilterInputStream {
// Each plaintext segment has 16 bytes more of memory than the actual plaintext that it contains.
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadEncryptingChannel.java b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadEncryptingChannel.java
index b683baf53..34d091855 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadEncryptingChannel.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadEncryptingChannel.java
@@ -23,7 +23,7 @@ import java.nio.channels.WritableByteChannel;
import java.security.GeneralSecurityException;
/**
- * An instance of {WritableByteChannel} that encrypts the input using a nonce based online
+ * An instance of {@link WritableByteChannel} that encrypts the input using a nonce based online
* authentication scheme.
*/
class StreamingAeadEncryptingChannel implements WritableByteChannel {
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadEncryptingStream.java b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadEncryptingStream.java
index 4af33371b..a7c9c6e92 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadEncryptingStream.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadEncryptingStream.java
@@ -23,7 +23,7 @@ import java.nio.ByteBuffer;
import java.security.GeneralSecurityException;
/**
- * An instance of {FilterOutputStream} that encrypts the input using a nonce based online
+ * An instance of {@link FilterOutputStream} that encrypts the input using a nonce based online
* authentication scheme.
*/
class StreamingAeadEncryptingStream extends FilterOutputStream {
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadSeekableDecryptingChannel.java b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadSeekableDecryptingChannel.java
index 03e27d9a2..056320354 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadSeekableDecryptingChannel.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/StreamingAeadSeekableDecryptingChannel.java
@@ -25,8 +25,8 @@ import java.security.GeneralSecurityException;
import java.util.Arrays;
/**
- * An instance of {code SeekableByteChannel} that allows random access to the plaintext of
- * some ciphertext.
+ * An instance of {@link SeekableByteChannel} that allows random access to the plaintext of some
+ * ciphertext.
*/
class StreamingAeadSeekableDecryptingChannel implements SeekableByteChannel {
// Each plaintext segment has 16 bytes more of memory than the actual plaintext that it contains.
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/X25519.java b/java/src/main/java/com/google/crypto/tink/subtle/X25519.java
index 6540c4999..7a767a397 100644
--- a/java/src/main/java/com/google/crypto/tink/subtle/X25519.java
+++ b/java/src/main/java/com/google/crypto/tink/subtle/X25519.java
@@ -25,8 +25,7 @@ import java.util.Arrays;
* also known as the X25519 function.
*
* <p>This implementation is based on <a
- * href="https://github.com/agl/curve25519-donna/blob/master/curve25519-donna.c">curve255-donna C
- * implementation</a>.
+ * href="https://github.com/agl/curve25519-donna/blob/master/curve25519-donna.c">curve255-donna</a>.
*
* <p>Example Usage:
*
diff --git a/java/src/main/java/com/google/crypto/tink/subtle/XSalsa20.java b/java/src/main/java/com/google/crypto/tink/subtle/XSalsa20.java
deleted file mode 100644
index 53015cf51..000000000
--- a/java/src/main/java/com/google/crypto/tink/subtle/XSalsa20.java
+++ /dev/null
@@ -1,140 +0,0 @@
-// Copyright 2017 Google Inc. //
-// Licensed under the Apache License, Version 2.0 (the "License");
-// you may not use this file except in compliance with the License.
-// You may obtain a copy of the License at
-//
-// http://www.apache.org/licenses/LICENSE-2.0
-//
-// Unless required by applicable law or agreed to in writing, software
-// distributed under the License is distributed on an "AS IS" BASIS,
-// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-// See the License for the specific language governing permissions and
-// limitations under the License.
-//
-////////////////////////////////////////////////////////////////////////////////
-
-package com.google.crypto.tink.subtle;
-
-import com.google.crypto.tink.annotations.Alpha;
-import java.nio.ByteBuffer;
-import java.nio.ByteOrder;
-import java.security.InvalidKeyException;
-
-/**
- * XSalsa20 stream cipher, see https://cr.yp.to/snuffle/xsalsa-20081128.pdf.
- *
- * <p>This cipher is meant to be used to construct an AEAD with Poly1305.
- */
-@Alpha
-class XSalsa20 extends Snuffle {
- private static final byte[] ZERO_16_BYTES = new byte[16];
-
- /**
- * Constructs a new {@link XSalsa20} cipher with the supplied {@code key}.
- *
- * @throws IllegalArgumentException when {@code key} length is not {@link
- * Snuffle#KEY_SIZE_IN_BYTES}.
- */
- XSalsa20(final byte[] key, int initialCounter) throws InvalidKeyException {
- super(key, initialCounter);
- }
-
- @Override
- ByteBuffer getKeyStreamBlock(final byte[] nonce, int counter) {
- int[] state = createInitialState(nonce, counter);
- int[] workingState = state.clone();
- shuffleState(workingState);
- for (int i = 0; i < state.length; i++) {
- state[i] += workingState[i];
- }
- ByteBuffer out = ByteBuffer.allocate(BLOCK_SIZE_IN_BYTES).order(ByteOrder.LITTLE_ENDIAN);
- out.asIntBuffer().put(state, 0, BLOCK_SIZE_IN_INTS);
- return out;
- }
-
- @Override
- int nonceSizeInBytes() {
- return 24;
- }
-
- private int[] createInitialState(final byte[] nonce, int counter) {
- // Set the initial state based on https://cr.yp.to/snuffle/xsalsa-20081128.pdf
- int[] state = new int[BLOCK_SIZE_IN_INTS];
- setSigma(state);
- setKey(state, hSalsa20(key.getBytes(), nonce));
- int[] nonceInt = toIntArray(ByteBuffer.wrap(nonce));
- state[6] = nonceInt[4];
- state[7] = nonceInt[5];
- state[8] = counter;
- state[9] = 0;
- return state;
- }
-
- static void quarterRound(int[] x, int a, int b, int c, int d) {
- x[b] ^= rotateLeft(x[a] + x[d], 7);
- x[c] ^= rotateLeft(x[b] + x[a], 9);
- x[d] ^= rotateLeft(x[c] + x[b], 13);
- x[a] ^= rotateLeft(x[d] + x[c], 18);
- }
-
- static void columnRound(final int[] state) {
- quarterRound(state, 0, 4, 8, 12);
- quarterRound(state, 5, 9, 13, 1);
- quarterRound(state, 10, 14, 2, 6);
- quarterRound(state, 15, 3, 7, 11);
- }
-
- static void rowRound(final int[] state) {
- quarterRound(state, 0, 1, 2, 3);
- quarterRound(state, 5, 6, 7, 4);
- quarterRound(state, 10, 11, 8, 9);
- quarterRound(state, 15, 12, 13, 14);
- }
-
- private static void shuffleState(final int[] state) {
- for (int i = 0; i < 10; i++) {
- columnRound(state);
- rowRound(state);
- }
- }
-
- private static void setSigma(int[] state) {
- state[0] = SIGMA[0];
- state[5] = SIGMA[1];
- state[10] = SIGMA[2];
- state[15] = SIGMA[3];
- }
-
- private static void setKey(int[] state, final byte[] key) {
- int[] keyInt = toIntArray(ByteBuffer.wrap(key));
- System.arraycopy(keyInt, 0, state, 1, 4);
- System.arraycopy(keyInt, 4, state, 11, 4);
- }
-
- static byte[] hSalsa20(final byte[] key) {
- return hSalsa20(key, ZERO_16_BYTES);
- }
-
- static byte[] hSalsa20(final byte[] key, final byte[] nonce) {
- int[] state = new int[BLOCK_SIZE_IN_INTS];
- setSigma(state);
- setKey(state, key);
- int[] nonceInt = toIntArray(ByteBuffer.wrap(nonce));
- state[6] = nonceInt[0];
- state[7] = nonceInt[1];
- state[8] = nonceInt[2];
- state[9] = nonceInt[3];
- shuffleState(state);
- // state[0] = state[0]
- state[1] = state[5];
- state[2] = state[10];
- state[3] = state[15];
- state[4] = state[6];
- state[5] = state[7];
- state[6] = state[8];
- state[7] = state[9];
- ByteBuffer buf = ByteBuffer.allocate(32).order(ByteOrder.LITTLE_ENDIAN);
- buf.asIntBuffer().put(state, 0, 8);
- return buf.array();
- }
-}
--
GitLab