THE SOFTWARE IS PROVIDED “AS IS” AND BRIAN SMITH AND THE AUTHORS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL BRIAN SMITH OR THE AUTHORS BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

ring

ring is a crypto library for Rust based on BoringSSL’s crypto primitive implementations.

Particular attention is being paid to making it easy to build and integrate ring into applications and higher-level frameworks, and to ensuring that ring works optimally on small devices, and eventually microcontrollers, to support Internet of Things (IoT) applications.

The name ring comes from the fact that ring started as a subset of BoringSSL, and “ring” is a substring of “Bo*ring*SSL”. Most of the (C and assembly language) code in ring comes from BoringSSL, and BoringSSL is derived from OpenSSL. ring merges changes from BoringSSL regularly. Also, several changes that were developed for ring have already been merged into BoringSSL.

ring is focused on the implementation, testing, and optimization of core crypto primitives. WebPKI X.509 certificate validation is done in the webpki project, which is built on top of ring. Also, multiple groups are working on TLS implementations on top of ring and webpki.

Documentation

See the documentation at https://briansmith.org/rustdoc/ring/.

See BUILDING.md for instructions on how to build it. These instructions are especially important on Windows, as there are build prerequisites that need to be installed.

Benchmarks

ring’s benchmarks are in the crypto-bench project. Because there is lots of platform-specific code in ring, and because ring chooses dynamically at runtime which optimized implementation of each crypto primitive to use, it is very difficult to publish a useful single set of benchmarks; instead, you are highly encouraged to run the benchmarks yourselves on your target hardware.

Contributing

The ring project happily accepts pull requests without you needing to sign any formal license agreement. The portions of pull requests that modify existing files must be licensed under the same terms as the files being modified. New files in pull requests, including in particular all Rust code, must be licensed under the ISC-style license. Please state that you agree to license your contributions in the commit messages of commits in pull requests, e.g. by putting this at the bottom of your commit message:


I agree to license my contributions to each file under the terms given
at the top of each file I changed.

The most important contributions are uses of ring. That is, we’re very interested in seeing useful things built on top of ring, like implementations of TLS, SSH, the Noise Protocol, etc.

Of course, contributions to ring’s code base are highly appreciated too. If you want to work directly on ring and you don’t have an idea for something to contribute already, see these curated lists of open issues:

  • good-first-bug: Bugs that we think newcomers might find best to start with. Note that what makes a bug a good fit depends a lot on the developer’s background and not just the hardness of the work.
  • oxidation: Replacing C code with Rust code.
  • tls-1.3: Issues blocking a complete implementation of TLS 1.3:
  • rsa: The primary ring developer is less interested in RSA than ECC and other things, and it would be great to have somebody jump in and “own” the RSA work. ring has inherited the fastest open source RSA implementation (as far as we know) from BoringSSL/OpenSSL, and we’ve already done a lot of cleanup. But, there’s a lot more work to do.

In addition, we’re always interested in these kinds of contributions:

  • Expanded benchmarks in the crypto-bench project.
  • Additional testing code and additional test vectors.
  • Static analysis and fuzzing in the continuous integration.
  • Support for more platforms in the continuous integration (e.g. Android, iOS, ARM microcontrollers).
  • Documentation improvements.
  • More code simplification, especially eliminating dead code.
  • Improving the code size, execution speed, and/or memory footprint.
  • Fixing any bugs you may have found.
  • Better IDE support for Windows (e.g. running the tests within the IDE) and macOS (e.g. Xcode project files).

Before submitting pull requests, make sure that the tests succeed both when running cargo test and cargo test --features=rsa_signing. See BUILDING.md for more info about the features flags that are useful for people hacking on ring.

Online Automated Testing

Travis CI is used for Android, Linux, and macOS. Appveyor is used for Windows. The tests are run in debug and release configurations, for the current release of each Rust channel (Stable, Beta, Nightly), for each configuration listed in the table below.

OSArch.CompilersStatus
Linux x86, x86_64 GCC 4.6, GCC 5, GCC 6, Clang 3.8
32‑bit ARM, AAarch64 GCC (Ubuntu/Linaro 4.8.4-2ubuntu1~14.04.1), tested using qemu-user-arm.
Android 32‑bit ARM Built using the Android SDK 24.4.1 and Android NDK 10e, tested using the Android emulator. (Aarch64 builds are blocked on the Rust team producing AAarch64 builds of Rust's libstd.)
Mac OS X x64 Apple LLVM version 7.3.0 (clang-703.0.31) from Xcode 7.3
Windows x86, x86_64 MSVC 2015 Update 3 (14.0)

Bug Reporting

Please report bugs either as pull requests or as issues in the issue tracker. ring has a full disclosure vulnerability policy. Please do NOT attempt to report any security vulnerability in this code privately to anybody.

License

See LICENSE.

Related Repositories

ring-json

ring-json

Ring middleware for handling JSON ...

shoreleave-remote-ring

shoreleave-remote-ring

Ring- (& Compojure-) friendly remote functions for use w/ shoreleave + ClojureScript ...

ring

ring

The Ring Programming Language ...

ring-netty-adapter

ring-netty-adapter

Netty Support for Ring ...

ring-transit

ring-transit

Ring middleware for handling transit format ...


Top Contributors

briansmith davidben agl SAHF dvorak42 djc frewsxcv PiotrSikora achernya nharper pietro haavardmolland llogiq ranweiler plietar shishkander benlaurie SimonSapin Ms2ger nico estark37 thejk mattcaswell samscott89 sbc100 ekr kruton pyfisch ghedo ekasper