Uploaded image for project: 'Java Driver'
  1. Java Driver
  2. JAVA-5306

Enable use of native crypto in libmongocrypt bindings

XMLWordPrintableJSON

    • Hide

      DRIVERS-2718:
      Summary of necessary driver changes

      Package the crypto-enabled libmongocrypt on platforms where it is safe to do so: Mac and Windows. For Linux, continue to package the crypto-disabled (nocrypto) builds due to the issues with OpenSSL versioning (see MONGOCRYPT-112).

      Check if the loaded libmongocrypt supports native crypto by calling mongocrypt_is_crypto_available. Only register crypto callbacks if it returns false.

      Document that on Linux, high-performance use cases should install libmongocrypt on the system. If possible, ensure this install takes precedence over the packaged crypto-disabled libmongocrypt.

      Update (2024-04-30): Drivers adding an environment variable to specify a path to libmongocrypt are recommended to use the name LIBMONGOCRYPT_PATH (consistent with Ruby driver).

      Context for other referenced/linked tickets

      mongocrypt_is_crypto_available is added in MONGOCRYPT-616. Until it is released, libmongocrypt binaries can be downloaded from the upload-all task for the commit.

      I expect this work only applies to drivers that implement the crypto hooks (i.e. calling mongocrypt_setopt_crypto_hooks and friends). From this survey, this appears to be: C#, Java, Node.js, Python, Ruby.

      Show
      DRIVERS-2718 : Summary of necessary driver changes Package the crypto-enabled libmongocrypt on platforms where it is safe to do so: Mac and Windows. For Linux, continue to package the crypto-disabled (nocrypto) builds due to the issues with OpenSSL versioning (see MONGOCRYPT-112 ). Check if the loaded libmongocrypt supports native crypto by calling mongocrypt_is_crypto_available . Only register crypto callbacks if it returns false. Document that on Linux, high-performance use cases should install libmongocrypt on the system. If possible, ensure this install takes precedence over the packaged crypto-disabled libmongocrypt. Update (2024-04-30): Drivers adding an environment variable to specify a path to libmongocrypt are recommended to use the name LIBMONGOCRYPT_PATH (consistent with Ruby driver). Context for other referenced/linked tickets mongocrypt_is_crypto_available is added in MONGOCRYPT-616 . Until it is released, libmongocrypt binaries can be downloaded from the upload-all task for the commit . I expect this work only applies to drivers that implement the crypto hooks (i.e. calling mongocrypt_setopt_crypto_hooks and friends). From this survey , this appears to be: C#, Java, Node.js, Python, Ruby.
    • Fully Compatible
    • Needed
    • Hide

      1. What would you like to communicate to the user about this feature?

      Performance has improved substantially due to use of native cryptography on all supported platforms.

      For Windows and Mac, no action needs to be taken besides upgrading to the recommended mongodb-crypt release. But on Linux, we recommend installing libmongocrypt.so directly on the file system, instead of relying on the one that is bundled within the mongodb-crypt jar file. This is because the bundled shared library does not link with OpenSSL due to the potential for OpenSSL binary incompatibilities.

      The shared library loading is handled by JNA. The rules for library loading search path order are documented by the NativeLibrary class's Javadoc: https://java-native-access.github.io/jna/5.14.0/javadoc/com/sun/jna/NativeLibrary.html

      We should link to instructions on how to install the libmongocrypt shared library on the local file system for Linux: https://www.mongodb.com/docs/manual/core/csfle/reference/libmongocrypt/#linux-installation

      We should also point out that if you use a package manager to install libmongocrypt, JNA will find it there without any further configuration. And at worst you should be able to specify the search path with LD_LIBRARY_PATH.

      2. Would you like the user to see examples of the syntax and/or executable code and its output?

      No.

      3. Which versions of the driver/connector does this apply to?

      JVM drivers 5.2.0, which will have an optional dependency on either mongodb-crypt 1.10.0 or 1.11.0.

      Show
      1. What would you like to communicate to the user about this feature? Performance has improved substantially due to use of native cryptography on all supported platforms. For Windows and Mac, no action needs to be taken besides upgrading to the recommended mongodb-crypt release. But on Linux, we recommend installing libmongocrypt.so directly on the file system, instead of relying on the one that is bundled within the mongodb-crypt jar file. This is because the bundled shared library does not link with OpenSSL due to the potential for OpenSSL binary incompatibilities. The shared library loading is handled by JNA . The rules for library loading search path order are documented by the NativeLibrary class's Javadoc: https://java-native-access.github.io/jna/5.14.0/javadoc/com/sun/jna/NativeLibrary.html We should link to instructions on how to install the libmongocrypt shared library on the local file system for Linux: https://www.mongodb.com/docs/manual/core/csfle/reference/libmongocrypt/#linux-installation We should also point out that if you use a package manager to install libmongocrypt, JNA will find it there without any further configuration. And at worst you should be able to specify the search path with LD_LIBRARY_PATH. 2. Would you like the user to see examples of the syntax and/or executable code and its output? No. 3. Which versions of the driver/connector does this apply to? JVM drivers 5.2.0, which will have an optional dependency on either mongodb-crypt 1.10.0 or 1.11.0.

      This ticket was split from DRIVERS-2718, please see that ticket for a detailed description.

            Assignee:
            jeff.yemin@mongodb.com Jeffrey Yemin
            Reporter:
            dbeng-pm-bot PM Bot
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: