| [](https://github.com/dart-lang/tools/actions/workflows/boring.yaml) | |
| [](https://pub.dev/packages/boring) | |
| [](https://pub.dev/packages/boring/publisher) | |
| Raw `ffigen` bindings to Google's | |
| [BoringSSL](https://boringssl.googlesource.com/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](https://dart.dev/dart-team-packages) 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](https://github.com/dart-lang/tools/issues). | |
| ## 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. | |
| ## Building | |
| `hook/build.dart` compiles the bundled BoringSSL sources with CMake and Ninja | |
| when the package is first built, for example by `dart run` or `dart test`. This | |
| requires CMake, Ninja, and a C toolchain (Clang or GCC, Xcode, MSVC, or the | |
| Android NDK), plus NASM on Windows. | |
| ## Conformance Testing | |
| CI checks the bundled BoringSSL and the generated bindings against two external | |
| suites, calling BoringSSL directly through the bindings (see | |
| [`test/conformance/`](test/conformance/)): | |
| - [**Project Wycheproof**](https://github.com/C2SP/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**](https://x509-limbo.com) (`./tool/run_x509_limbo_tests.sh`): | |
| 9,770 of the 9,793 path validation testcases run against `X509_verify_cert`, | |
| and 9,237 (94.5%) 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`][limbo-failures]. | |
| [limbo-failures]: test/conformance/x509_limbo_expected_failures.txt | |
| ## License | |
| See [LICENSE](LICENSE) for details. BoringSSL is licensed under Apache 2.0 and | |
| BSD-style licenses; see | |
| [`third_party/boringssl/LICENSE`](third_party/boringssl/LICENSE). |