boring 0.4.2

Raw FFI bindings to BoringSSL, compiled and bundled through Dart Native Assets.

Raw ffigen bindings to Google's BoringSSL (bssl_dart).

Warning

package:boring is not meant to be used directly by application developers. It is meant to facilitate code reuse for developers building higher-level cryptography packages on top of BoringSSL.

Note

This package is currently experimental and published under the labs.dart.dev pub publisher in order to solicit feedback.

For packages in the labs.dart.dev publisher we generally plan to either graduate the package into a supported publisher (dart.dev, tools.dart.dev) after a period of feedback and iteration, or discontinue the package. These packages have a much higher expected rate of API and breaking changes.

Your feedback is valuable and will help us evolve this package. For general feedback, suggestions, and comments, please file an issue in the bug tracker.

Error Handling

BoringSSL signals failure through return values and pushes details onto a per-thread error queue. A Dart isolate may resume on a different OS thread after an await, and every package using package:boring on a thread shares its queue, so:

• Read errors with extractBoringSslError(), which also clears the queue, right after the failing call. Don't leave an await in between, and don't defer it to a finally that may run after one, such as the release of an async BoringArena.using.
• Discard errors you ignore with ERR_clear_error(), for example when a failed signature verification just means false. Otherwise they are reported for the next, unrelated failure.
• Call ERR_clear_error() before a call whose errors you report, so errors left behind by other code aren't attributed to it.

Native Asset Build Modes

Configured in pubspec.yaml under hooks.user_defines.boring:

hooks:
  user_defines:
    boring:
      buildMode: fetch # 'fetch', 'checkout', or 'local'

• fetch (default): Downloads the prebuilt library of the pinned release from GitHub Releases and verifies it against the SHA-256 hash pinned in the package. A hash mismatch is an error.
• checkout: Compiles BoringSSL locally from bundled sources via CMake and Ninja.
• local: Uses a custom prebuilt dynamic library at localPath, which is bundled as is, without tree-shaking.

Prebuilt libraries exist for Linux (x64 and arm64), macOS (arm64 and x64), Windows (x64), Android (arm, arm64 and x64; API 21 and later), and iOS (arm64, and the arm64 and x64 simulators; iOS 12 and later). Other targets require buildMode: checkout, which requires CMake, Ninja, and a C toolchain (Clang or GCC, Xcode, MSVC, or the Android NDK), plus NASM on Windows.

Tree-Shaking

When linking is enabled (dart build, and Flutter profile and release builds), hook/link.dart links a dynamic library with only the functions the application uses from the static library. The bindings are annotated with @RecordUse(), so the Dart compiler records which of them the application calls, tears off, or takes the address of with addresses.*. For the example, the bundled library shrinks from 2.9 MB to 240 KB on Linux x64.

• Use addresses.X rather than Native.addressOf(X) for the address of a function, for example for a NativeFinalizer. Native.addressOf isn't recorded, so the function would be missing from the library.
• Without recorded uses, for example with flutter config --no-enable-record-use, all functions are kept.
• Linking requires a C toolchain for the target (Clang or GCC, Xcode, MSVC, or the Android NDK). Without one, for example when cross-compiling, the fetch build mode bundles the prebuilt dynamic library instead, which is not tree-shaken, and prints a warning.

Conformance Testing

CI checks the bundled BoringSSL and the generated bindings against two external suites, calling BoringSSL directly through the bindings (see test/conformance/):

• Project Wycheproof (./tool/run_conformance_tests.sh): AES-GCM, ChaCha20-Poly1305, XChaCha20-Poly1305, AES-CBC, AES Key Wrap, Ed25519, ECDSA (P-256, P-384, P-521), RSA PKCS#1 v1.5 and RSA-PSS signatures, RSA-OAEP, ECDH, HKDF, HMAC, and PBKDF2.
• x509-limbo (./tool/run_x509_limbo_tests.sh): 9,770 of the 9,793 path validation testcases run against X509_verify_cert, and 9,240 (94.6%) agree. The divergences, mostly name constraint types BoringSSL does not support and CA/Browser Forum profile checks it leaves to the caller, are listed and explained in test/conformance/x509_limbo_expected_failures.txt.

License

See LICENSE for details. BoringSSL is licensed under Apache 2.0 and BSD-style licenses; see third_party/boringssl/LICENSE.