Giter Club home page Giter Club logo

libmongocrypt's Introduction

libmongocrypt

The companion C library for client side encryption in drivers.

Documentation

See The Integration Guide to integrate with your driver.

See mongocrypt.h for the public API reference. The documentation can be rendered into HTML with doxygen. Run doxygen ./doc/Doxygen, then open ./doc/html/index.html.

Building libmongocrypt

First build the following dependencies:

  1. The BSON library (part of the C driver), consisting of libbson. Build it from source.

    wget https://github.com/mongodb/mongo-c-driver/releases/download/1.14.0/mongo-c-driver-1.14.0.tar.gz
    tar xzf mongo-c-driver-1.14.0.tar.gz
    cd mongo-c-driver-1.14.0
    mkdir cmake-build && cd cmake-build
    cmake -DENABLE_MONGOC=OFF -DCMAKE_INSTALL_PATH="/path/to/bson-install" -DCMAKE_C_FLAGS="-fPIC" ../
    make -j8 install
    

    This installs the library and includes into /path/to/bson-install. The prefix can be omitted if you prefer installing in /usr/local.

  2. OpenSSL (if on Linux).

Then build libmongocrypt:

git clone [email protected]:10gen/libmongocrypt.git
cd libmongocrypt
mkdir cmake-build && cd cmake-build
cmake -DCMAKE_C_FLAGS="-fPIC" -DCMAKE_PREFIX_PATH="/path/to/bson-install" ../
make

This builds libmongocrypt.dylib and test-libmongocrypt, in the cmake-build directory. Note, the CMAKE_PREFIX_PATH must include the path to the BSON library installation directory if it was not the defaults. Also note that if your project will also dynamically link to the BSON library, you will need to add -DENABLE_SHARED_BSON=ON to the cmake command line.

Testing

test-mongocrypt mocks all I/O with files stored in the test/data and test/example directories. Run test-mongocrypt from the source directory:

cd libmongocrypt
./cmake-build/test-mongocrypt

libmongocrypt is continuously built and published on evergreen. Submit patch builds to this evergreen project when making changes to test on supported platforms. The latest tarball containing libmongocrypt built on all supported variants is (published here)[https://s3.amazonaws.com/mciuploads/libmongocrypt/all/master/latest/libmongocrypt-all.tar.gz].

Troubleshooting

If OpenSSL is installed in a non-default directory, pass -DOPENSSL_ROOT_DIR=/path/to/openssl to the cmake command for libmongocrypt.

If there are errors with cmake configuration, send the set of steps you performed to the maintainers of this project.

If there are compilation or linker errors, run make again, setting VERBOSE=1 in the environment or on the command line (which shows exact compile and link commands), and send the output to the maintainers of this project.

Design Principles

The design of libmongocrypt adheres to these principles.

Easy to integrate

The main reason behind creating a C library is to make it easier for drivers to support FLE. Some consequences of this principle: the API is minimal, structs are opaque, and global initialization is lazy.

Lightweight

We decided against the "have libmongocrypt do everything" approach because it complicated integration, especially with async drivers. Because of this we decided no I/O occurs in libmongocrypt.

Narrowly scoped

The first version of FLE is to get signal. If FLE becomes popular, further improvements will be made (removing mongocryptd process, support for more queries, better performance). libmongocrypt takes the same approach. Making it blazing fast and completely future-proof is not a high priority.

Releasing

To release create a new git tag, and update MONGOCRYPT_VERSION in mongocrypt.h.

libmongocrypt's People

Contributors

kevinalbs avatar samantharitter avatar rcsanchez97 avatar jyemin avatar markbenvenuto avatar shaneharvey avatar daprahamian avatar rozza avatar mbroadst avatar bazile-clyde avatar vincentkam avatar behackett avatar

Stargazers

VonVictor V. Rosenchild avatar

Watchers

James Cloos avatar  avatar

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.