Add JavaDoc

src/main/java/dslab/client/MessageClient.java

@@ -182,6 +182,12 @@ public class MessageClient implements IMessageClient, Runnable {
         return new String(aesDecryptCipher.doFinal(cipherText));
     }
 
+    /**
+     * Takes a server's AES encrypted challenge and compares it against the one that was sent initially.
+     *
+     * @param response The server's encoded and encrypted client challenge.
+     * @throws FailedVerificationException Thrown if the challenges do not match.
+     */
     private void verifyChallenge(String response) throws FailedVerificationException {
         // Decrypt to base64 encoded byte array
         String plainText;
@@ -204,6 +210,11 @@ public class MessageClient implements IMessageClient, Runnable {
                     " does not match sent clientChallenge " + new String(this.challenge));
     }
 
+    /**
+     * Generates a new random 256 bit AES secret key.
+     *
+     * @return Either shuts down on error or returns the generated key.
+     */
     private SecretKeySpec generateSecretKey() {
         try {
             KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
@@ -217,6 +228,11 @@ public class MessageClient implements IMessageClient, Runnable {
         return null;
     }
 
+    /**
+     * Generates a new random 128 bit initialization vector
+     *
+     * @return The generated IV.
+     */
     private IvParameterSpec generateIv() {
         // Size of IV corresponds to AES block size (=128bits=16bytes)
         byte[] iv = new byte[16];
@@ -224,6 +240,12 @@ public class MessageClient implements IMessageClient, Runnable {
         return new IvParameterSpec(iv);
     }
 
+    /**
+     * Sets the global encryption and decryption ciphers (aesEncryptCipher, aesDecryptCipher).
+     *
+     * @param secretKey A previously generated 256 bit AES secret key.
+     * @param iv        A previously generated 128 bit AES initialization vector.
+     */
     private void setAesCiphers(SecretKeySpec secretKey, IvParameterSpec iv) {
         try {
             this.aesEncryptCipher = Cipher.getInstance("AES/CTR/NoPadding");
@@ -244,7 +266,12 @@ public class MessageClient implements IMessageClient, Runnable {
         }
     }
 
-    private byte[] generateChallenge(PublicKey serverPublicKey) {
+    /**
+     * Generates a new random 256 bit challenge.
+     *
+     * @return The generated challenge.
+     */
+    private byte[] generateChallenge() {
         SecureRandom secureRandom = new SecureRandom();
         // Generate new random 32 byte challenge
         this.challenge = new byte[32];
@@ -252,9 +279,19 @@ public class MessageClient implements IMessageClient, Runnable {
         return this.challenge;
     }
 
+    /**
+     * Generates the full challenge message to be sent to the server.
+     *
+     * The challenge message is of the format:
+     * ok <client-challenge> <secret-key> <iv>
+     * The parameters are base64 encoded individually, then they are concatenated:
+     * ok <base64-client-challenge> <base64-secret-key> <base64-iv>
+     * The whole string is then AES encrypted and the result base64 encoded again.
+     * @return A base64 encoded full client challenge.
+     */
     private String generateChallengeMessage(PublicKey serverPublicKey) {
         SecureRandom secureRandom = new SecureRandom();
-        byte[] clearTextChallenge = generateChallenge(serverPublicKey);
+        byte[] clearTextChallenge = generateChallenge();
         SecretKeySpec secretKeySpec = generateSecretKey();
         assert secretKeySpec != null;
         IvParameterSpec iv = generateIv();