<!---
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You under the Apache License, Version 2.0
 (the "License"); you may not use this file except in compliance with
 the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

 Unless required by applicable law or agreed to in writing, software
 distributed under the License is distributed on an "AS IS" BASIS,
 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 See the License for the specific language governing permissions and
 limitations under the License.
-->

Notes on Library names
======================

If the default SSL Cryptography library is not suitable for use, it may be
necessary to override the path or name.

The way to do this depends on the OS.

On Linux/macOS, each library version is generally installed in a separate directory.
The following properties can be used to override the JNI and JNA locations respectively:
jni.library.path
jna.library.path

On Windows, multiple library versions may be installed in the system directory under a different name.
The following properties can be used to override the JNI and JNA file names respectively:
commons.crypto.OpenSslNativeJni
commons.crypto.OpenSslNativeJna

For testing with Maven, these properties can be defined on the command-line:

Linux/macOs:
$ mvn ... -Djni.library.path=/usr/local/lib -Djna.library.path=/usr/local/lib ...

Windows:

> mvn ... -D"commons.crypto.OpenSslNativeJni=libcrypto-1_1-x64" -D"commons.crypto.OpenSslNativeJna=libcrypto-1_1-x64" ...

Library override is needed on macOS
-----------------------------------
Attempts to load the default library on macOS cause the application to crash with a message of the form:
".../bin/java is loading libcrypto in an unsafe way"

To fix this, he properties jni.library.path and/or jna.library.path need to be set to the appropriate path,
for example /usr/local/lib.

An alternative is to ensure that there is a copy of the library in the application launch directory.
This can be a soft link to the actual library. This only works for unrestricted processes.

It does not appear to be possible to use any of the DYLIB_ environment variables.
These are removed as part of System Integrity Protection, so are not seen by the application and dlopen().