fix javadoc issues

[deploy]

Author: overheadhunter

src/main/java/org/cryptomator/siv/CMac.java

@@ -157,6 +157,9 @@ private static void encryptBlock(Cipher cipher, byte[] block, byte[] output) {
 
 	/**
 	 * Create a new CMAC instance for incremental message processing
+	 * @param key The AES key (16, 24, or 32 bytes)
+	 * @return The CMAC instance
+	 * @throws IllegalArgumentException if the key length is invalid
 	 */
 	public static CMac create(byte[] key) {
 		if (key.length != 16 && key.length != 24 && key.length != 32) {
@@ -175,6 +178,10 @@ public static CMac create(byte[] key) {
 
 	/**
 	 * One-shot CMAC computation
+	 * @param key The AES key (16, 24, or 32 bytes)
+	 * @param message The message to authenticate
+	 * @return The CMAC tag (always {@value BLOCK_SIZE} bytes)
+	 * @throws IllegalArgumentException if the key length is invalid
 	 */
 	public static byte[] tag(byte[] key, byte[] message) {
 		CMac cmac = create(key);

src/main/java/org/cryptomator/siv/SivCipher.java

@@ -18,6 +18,11 @@
 import java.util.Arrays;
 import java.util.List;
 
+/**
+ * JCE Cipher implementation for AES-SIV mode.
+ * <p>
+ * This cipher implements the Synthetic Initialization Vector (SIV) mode as specified in RFC 5297.
+ */
 public class SivCipher extends CipherSpi {
 
 	private static final byte[] EMPTY = new byte[0];

src/main/java/org/cryptomator/siv/SivEngine.java

@@ -21,6 +21,11 @@
 
 /**
  * Implements the RFC 5297 SIV mode.
+ * <p>
+ * Note: Instances of this class are not thread-safe.
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc5297">RFC 5297</a>
+ * @since 2.0
  */
 public final class SivEngine {
 
@@ -86,6 +91,17 @@ public byte[] encrypt(byte[] plaintext, byte[]... associatedData) {
 		return ciphertext;
 	}
 
+	/**
+	 * Encrypts plaintext using SIV mode and writes the result to the provided output buffer.
+	 *
+	 * @param plaintext      Your plaintext, which shall be encrypted.
+	 * @param output         The output buffer to write IV + ciphertext to.
+	 * @param outputOffset   The offset in the output buffer to start writing at.
+	 * @param associatedData Optional associated data, which gets authenticated but not encrypted.
+	 * @return The number of bytes written to the output buffer (should always be {@value IV_LENGTH} + plaintext length).
+	 * @throws ShortBufferException     If the output buffer is too small.
+	 * @throws IllegalArgumentException if either param exceeds the limits for safe use.
+	 */
 	public int encrypt(byte[] plaintext, byte[] output, int outputOffset, byte[]... associatedData) throws ShortBufferException {
 		// Check if plaintext length will cause overflows
 		if (plaintext.length > (Integer.MAX_VALUE - IV_LENGTH)) {
@@ -104,11 +120,12 @@ public int encrypt(byte[] plaintext, byte[] output, int outputOffset, byte[]...
 	/**
 	 * Decrypts ciphertext using SIV mode. A block cipher defined by the constructor is being used.<br>
 	 *
-	 * @param ciphertext     Your ciphertext, which shall be encrypted.
+	 * @param ciphertext     Your ciphertext, which shall be decrypted.
 	 * @param associatedData Optional associated data, which needs to be authenticated during decryption.
 	 * @return Plaintext byte array.
-	 * @throws AEADBadTagException If the authentication failed, e.g. because ciphertext and/or associatedData are corrupted.
-	 * @throws IllegalBlockSizeException      If the provided ciphertext is of invalid length.
+	 * @throws AEADBadTagException       If the authentication failed, e.g. because ciphertext and/or associatedData are corrupted.
+	 * @throws IllegalBlockSizeException If the provided ciphertext is shorter than 16 bytes.
+	 * @throws IllegalArgumentException  If number of associatedData fields exceed the limits for safe use.
 	 */
 	public byte[] decrypt(byte[] ciphertext, byte[]... associatedData) throws AEADBadTagException, IllegalBlockSizeException {
 		if (ciphertext.length < IV_LENGTH) {

src/main/java/org/cryptomator/siv/SivMode.java

@@ -68,7 +68,7 @@ public byte[] encrypt(SecretKey ctrKey, SecretKey macKey, byte[] plaintext, byte
 	 * @param plaintext      Your plaintext, which shall be encrypted.
 	 * @param associatedData Optional associated data, which gets authenticated but not encrypted.
 	 * @return IV + Ciphertext as a concatenated byte array.
-	 * @throws IllegalArgumentException if the either of the two keys is of invalid length for the used {@link BlockCipher}.
+	 * @throws IllegalArgumentException if the either of the two keys is of invalid length.
 	 */
 	public byte[] encrypt(byte[] ctrKey, byte[] macKey, byte[] plaintext, byte[]... associatedData) {
 		byte[] combinedKey = new byte[ctrKey.length + macKey.length];

src/main/java/org/cryptomator/siv/SivProvider.java

@@ -3,12 +3,27 @@
 import java.security.Provider;
 import java.util.HashMap;
 
+/**
+ * JCE Security Provider for AES-SIV mode.
+ * <p>
+ * Provides implementations for:
+ * <ul>
+ *   <li>CMAC (Cipher-based Message Authentication Code)</li>
+ *   <li>AES/SIV/NoPadding cipher</li>
+ * </ul>
+ */
 public class SivProvider extends Provider {
 
+	/**
+	 * Singleton instance of the SIV provider.
+	 */
 	public static final SivProvider INSTANCE = new SivProvider();
 
+	/**
+	 * Constructs a new SIV provider and registers the available algorithms.
+	 */
 	public SivProvider() {
-		super("SIV", 2.0, "");
+		super("SIV", 2.0, "AES-SIV mode provider for authenticated encryption");
 		putService(new Service(this, "Mac", "CMAC", CMac.class.getName(), null, new HashMap<>()));
 		putService(new Service(this, "Cipher", "AES/SIV/NoPadding", SivCipher.class.getName(), null, new HashMap<>()));
 	}

src/main/java/org/cryptomator/siv/Utils.java

@@ -2,6 +2,11 @@
 
 import java.util.Arrays;
 
+/**
+ * Utility methods for cryptographic operations.
+ * <p>
+ * Provides bit manipulation and padding operations used in AES-SIV mode.
+ */
 public class Utils {
 
 	private static final byte DOUBLING_CONST = (byte) 0x87;

src/main/java/org/cryptomator/siv/package-info.java

@@ -1,8 +1,12 @@
 /**
  * Java implementation of RFC 5297 SIV Authenticated Encryption.
  * <p>
- * Use an instance of the {@link org.cryptomator.siv.SivEngine} class to
- * {@link org.cryptomator.siv.SivEngine#encrypt(byte[], byte[]...) encrypt} or
- * {@link org.cryptomator.siv.SivEngine#decrypt(byte[], byte[]...) decrypt} data.
+ * Two usage patterns are supported:
+ * <ul>
+ *   <li>Direct API: Use {@link org.cryptomator.siv.SivEngine} for encrypt/decrypt operations</li>
+ *   <li>JCE Provider: Register {@link org.cryptomator.siv.SivProvider} and use standard JCE APIs</li>
+ * </ul>
+ *
+ * @see <a href="https://tools.ietf.org/html/rfc5297">RFC 5297</a>
  */
 package org.cryptomator.siv;