Uploaded image for project: 'C# Driver'
  1. C# Driver
  2. CSHARP-4944

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.
    • Needed
    • Hide

      1. What would you like to communicate to the user about this feature?
      I want the user to know about libmongocrypt and that linux users should use the environment variable LIBMONGOCRYPT_PATH to specify the path to a manually installed libmongocrypt library.

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

      3. Which versions of the driver/connector does this apply to?
      This would most likely target the next release; 2.26

      We would like to have a section under our C# CSFLE docs talking about libmongocrypt as below; I copied the Ruby docs for this and adapted a bit for our needs.

      Libmongocrypt

      Libmongocrypt is a C library utilized by the driver for client-side encryption. To enable client-side encryption, you must install the libmongocrypt library on the machine running your application. The driver includes the MongoDB.libmongocrypt NuGet package, which bundles libmongocrypt libraries for various operating systems. However, on Linux systems, the bundled libmongocrypt library does not use the system’s native encryption providers due to OpenSSL versioning issues. For high-performance applications on Linux, it is recommended to manually install the libmongocrypt library and specify its path to the driver using the LIBMONGOCRYPT_PATH environment variable. This is only recommended for users on linux systems.

      You can download a pre-built binary distribution of libmongocrypt and manually place the required shared object on your computer, as follows:

      • Download a tarball of all libmongocrypt variations here.
      • Extract the file you downloaded. You will see a list of directories, each corresponding to an operating system. Find the directory that matches your operating system and open it.
      • Inside that folder, open either the lib or lib64 folder, you will find the libmongocrypt.so or libmongocrypt.dylib or libmongocrypt.dll file, depending on your OS.
      • Move that file to wherever you want to keep it on your machine. You may delete the other files included in the tarball.

      To build the binary from source:

      Once you have the libmongocrypt binary on your machine, specify the path to the binary using the LIBMONGOCRYPT_PATH environment variable. It is recommended that you add this variable to your rc files.
      For example:
      export LIBMONGOCRYPT_PATH=/absolute/path/to/your/libmongocrypt.so

      Show
      1. What would you like to communicate to the user about this feature? I want the user to know about libmongocrypt and that linux users should use the environment variable LIBMONGOCRYPT_PATH to specify the path to a manually installed libmongocrypt library. 2. Would you like the user to see examples of the syntax and/or executable code and its output? no code example needed. 3. Which versions of the driver/connector does this apply to? This would most likely target the next release; 2.26 We would like to have a section under our C# CSFLE docs talking about libmongocrypt as below; I copied the  Ruby docs  for this and adapted a bit for our needs. Libmongocrypt Libmongocrypt is a C library utilized by the driver for client-side encryption. To enable client-side encryption, you must install the libmongocrypt library on the machine running your application. The driver includes the MongoDB.libmongocrypt NuGet package, which bundles libmongocrypt libraries for various operating systems. However, on Linux systems, the bundled libmongocrypt library does not use the system’s native encryption providers due to OpenSSL versioning issues. For high-performance applications on Linux, it is recommended to manually install the libmongocrypt library and specify its path to the driver using the LIBMONGOCRYPT_PATH environment variable. This is only recommended for users on linux systems. You can download a pre-built binary distribution of libmongocrypt and manually place the required shared object on your computer, as follows: Download a tarball of all libmongocrypt variations  here . Extract the file you downloaded. You will see a list of directories, each corresponding to an operating system. Find the directory that matches your operating system and open it. Inside that folder, open either the lib or lib64 folder, you will find the libmongocrypt.so or libmongocrypt.dylib or libmongocrypt.dll file, depending on your OS. Move that file to wherever you want to keep it on your machine. You may delete the other files included in the tarball. To build the binary from source: Follow the instructions in the README in the  libmongocrypt GitHub repo . Once you have the libmongocrypt binary on your machine, specify the path to the binary using the LIBMONGOCRYPT_PATH environment variable. It is recommended that you add this variable to your rc files. For example: export LIBMONGOCRYPT_PATH=/absolute/path/to/your/libmongocrypt.so

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

            Assignee:
            adelin.mbidaowona@mongodb.com Adelin Mbida Owona
            Reporter:
            dbeng-pm-bot PM Bot
            Votes:
            0 Vote for this issue
            Watchers:
            2 Start watching this issue

              Created:
              Updated:
              Resolved: