Mundane is a Rust cryptography library backed by BoringSSL that is difficult to misuse, ergonomic, and performant (in that order).

Last update: Jun 15, 2022

Mundane

Mundane is a Rust cryptography library backed by BoringSSL that is difficult to misuse, ergonomic, and performant (in that order).

Issues and Contributions

We use GitHub issues for issue tracking, and Gerrit for code reviews. See CONTRIBUTING.md for more details.

Dependencies

Rust 1.36 or newer is required.

Mundane vendors a copy of the BoringSSL source, so BoringSSL does not need to be installed locally in order to build. However, the BoringSSL build system has the following dependencies:

  • CMake 2.8.11 or later
  • Perl 5.6.1 or later. See BoringSSL's build instructions for what to do if CMake fails to find Perl on your system.
  • Either Make or Ninja. Ninja is preferable, as it makes compilation significantly faster; if both are present, Ninja will be used. On Windows, Ninja is required.
  • A C++ compiler
  • Go 1.10 or later
  • To build the x86 and x86_64 assembly, your assembler must support AVX2 instructions and MOVBE. If using GNU binutils, you must have 2.22 or later.

In order to avoid errors at link time due to conflicting symbols, we build BoringSSL with a custom prefix for all of its symbols which is based on the name and version of this crate. That way, even if multiple different versions of Mundane are present in the same dependency graph, none of the symbols from one version's BoringSSL will conflict with the symbols from another version's BoringSSL.

Supported platforms

Mundane supports being built on and for Linux and Mac. Windows support is under development. Cross-compilation is not supported.

License

Everything outside of the boringssl/boringssl directory is licensed under an MIT license which can be found in the LICENSE file. Everything in the boringssl/boringssl directory is licensed with a license that can be found in the boringssl/boringssl/LICENSE file.

Disclaimer: Mundane is not an officially supported Google product.

GitHub

