INTPYTHON-527 Add Queryable Encryption support

[aclark4life]

Previous attempts and additional context here:

• INTPYTHON-527 Add Queryable Encryption config #318

  • Branched from transaction support and includes only helpers

• INTPYTHON-527 Add queryable encryption support #319

  • In which this bug in libmongocrypt was discovered
  • A fix for that bug in PyMongo is being discussed here.

• INTPYTHON-527 Add Queryable Encryption support #323

  • Before I understood that the shared lib for mongocrypt was included in the pymongocrypt wheel.

• Add test for "Encrypted fields found" error (ensure this exception still happens)

• Add check for model schema not matching encrypted fields

• Document key_vault_namespace must be encrypted db

• Document that fields within EmbeddedModelArrayField can't be encrypted

• Document workflow:

  • Develop and test local
  • Deploy and run migrate
  • Run showencryptedfieldsmap and set encrypted_fields_map in auto_encryption_opts
  • Deploy again

[addaleax]

Can we be clear about the fact that this is a bug workaround and not expected behavior?

[timgraham]

Yes, I think it should say something like, "If you encounter Pymongocrypt.errors.MongoCryptError: An existing crypt_shared library is loaded by the application at [/path/to/mongo_crypt_v1.so], but the current call to mongocrypt_init() failed to find that same library.", ....

Did you find the root cause so we can at least a link to that issue in a comment here?

[aclark4life]

I think the root cause is that the error message is confusing and I don't think setting environment variables is a bug workaround … rather, it's quite common when the shared library is not in the location the OS checks by default. In these cases, my guess is that the failure to find the library is because it's not found, not that there is a 2nd conflicting library, so I think the pymongocrypt error message could be improved to help with this.

[timgraham]

I'm not sure how all the parts fit together, but as far as I tested, the error doesn't happen with MongoDB 7.0 so it seems plausible it could be a server regression.

[aclark4life]

@timgraham Can you reproduce with 7?

[timgraham]

The problems seems specific with version 8.0.x and later of the shared library.

No issue with MongoDB 7.0.25 + mongo_crypt_shared_v1-linux-x86_64-enterprise-ubuntu2204-7.0.25 (I'm the ubuntu2204 shared library on Ubuntu 24.04 because one isn't available for 2404).

With MongoDB 7.0.25 and 8.0.15 and mongo_crypt_shared_v1-linux-x86_64-enterprise-ubuntu2404-8.0.15: "An existing crypt_shared library is loaded... " error. [fixed by specifying LD_LIBRARY_PATH]

With MongoDB 8.0.15 + mongo_crypt_shared_v1-linux-x86_64-enterprise-ubuntu2204-7.0.25, the application starts and runs, failing later (as expected) because of backward incompatible changes to queries: "csfle "analyze_query" failed: Enumeration value 'range' for field 'create.encryptedFields.fields.queryType' is not a valid value."

[aclark4life]

With MongoDB 8.0.15 + mongo_crypt_shared_v1-linux-x86_64-enterprise-ubuntu2204-7.0.25, the application starts and runs, failing later (as expected) because of backward incompatible changes to queries: "csfle "analyze_query" failed: Enumeration value 'range' for field 'create.encryptedFields.fields.queryType' is not a valid value."

Ah OK so the server should catch the missing LD_LIBRARY_PATH and say "An existing crypt_shared library is loaded... " rather than proceeding as if the library was found. Additionally the error appears nonsensical since range is correct for 8.0.

[timgraham]

No, I believe the shared library 7 loads fine, even with server 8. The error message is because shared library 7 incompatible with server 8 because shared library 7 assumes it's used with server 7 and has enumeration values like "rangePreview" built-in.