Improve documentation (#151)

* Improve documentation

* Language tweaks

DEVELOPMENT-GUIDE.md

@@ -38,11 +38,11 @@ In decreasing order of importance:
     2. Test to prove correctness. (While we must always do this, it is even more critical here.)
     3. Comment to explain exactly what is intended and, when appropriate, why a particular technique was chosen.
     Examples: ([ConstantTime](https://github.com/corretto/amazon-corretto-crypto-provider/blob/develop/src/com/amazon/corretto/crypto/provider/ConstantTime.java) and its [tests](https://github.com/corretto/amazon-corretto-crypto-provider/blob/develop/tst/com/amazon/corretto/crypto/provider/test/ConstantTimeTests.java), [Janitor](https://github.com/corretto/amazon-corretto-crypto-provider/blob/develop/src/com/amazon/corretto/crypto/provider/Janitor.java) and its [tests](https://github.com/corretto/amazon-corretto-crypto-provider/blob/develop/tst/com/amazon/corretto/crypto/provider/test/JanitorTest.java))
-7. Old code *must* be updated to current best practices.
+7. New best practices *must* be applied uniformly to the codebase.
     As we extend and improve ACCP, we will create new tools and frameworks to make our code better (cleaner, safer, easier to read, etc.).
+    When we do this, we must  go back through the rest of the ACCP codebase to make the same improvements everywhere.
     Historical examples of this include `java_buffer`, `InputBuffer`, `NativeResource`, `raii_env` and others.
-    Even though old code will continue to work, we must go back and bring old code up to current standards and techniques.
-    This means that just because existing code was acceptable when it was written does not mean it is acceptable now.
+    Just because existing code was acceptable when it was written does not mean it is acceptable now.
     Doing this allows us to continually raise the bar on code quality across the project and combat [bit rot](https://en.wikipedia.org/wiki/Software_rot).
 
 

DIFFERENCES.md

@@ -42,9 +42,9 @@ This construction is safe for all known JCE providers and is expected to remain
 For more information, see the [changelog](./CHANGELOG.md) notes for version 1.5.0.
 
 ## Cipher.getOutputSize() for AES-GCM
-ACCP might overestimate the amount of space needed when encrypted with `AES/GCM/NoPadding`.
+ACCP might overestimate the amount of space needed when encrypted with `AES/GCM/NoPadding` on versions prior to 1.6.0.
 While this is compliant with the JCE (which [permits overestimation](https://docs.oracle.com/javase/8/docs/api/javax/crypto/Cipher.html#getOutputSize-int-)) it has caused confusion for some developers.
-We are tracking this as [issue #135](https://github.com/corretto/amazon-corretto-crypto-provider/issues/135) and will improve this behavior.
+
 
 ## SecureRandom is never deterministic
 Some implementation of `SecureRandom` (such as `SHA1PRNG`, provided by the default OpenJDK cryptographic providers) can operate deterministically if `SecureRandom.setSeed(byte[])` is called prior to any other methods.

README.md

@@ -8,7 +8,12 @@ Currently algorithms are primarily backed by OpenSSL's implementations (1.1.1j a
 
 
 ## Build Status
-Please be aware that "Overkill" tests are known to be flakey
+Please be aware that both "Overkill" and "Dieharder" tests are known to be flakey.
+Both of these tests are flakey because they include entropy generation tests
+(specificaly, the [Dieharder tests](http://webhome.phy.duke.edu/~rgb/General/dieharder.php)).
+Entropy tests are unavoidably flakey because there is always a possibility that a high-quality
+random number generator will output data which looks non-random.
+(For example, even a fair coin will come up heads ten times in a row about one in a thousand trials.)
 
 | Build Name | master branch | develop branch |
 | ---------- | ------------- | -------------- |

src/com/amazon/corretto/crypto/provider/Loader.java

@@ -27,6 +27,22 @@
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+/**
+ * This class owns <em>all</em> logic necessary for loading the native library.
+ * For this reason it must not depend on any other classes from this project (other than Janitor).
+ *
+ * The rough logic flow is as follows:
+ * <ol>
+ * <li>Read library version from embedded properties file
+ * <li>Use some entropy from {@code /dev/urandom} to create a random temporary filename
+ * <li>Copy the shared object from within our own JAR to the temporary file
+ * <li>Load the shared object as a library from the temporary file
+ * <li>Delete the temporary file
+ * <li>If loading the library from above fails, try to load the library from our standard library path
+ * <li>If we have successfully loaded a library, ask it for the version it was compiled with
+ * <li>If the versions match, we mark that we loaded successful, else, we record the error.
+ * </ol>
+ */
 final class Loader {
     private static final String PROPERTY_BASE = "com.amazon.corretto.crypto.provider.";
     private static final String LIBRARY_NAME = "amazonCorrettoCryptoProvider";