https://github.com/google/mundane
Comments
  • 1. Add BoringSSL exponent and modulus getters

    Background

    We are planning on using mundane for OpenTitan image signing host tooling. One of the things that would be helpful to us is being able to retrieve a key public exponent and modulus from an RSA key.

    It seems that mundane doesn't directly expose these fields, so additional BoringSSL API should be exposed: RSA_get0_n and RSA_get0_e

    These functions could potentially be useful for other users of mundane.

    Questions

    1. Would the upstream be happy with adding these getters (in which case I can put together a patch)?
    2. bindgen.sh expects version number as an input, what is the policy when updating the bindings? Should the version be bumped-up?
    Reviewed by silvestrst at 2021-02-02 15:11
  • 2. Test that symbol version names are correct

    Currently, there's no way to automatically test that the version number in link and link_name attributes in boringssl/boringssl.rs match the version number in Cargo.toml. This has already led to an issue: we published 0.2.1 with the version numbers in boringssl/boringssl.rs still at 0.2.0, forcing us to fix and release 0.2.2, and yank 0.2.1. We should add an automated test so this sort of issue can't slip through in the future.

    Reviewed by joshlf at 2018-11-14 19:47
  • 3. Linker bug compiling on Linux

    When compiling on Linux, I get the following linker error:

    /usr/bin/ld: /home/vagrant/tmp/mundane/target/debug/build/mundane-9145b5e5c96cb8ea/out/boringssl/build_2/crypto/libcrypto_0_2_0.a(cbb.c.o): relocation R_X86_64_32 against `.rodata' can not be used when making a shared object; recompile with -fPIC
              /home/vagrant/tmp/mundane/target/debug/build/mundane-9145b5e5c96cb8ea/out/boringssl/build_2/crypto/libcrypto_0_2_0.a: error adding symbols: Bad value
              collect2: error: ld returned 1 exit status
    

    This is surprising because, if I'm not mistaken, @erickt has successfully compiled on Linux before, implying that this is either a nondeterministic issue or has to do with my setup in particular.

    Reviewed by joshlf at 2018-11-07 06:34
  • 4. BoringSSL build failure with GCC > 9

    Introduction

    In later GCC versions some warning semantics have changed, causing build to fail (due to -Werror).

    One example:

      /home/svt/.cargo/registry/src/github.com-1ecc6299db9ec823/mundane-0.4.4/boringssl/boringssl/crypto/fipsmodule/sha/sha512.c: In function ‘SHA512_256_Final’:
      /home/svt/.cargo/registry/src/github.com-1ecc6299db9ec823/mundane-0.4.4/boringssl/boringssl/crypto/fipsmodule/sha/sha512.c:179:10: error: ‘SHA512_Final’ accessing 64 bytes in a region of size 32 [-Werror=stringop-overflow=]
        179 |   return SHA512_Final(out, sha);
    

    This could be unpleasant for people with rolling distros like archlinux that usually have significantly newer compiler versions.

    How to reproduce

    I have experienced the problem with GCC 11:

    Using built-in specs.
    COLLECT_GCC=/usr/bin/gcc
    COLLECT_LTO_WRAPPER=/usr/lib/gcc/x86_64-pc-linux-gnu/11.1.0/lto-wrapper
    Target: x86_64-pc-linux-gnu
    Configured with: /build/gcc/src/gcc/configure --prefix=/usr --libdir=/usr/lib --libexecdir=/usr/lib --mandir=/usr/share/man --infodir=/usr/share/info --with-bugurl=https://bugs.archlinux.org/ --enable-languages=c,c++,ada,fortran,go,lto,objc,obj-c++,d --with-isl --with-linker-hash-style=gnu --with-system-zlib --enable-__cxa_atexit --enable-cet=auto --enable-checking=release --enable-clocale=gnu --enable-default-pie --enable-default-ssp --enable-gnu-indirect-function --enable-gnu-unique-object --enable-install-libiberty --enable-linker-build-id --enable-lto --enable-multilib --enable-plugin --enable-shared --enable-threads=posix --disable-libssp --disable-libstdcxx-pch --disable-libunwind-exceptions --disable-werror gdc_include_dir=/usr/include/dlang/gdc
    Thread model: posix
    Supported LTO compression algorithms: zlib zstd
    gcc version 11.1.0 (GCC)
    

    However, judging by the GCC change log - it is likely that GCC 10 would trigger same errors.

    Some additional thoughts

    There several easy short term solutions of course:

    • Downgrade GCC
    • Build an older version of GCC
    • Check out Mundane locally and do something like "CFLAGS=-Wno-error ./configure" on the BoringSSL (hacky)
    Reviewed by silvestrst at 2021-09-21 07:02
  • 5. Document items behind feature flags

    https://docs.rs/crate/mundane/0.4.2/builds

    [INFO] [stderr]  Documenting mundane v0.4.2 (/opt/rustwide/workdir)
    [INFO] [stderr] error: `[RsaPkcs1v15]` cannot be resolved, ignoring it...
    [INFO] [stderr]    --> src/public/rsa/mod.rs:363:26
    [INFO] [stderr]     |
    [INFO] [stderr] 363 | /// feature is enabled, [`RsaPkcs1v15`].
    [INFO] [stderr]     |                          ^^^^^^^^^^^^^ cannot be resolved, ignoring
    [INFO] [stderr]     |
    

    ========

    Edit by @joshlf : This issue is now about both fixing this issue and also about documenting all items behind feature flags in general; see this comment below.

    Reviewed by taralx at 2019-12-02 21:30
  • 6. Automatically generate link_name attributes in boringssl.rs

    Currently, our bindgen.sh script does not automatically generate the link_name attributes that we need in order to perform symbol renaming as described in boringssl/README.md. Instead, we do this manually, which is annoying.

    We should do this automatically. One good option would be to implement the bindgen feature described in this issue: https://github.com/rust-lang-nursery/rust-bindgen/issues/1375. It could also be good to have a simpler workaround until that feature is implemented.

    Reviewed by joshlf at 2018-11-14 01:11
  • 7. Rename Signature::verify to is_valid

    Signature::verify takes a public key and a signature and returns a boolean. @zarvox has pointed out that it's not 100% obvious to somebody coming across code like if sig.verify(&pub) { ... } which return value means that the signature is valid and which means that it's invalid.

    In order to make it more obvious, we should rename this method to is_valid.

    Reviewed by joshlf at 2019-01-15 22:04
  • 8. Replace "whitelist" with "allowlist"

    In boringssl/bindgen.sh, we use the term "whitelist" to refer to lists of items that should be included by bindgen when generating bindings. For inclusivity reasons, we should use the term "allowlist" instead.

    Reviewed by joshlf at 2021-01-22 19:07
  • 9. Support for TLS?

    Hello,

    it looks like mundane is being actively developed, so I wonder whether are there any plans to support also TLS? If so, could you share some planned timelines?

    Thanks,

    Bartosz.

    Reviewed by przydatek at 2020-04-07 09:43
  • 10. CONTRIBUTING.md: Document that you need to pull from googlesource.com

    Our CONTRIBUTING.md documentation on submitting code was copied from BoringSSL's. As such, it assumes that you know to pull from the googlesource.com repo. Since Mundane is also available on GitHub, it's less obvious in our case.

    Concretely, we should document that submissions should be pushed to https://fuchsia.googlesource.com/mundane. It's probably easiest to document that by suggesting the following command to clone: git clone --recursive https://fuchsia.googlesource.com/mundane.

    Reviewed by joshlf at 2018-11-28 06:57
  • 11. Build docs.rs documentation with all features enabled

    Now that we're using docs.rs to host our documentation, we need to add metadata to the Cargo.toml file to instruct docs.rs to use all build features when building the documentation. By default, it just uses the default features, meaning that we get no documentation for things like the insecure feature.

    For details on how to do this, see the "Metadata for custom builds" section here. In particular, we'll want a section like this:

    [package.metadata.docs.rs]
    features = [ "bytes", "insecure", "..." ]
    

    In total, we'll want the following features documented:

    • bytes
    • insecure
    • kdf
    • rsa-pkcs1v15

    We'll also want to add a comment on the [features] line in Cargo.toml reminding developers to update the [package.metadata.docs.rs] section when they update the [features] section.

    Reviewed by joshlf at 2019-09-30 23:32
  • 12. How can i sign the message without hashing

    I noticed this comment, the function sign() will both hashing and signing the message.

    image

    how can i sign the message without hashing ?

    Looking forward to your reply ~

    Reviewed by dwj1210 at 2022-03-24 07:29
  • 13. Outdated dependency for cmake

    Hello, I recently had the pleasure of building your crate when I noticed that the dependencies may be out of date. It would appear that mundane currently requires cmake 3.3 or higher:

    (Paths redacted below)

    Compiling mundane v0.4.4
    error: failed to run custom build command for `mundane v0.4.4`
    
    Caused by:
      process didn't exit successfully: `....release/build/mundane-dd369fe2607dde56/build-script-main` (exit code: 101)
      --- stdout
      cargo:rerun-if-env-changed=....github.com-1ecc6299db9ec823/mundane-0.4.4
      cargo:rerun-if-env-changed=..../release/build/mundane-453aa1aaa20c68ee/out
      cargo:rerun-if-env-changed=0
      cargo:rerun-if-env-changed=4
      cargo:rerun-if-env-changed=4
      -- Configuring incomplete, errors occurred!
    
      --- stderr
      CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
        CMake 3.3 or higher is required.  You are running version 2.8.12.2
    
    
      thread 'main' panicked at 'cmake failed with status exit code: 1', .../cargo/registry/src/github.com-1ecc6299db9ec823/mundane-0.4.4/build/main.rs:219:9
      note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
    
    Reviewed by martin-lueker at 2021-05-18 13:51
  • 14. Figure out coherent strategy around RSA keys

    Per @davidben's comment here:

    I think you should probably think about what things you want to support and build an API around that.

    • What flavors of RSA private keys do you believe in? Just CRT? n/e/d as well?
    • If you support multiple, do you want to jam them into one type or separate types? (Separate might make more sense given only CRT is serializable.)

    Read the entire comment thread for more context.

    We should answer these questions, document them clearly in our RSA code, and then update the organization of our RSA implementation as appropriate.

    Reviewed by joshlf at 2021-03-02 01:39
  • 15. Make keys Send and Sync, remove Clone

    To err on the safe side, we initially made our key objects neither Send nor Sync. However, BoringSSL provides concurrency semantics for key objects that allow us to relax these restrictions. In particular, key objects' reference counts are incremented and decremented atomically, and all BoringSSL operations on keys have well-defined concurrency safety semantics.

    I propose that we implement Sync on key objects, and use BoringSSL's definition of which functions are mutating to decide which methods to have take a &mut self vs a &self receiver.

    An aside on Clone and reference counting

    Currently, keys are reference counted, and cloning a Mundane key object obtains a new reference-counted reference to the same underlying object. Unfortunately, we cannot implement either Send or Sync so long as it's possible to obtain multiple references to the same underlying object.

    If reference-counted key objects are Send, then different clones could be sent to different threads, and we'd have no way of preventing those two separate clones from being operated on using &mut self methods concurrently, which would be unsound.

    If reference-counted key objects are Sync, then different clones owned by one thread could be accessed concurrently from different threads, and we'd have no way of preventing those two separate clones from being operated on using &mut self methods concurrently, which would be unsound.

    Thus, I conclude that we must remove the ability to clone key objects. The primary benefit to reference counting in BoringSSL is to be able to use keys concurrently from multiple threads at once. Since Rust's lifetime system allows us to share references across threads safely, we get the same advantage even without reference counting. Even if reference counting were desired, we could put a Mundane key object inside of an Rc or an Arc and get the same effect.

    Thus, the concrete tasks are:

    • [ ] Remove the ability to Clone key objects
    • [ ] Audit the codebase to ensure that all mutating BoringSSL functions are exposed via &mut self methods, and document our strategy and reasoning in code comments
    • [ ] Implement Send and Sync on key objects

    Old (incorrect) text:

    BoringSSL key types are reference-counted, and use reference counting to implement Clone. While the reference counting itself is thread-safe (see CRYPTO_refcount_xxx, crypto/internal.h), it's not clear that all operations on keys are also thread-safe. In other words, having two key objects in different threads which are both references to the same underlying BoringSSL object may mean that calling methods on those objects concurrently is unsound. As a result, our key objects do not implement Send.

    Eventually, we will want to identify which methods are thread-safe and which are not. This is not only a prerequisite for making our key objects Send, it's also a prerequisite for making them Sync. However, we can much more easily unblock making our key objects Send by just not implementing Clone so that a given key object is always the only reference to its underlying BoringSSL object.

    Reviewed by joshlf at 2019-08-26 22:06
  • 16. Switch to opaque error type?

    Currently, our error type can be printed as a string, which provides a lot of information about the error. Cryptography errors are a notorious source of information leak, as programmers often misuse the errors and either compute on them or expose them in ways that they shouldn't. Ring, for example, takes the much more aggressive approach of having an error type that contains no information at all.

    I'm not sure what the right thing for us to do here is, since it seems useful to provide some error information, such as about parsing failures. But we need to strike the right balance, and exposing as much as we do now may be too much. This is also compounded by the fact that a lot of the errors we would want to expose (like parsing errors) come from BoringSSL, and BoringSSL's errors cannot be inspected programmatically.

    Reviewed by joshlf at 2019-02-08 20:02
Pairing cryptography library in Rust

bn This is a pairing cryptography library written in pure Rust. It makes use of the Barreto-Naehrig (BN) curve construction from [BCTV2015] to provide

Jun 20, 2022
Pairing cryptography library in Rust

bn This is a pairing cryptography library written in pure Rust. It makes use of the Barreto-Naehrig (BN) curve construction from [BCTV2015] to provide

Apr 22, 2022
Cryptography-oriented big integer library with constant-time, stack-allocated (no_std-friendly) implementations of modern formulas

RustCrypto: Cryptographic Big Integers Pure Rust implementation of a big integer library which has been designed from the ground-up for use in cryptog

Jun 16, 2022
Ursa - Hyperledger Ursa is a shared cryptography library

HYPERLEDGER URSA Introduction Features Libursa Libzmix Dependencies Building from source Contributing Introduction Ursa was created because people in

May 31, 2022
WIP, POC of node js driver for pulsar backed by rust

WIP not ready at all, POC for node js rurt based pulsar driver pulsar-node-rust-client This project was bootstrapped by create-neon. Installing pulsar

Jun 2, 2022
Collect libraries and packages about cryptography in Rust.

Awesome Cryptography Rust Collect libraries and packages about cryptography in Rust. Collection Library Symmetric Public-key / Asymmetric One-way Hash

Jun 19, 2022
Implementation of the Web Cryptography specification in Rust.

[wip] webcrypto Implementation of the Web Cryptography specification in Rust. This crate hopes to ease interoperability between WASM and native target

Mar 7, 2022
Example implementation for Biscuit tokens cryptography

example implementation for Biscuit token cryptography To aid in the implementation of Biscuit tokens in various languages, this repository contains an

May 25, 2021
Manage secret values in-repo via public key cryptography

amber Manage secret values in-repo via public key cryptography. See the announcement blog post for more motivation. Amber provides the ability to secu

Apr 19, 2022
Cryptography-related format encoders/decoders: PKCS, PKIX

RustCrypto: Formats Cryptography-related format encoders/decoders: PKCS, PKIX. Crates Name crates.io Docs Description base64ct Constant-time encoder a

Jun 16, 2022
BLS12-381 cryptography using Apache Milagro

BLS12-381 Aggregate Signatures in Rust using Apache Milagro WARNING: This library is a work in progress and has not been audited. Do NOT consider the

Apr 4, 2022
Traits - Collection of cryptography-related traits

RustCrypto: Traits Collection of traits which describe functionality of cryptographic primitives. Crates Name Algorithm Crates.io Docs MSRV aead Authe

Jun 21, 2022
The new, performant, and simplified version of Holochain on Rust (sometimes called Holochain RSM for Refactored State Model)

Holochain License: This repository contains the core Holochain libraries and binaries. This is the most recent and well maintained version of Holochai

Jun 15, 2022
Library with support for de/serialization, parsing and executing on data-structures and network messages related to Bitcoin
Library with support for de/serialization, parsing and executing on data-structures and network messages related to Bitcoin

Rust Bitcoin Library with support for de/serialization, parsing and executing on data-structures and network messages related to Bitcoin. Heads up for

Jun 17, 2022
Aya is an eBPF library for the Rust programming language, built with a focus on developer experience and operability.

Aya API docs | Chat | Aya-Related Projects Overview eBPF is a technology that allows running user-supplied programs inside the Linux kernel. For more

Jun 24, 2022
A library to help you sew up your Ethereum project with Rust and just like develop in a common backend

SewUp Secondstate EWasm Utility Program, a library helps you sew up your Ethereum project with Rust and just like development in a common backend. The

Jun 9, 2022
Enigma Core library. The domain: Trusted and Untrusted App in Rust.

Enigma Core library Service Master Develop CI Badge Pure Rust Enclave && Untrusted in Rust. Core is part of the Enigma node software stack. The Core c

May 9, 2022
Zei is a library that provide tools to create and verify public transaction with confidential data.
Zei is a library that provide tools to create and verify public transaction with confidential data.

#Zei: Findora's Cryptographic Library Zei is a library that provide tools to create and verify public transaction with confidential data. Support: Bas

Jun 20, 2022
Helper library for interacting with Terra assets (SDK coins and CW20 tokens)

terra-asset Helpers for interacting with Terra assets, including native coins and CW20 tokens Usage This crate contains two struct types: AssetInfo st

Jan 3, 2022