Add property to skip bundled lib and improve docs.

* Enables skipping the bundled lib by setting the system property `com.amazon.corretto.crypto.provider.useExternalLib`. (Addresses corretto#140)
* Documents all currently defined system properties. (Addresses corretto#83)

CMakeLists.txt

@@ -688,6 +688,21 @@ add_custom_target(check-install-via-properties
 
     DEPENDS accp-jar tests-jar)
 
+add_custom_target(check-external-lib
+    # Unfortunately we do not have a way to know where the library is loaded from.
+    # So this test just proves that requesting the external lib does not break things
+    COMMAND ${TEST_JAVA_EXECUTABLE}
+        -cp $<TARGET_PROPERTY:accp-jar,JAR_FILE>:$<TARGET_PROPERTY:tests-jar,JAR_FILE>:${TEST_CLASSPATH}
+        -Djava.library.path=$<TARGET_FILE_DIR:amazonCorrettoCryptoProvider>
+        -Dcom.amazon.corretto.crypto.provider.useExternalLib=true
+        -Dcom.amazon.corretto.crypto.provider.inTestSuite=hunter2
+        -Dtest.data.dir=${TEST_DATA_DIR}
+        -Djava.security.properties=${ORIG_SRCROOT}/etc/amazon-corretto-crypto-provider.security
+        ${TEST_JAVA_ARGS}
+        com.amazon.corretto.crypto.provider.test.SecurityPropertyTester
+
+    DEPENDS accp-jar tests-jar)
+
 add_custom_target(check-install-via-properties-recursive
     COMMAND ${TEST_JAVA_EXECUTABLE}
         -cp $<TARGET_PROPERTY:accp-jar,JAR_FILE>:$<TARGET_PROPERTY:tests-jar,JAR_FILE>:${TEST_CLASSPATH}
@@ -714,7 +729,7 @@ add_custom_target(check-install-via-properties-with-debug
     DEPENDS accp-jar tests-jar)
 
 add_custom_target(check
-    DEPENDS check-recursive-init check-install-via-properties check-install-via-properties-with-debug check-junit check-junit-SecurityManager)
+    DEPENDS check-recursive-init check-install-via-properties check-install-via-properties-with-debug check-junit check-junit-SecurityManager check-external-lib)
 
 if(ENABLE_NATIVE_TEST_HOOKS)
     if (CMAKE_SYSTEM_PROCESSOR STREQUAL "x86_64")

README.md

@@ -120,7 +120,7 @@ For more information, please see [VERSIONING.rst](https://github.com/corretto/am
 ### Gradle
 Add the following to your `build.gradle` file. If you already have a
 `dependencies` block in your `build.gradle`, you can add the ACCP line to your
-existing block. 
+existing block.
 This will instruct it to use the most recent 1.x version of ACCP.
 For more information, please see [VERSIONING.rst](https://github.com/corretto/amazon-corretto-crypto-provider/blob/develop/VERSIONING.rst).
 
@@ -185,6 +185,33 @@ Add the following Java property to your programs command line: `-Djava.security.
 ### Modify the JVM settings
 Modify the `java.security` file provided by your JVM so that the highest priority provider is the Amazon Corretto Crypto Provider. Look at [amazon-corretto-crypto-provider.security](https://github.com/corretto/amazon-corretto-crypto-provider/blob/master/etc/amazon-corretto-crypto-provider.security) for an example of what this change will look like.
 
+### Other system properties
+ACCP can be configured via several system properties.
+None of these should be needed for standard deployments and we recommend not touching them.
+They are of most use to developers needing to test ACCP or experiment with benchmarking.
+These are all read early in the load process and may be cached so any changes to them made from within Java may not be respected.
+Thus, these should all be set on the JVM command line using `-D`.
+
+* `com.amazon.corretto.crypto.provider.extrachecks`
+   Adds exta cryptographic consistency checks which are not necessary on standard systems.
+   These checks may be computationally expensive and are not normally relevant.
+   See `ExtraCheck.java` for values and more information.
+   (Also accepts "ALL" as a value to enable all flags.)
+* `com.amazon.corretto.crypto.provider.debug`
+   Enables extra debugging behavior.
+   These behaviors may be computationally expensive, produce additional output, or otherwise change the behavior of ACCP.
+   No values here will lower the security of ACCP or cause it to give incorrect results.
+   See `DebugFlag.java` for values and more information.
+   (Also accepts "ALL" as a value to enable all flags.)
+* `com.amazon.corretto.crypto.provider.useExternalLib`
+   Takes in `true` or `false` (defaults to `false`).
+   If `true` then ACCP skips trying to load the native library bundled within its JAR and goes directly to the system library path.
+* `com.amazon.corretto.crypto.provider.janitor.stripes`
+   Takes *positive integer value* which is the requested minimum number of "stripes" used by the `Janitor` for dividing cleaning tasks (messes) among its workers.
+   (Current behavior is to default this value to 4 times the CPU core count and then round the value up to the nearest power of two.)
+   See `Janitor.java` for for more information.
+
+
 ### Verification (Optional)
 If you want to check to verify that ACCP is properly working on your system, you can do any of the following:
 1. Verify that the highest priority provider actually is ACCP:

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

@@ -122,13 +122,19 @@ static String getProperty(String propertyName, String def) {
                 FileSystems.getDefault();
 
                 // First, try to find the library in our own jar
+                final boolean useExternalLib = Boolean.valueOf(getProperty("useExternalLib", "false"));
+                Exception loadingException = null;
+
                 String libraryName = System.mapLibraryName(LIBRARY_NAME);
-                if (libraryName != null) {
+                if (useExternalLib) {
+                    loadingException = new RuntimeCryptoException("Skipping bundled library due to system property");
+                } else if (libraryName != null) {
                     int index = libraryName.lastIndexOf('.');
                     final String prefix = libraryName.substring(0, index);
                     final String suffix = libraryName.substring(index, libraryName.length());
 
                     final Path libPath = createTmpFile(prefix, suffix);
+
                     try (final InputStream is = Loader.class.getResourceAsStream(libraryName);
                          final OutputStream os = Files.newOutputStream(libPath, StandardOpenOption.CREATE,
                                  StandardOpenOption.WRITE, StandardOpenOption.TRUNCATE_EXISTING)) {
@@ -141,19 +147,27 @@ static String getProperty(String propertyName, String def) {
                         os.flush();
                         System.load(libPath.toAbsolutePath().toString());
                         return true;
+                    } catch (final Exception realException) {
+                        loadingException = realException;
                     } catch (final Throwable realError) {
-                        // We failed to load the library from our JAR but don't know why.
-                        // Try to load it directly off of the system path.
-                        try {
-                            System.loadLibrary(LIBRARY_NAME);
-                            return true;
-                        } catch (final Throwable suppressedError) {
-                            realError.addSuppressed(suppressedError);
-                            throw realError;
-                        }
+                        loadingException = new RuntimeCryptoException("Unable to load native library", realError);
                     } finally {
                         Files.delete(libPath);
                     }
+                } else {
+                    loadingException = new RuntimeCryptoException("Skipping bundled library null mapped name");
+                }
+
+                if (loadingException != null) {
+                    // We failed to load the library from our JAR but don't know why.
+                    // Try to load it directly off of the system path.
+                    try {
+                        System.loadLibrary(LIBRARY_NAME);
+                        return true;
+                    } catch (final Throwable suppressedError) {
+                        loadingException.addSuppressed(suppressedError);
+                        throw loadingException;
+                    }
                 }
 
                 return false;