Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve documentation #151

Merged
merged 2 commits into from
Mar 18, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions DEVELOPMENT-GUIDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).


Expand Down
4 changes: 2 additions & 2 deletions DIFFERENCES.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
7 changes: 6 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
| ---------- | ------------- | -------------- |
Expand Down
16 changes: 16 additions & 0 deletions src/com/amazon/corretto/crypto/provider/Loader.java
Original file line number Diff line number Diff line change
Expand Up @@ -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";
Expand Down