Javadoc a little

rctcwyvrn · May 14, 2020 · 8f22dd1 · 8f22dd1
1 parent f1d8e08
commit 8f22dd1
Showing 1 changed file with 94 additions and 45 deletions.
diff --git a/src/com/github/rctcwyvrn/blake3/Blake3.java b/src/com/github/rctcwyvrn/blake3/Blake3.java
@@ -4,6 +4,8 @@
 import java.io.IOException;
 import java.nio.ByteBuffer;
 import java.nio.ByteOrder;
+import java.nio.charset.Charset;
+import java.nio.charset.StandardCharsets;
 import java.nio.file.Files;
 import java.nio.file.Paths;
 import java.util.Arrays;
@@ -16,6 +18,7 @@
 public class Blake3 {
     private static final char[] HEX_ARRAY = "0123456789abcdef".toCharArray();
 
+    private static final int DEFAULT_HASH_LEN = 32;
     private static final int OUT_LEN = 32;
     private static final int KEY_LEN = 32;
     private static final int BLOCK_LEN = 64;
@@ -246,65 +249,52 @@ private Node createNode(){
     private byte cvStackLen = 0;
     private int flags;
 
-    public Blake3(){
-        this(IV,0);
-    }
-
-    public Blake3(int[] key, int flags){
+    private void initialize(int[] key, int flags){
         this.chunkState = new ChunkState(key, 0, flags);
         this.key = key;
         this.flags = flags;
     }
 
-    public Blake3(byte[] key){
-        this(wordsFromLEBytes(key), KEYED_HASH);
-    }
-
-    public Blake3(String context){
-        Blake3 contextHasher = new Blake3(IV, DERIVE_KEY_CONTEXT);
-    }
-
-    private void pushStack(int[] cv){
-        this.cvStack[this.cvStackLen] = cv;
-        cvStackLen+=1;
-    }
-
-    private int[] popStack(){
-        this.cvStackLen-=1;
-        return cvStack[cvStackLen];
-    }
-
-    // Combines the chaining values of two children to create the parent node
-    private static Node parentNode(int[] leftChildCV, int[] rightChildCV, int[] key, int flags){
-        int[] blockWords = new int[16];
-        int i = 0;
-        for(int x: leftChildCV){
-            blockWords[i] = x;
-            i+=1;
-        }
-        for(int x: rightChildCV){
-            blockWords[i] = x;
-            i+=1;
-        }
-        return new Node(key, blockWords, 0, BLOCK_LEN, PARENT | flags);
+    /**
+     * Construct a default blake3 hasher
+     */
+    public Blake3(){
+        initialize(IV,0);
     }
 
-    private static int[] parentCV(int[] leftChildCV, int[] rightChildCV, int[] key, int flags){
-        return parentNode(leftChildCV, rightChildCV, key, flags).chainingValue();
+    /**
+     * Construct a new blake3 keyed hasher
+     * @param key The key
+     */
+    public Blake3(byte[] key){
+        initialize(wordsFromLEBytes(key), KEYED_HASH);
     }
 
-    private void addChunkChainingValue(int[] newCV, long totalChunks){
-        while((totalChunks & 1) == 0){
-            newCV = parentCV(popStack(), newCV, key, flags);
-            totalChunks >>=1;
-        }
-        pushStack(newCV);
+    /**
+     * Construct a new blake3 key derivation hasher
+     * @param context Context string used to derive keys. The context string should be hardcoded, globally unique, and application-specific
+     */
+    public Blake3(String context){
+        Blake3 contextHasher = new Blake3();
+        contextHasher.initialize(IV, DERIVE_KEY_CONTEXT);
+        contextHasher.update(context.getBytes(StandardCharsets.UTF_8));
+        int[] contextKey = wordsFromLEBytes(contextHasher.digest());
+        initialize(contextKey, DERIVE_KEY_MATERIAL);
     }
 
+    /**
+     * Append the byte contents of the file to the hash tree
+     * @param file File to be added
+     * @throws IOException If the file does not exist
+     */
     public void update(File file) throws IOException {
         update(Files.readAllBytes(file.toPath()));
     }
 
+    /**
+     * Appends new data to the hash tree
+     * @param input Data to be added
+     */
     public void update(byte[] input){
         while(input.length != 0) {
 
@@ -323,6 +313,11 @@ public void update(byte[] input){
         }
     }
 
+    /**
+     * Generate the blake3 hash for the current tree with the given byte length
+     * @param hashLen The number of bytes of hash to return
+     * @return The byte array representing the hash
+     */
     public byte[] digest(int hashLen){
         Node node = this.chunkState.createNode();
         int parentNodesRemaining = cvStackLen;
@@ -338,12 +333,66 @@ public byte[] digest(int hashLen){
         return node.rootOutputBytes(hashLen);
     }
 
+    /**
+     * Generate the blake3 hash for the current tree with the default byte length of 32
+     * @return The byte array representing the hash
+     */
+    public byte[] digest(){
+        return digest(DEFAULT_HASH_LEN);
+    }
+
+    /**
+     * Generate the blake3 hash for the current tree with the given byte length
+     * @param hashLen The number of bytes of hash to return
+     * @return The hex string representing the hash
+     */
     public String hexdigest(int hashLen){
         return bytesToHex(digest(hashLen));
     }
 
+    /**
+     * Generate the blake3 hash for the current tree with the default byte length of 32
+     * @return The hex string representing the hash
+     */
     public String hexdigest(){
-        return hexdigest(32);
+        return hexdigest(DEFAULT_HASH_LEN);
+    }
+
+    private void pushStack(int[] cv){
+        this.cvStack[this.cvStackLen] = cv;
+        cvStackLen+=1;
+    }
+
+    private int[] popStack(){
+        this.cvStackLen-=1;
+        return cvStack[cvStackLen];
+    }
+
+    // Combines the chaining values of two children to create the parent node
+    private static Node parentNode(int[] leftChildCV, int[] rightChildCV, int[] key, int flags){
+        int[] blockWords = new int[16];
+        int i = 0;
+        for(int x: leftChildCV){
+            blockWords[i] = x;
+            i+=1;
+        }
+        for(int x: rightChildCV){
+            blockWords[i] = x;
+            i+=1;
+        }
+        return new Node(key, blockWords, 0, BLOCK_LEN, PARENT | flags);
+    }
+
+    private static int[] parentCV(int[] leftChildCV, int[] rightChildCV, int[] key, int flags){
+        return parentNode(leftChildCV, rightChildCV, key, flags).chainingValue();
+    }
+
+    private void addChunkChainingValue(int[] newCV, long totalChunks){
+        while((totalChunks & 1) == 0){
+            newCV = parentCV(popStack(), newCV, key, flags);
+            totalChunks >>=1;
+        }
+        pushStack(newCV);
     }
 
     private static String bytesToHex(byte[] bytes) {