Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions .github/workflows/boring.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,23 @@ jobs:
run: dart test
if: always() && steps.install.outcome == 'success'

# Build BoringSSL with AddressSanitizer through the build hook, and run the
# tests on the Dart VM built with it.
asan:
needs: analyze
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
- uses: dart-lang/setup-dart@6afc89df92d6eb3834022f73cd65adc8cdfcb92d
with:
sdk: dev
- name: Install dependencies
run: dart pub get
- name: Run tests with AddressSanitizer
run: dart test -c cli -p vm-asan test/boring_test.dart

# Check the bundled BoringSSL and the bindings against Project Wycheproof.
conformance:
needs: analyze
Expand Down
8 changes: 5 additions & 3 deletions .github/workflows/boring_binaries.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -61,15 +61,17 @@ jobs:
# tool/precompile_binaries.dart.
include:
# The oldest available Ubuntu, so the libraries only require glibc
# 2.35.
# 2.34, for the pthread functions that moved into libc in 2.34. Keep
# `max-glibc` in sync with `prebuiltLinuxGlibc` in
# lib/src/hook_helpers/libc.dart.
- os: ubuntu-22.04
target-os: linux
target-arch: x64
max-glibc: '2.35'
max-glibc: '2.34'
- os: ubuntu-22.04-arm
target-os: linux
target-arch: arm64
max-glibc: '2.35'
max-glibc: '2.34'
- os: macos-15
target-os: macos
target-arch: arm64
Expand Down
15 changes: 15 additions & 0 deletions pkgs/boring/CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,19 @@
## 0.4.3-wip
- On Linux, the `fetch` build mode checks that the machine has glibc 2.34 or
later, which the prebuilt libraries require, and otherwise fails with a hint
to use `buildMode: checkout`, instead of bundling a library that fails to
load. This includes distributions with another C library, such as musl on
Alpine Linux. The README now lists the requirement.
- BoringSSL is compiled with `OPENSSL_SMALL`, which for example makes the
tree-shaken library of `package:webcrypto` about 19% smaller, and P-256
operations about 2x slower.
- When the Dart runtime uses a sanitizer (`asan`, `msan`, or `tsan`), the
`fetch` and `checkout` build modes compile BoringSSL with it, using Clang.
The prebuilt libraries aren't instrumented, so `fetch` builds from source.
- The `checkout` build mode rebuilds when BoringSSL's `.inc` files change.
- Fixed the bindings of the `BN_*_word` functions on 32-bit targets, such as
Android arm. `BN_ULONG` is now `UintPtr` instead of `Uint64`, because it is
`uint32_t` on 32-bit targets.
- Update BoringSSL to [8f2554dc](https://boringssl.googlesource.com/boringssl/+/8f2554dc344d403fd6d628773d39637c323eb801).

## 0.4.2
Expand Down
15 changes: 15 additions & 0 deletions pkgs/boring/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,21 @@ 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.

The prebuilt Linux libraries require glibc 2.34 or later, for example Ubuntu
22.04, Debian 12, RHEL 9, Fedora 35, or Amazon Linux 2023. On older
distributions, and on distributions with another C library, such as musl on
Alpine Linux, the `fetch` build mode fails with a hint to use `buildMode:
checkout` instead, which compiles BoringSSL for the C library of the machine.

When the Dart runtime uses a sanitizer, for example with `dart test -p
vm-asan`, the `fetch` build mode compiles BoringSSL from source with that
sanitizer and Clang instead, because the prebuilt libraries aren't
instrumented.

BoringSSL is compiled with `OPENSSL_SMALL`, which trades slower elliptic-curve
operations (for example about 2x slower P-256 signatures) for smaller
precomputed tables that tree-shaking can't remove.

## Tree-Shaking

When linking is enabled (`dart build`, and Flutter profile and release builds),
Expand Down
32 changes: 30 additions & 2 deletions pkgs/boring/hook/build.dart
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,22 @@ Future<void> main(List<String> args) async {
// the application uses from the static library.
final static = input.config.linkingEnabled;

switch (buildOptions.buildMode) {
// The prebuilt libraries aren't built with a sanitizer, but all native
// code must be compiled with the sanitizer of the Dart runtime that loads
// it (for example `dart test -p vm-asan`), so build from source.
final sanitizer = input.config.code.sanitizer;
final buildMode =
sanitizer != null && buildOptions.buildMode == BuildModeEnum.fetch
? BuildModeEnum.checkout
: buildOptions.buildMode;
if (buildMode != buildOptions.buildMode) {
stdout.writeln(
'boring: building from source, because there are no prebuilt '
'libraries with the ${sanitizer!.name} sanitizer.',
);
}

switch (buildMode) {
case BuildModeEnum.fetch:
final library = await fetchPrebuiltLibrary(input, static: static);
_addLibrary(input, output, library, static: static);
Expand Down Expand Up @@ -106,9 +121,11 @@ Future<void> _buildLocalCMake(
final sourceDir = packageRoot.resolve('src/');
final targetOS = input.config.code.targetOS;
final targetArch = input.config.code.targetArchitecture;
final sanitizer = input.config.code.sanitizer;

stdout.writeln(
'boring: building native asset with CMake for $targetOS-$targetArch.',
'boring: building native asset with CMake for $targetOS-$targetArch'
'${sanitizer == null ? '' : ' with the ${sanitizer.name} sanitizer'}.',
);

// Installs both the dynamic and the static library, see src/CMakeLists.txt.
Expand All @@ -118,6 +135,14 @@ Future<void> _buildLocalCMake(
defines: {
'CMAKE_BUILD_TYPE': 'Release',
'CMAKE_INSTALL_PREFIX': installDir.toFilePath(),
// The Dart SDK's sanitizer runtimes come from Clang, so compile with
// Clang instead of the compiler of the build config's toolchain.
if (sanitizer != null) ...{
'CMAKE_TOOLCHAIN_FILE': '',
'CMAKE_C_COMPILER': 'clang',
'CMAKE_CXX_COMPILER': 'clang++',
'BSSL_DART_SANITIZER': sanitizer.name,
},
},
targets: ['install'],
parallelUseAllProcessors: true,
Expand Down Expand Up @@ -147,6 +172,9 @@ final _buildDependencyExtensions = {
'.cmake',
'.cpp',
'.h',
// BoringSSL includes `.cc.inc` and `.c.inc` files, for example in
// crypto/fipsmodule/.
'.inc',
'.s',
'CMakeLists.txt',
};
Expand Down
11 changes: 11 additions & 0 deletions pkgs/boring/lib/bindings.dart
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,17 @@ import 'src/bindings/boringssl.g.dart' as bssl;
export 'src/arena.dart';
export 'src/bindings/boringssl.g.dart';

/// BoringSSL's `BN_ULONG`, a word of a [bssl.BIGNUM].
///
/// It's pointer-sized: `uint64_t` on 64-bit targets and `uint32_t` on 32-bit
/// targets. The generated bindings use [ffi.UintPtr] for it.
// ignore: camel_case_types
typedef BN_ULONG = ffi.UintPtr;

/// The Dart type of [BN_ULONG].
// ignore: camel_case_types
typedef DartBN_ULONG = int;

/// An [ffi.Allocator] backed by BoringSSL's [bssl.OPENSSL_malloc] and
/// [bssl.OPENSSL_free].
///
Expand Down
32 changes: 15 additions & 17 deletions pkgs/boring/lib/src/bindings/boringssl.g.dart

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

13 changes: 13 additions & 0 deletions pkgs/boring/lib/src/hook_helpers/fetch.dart
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import 'package:crypto/crypto.dart' show sha256;
import 'package:hooks/hooks.dart';

import 'hashes.dart' show fileHashes, releaseRepository, releaseTag;
import 'libc.dart' show currentGlibcVersion, unsupportedLinuxLibcReason;
import 'targets.dart'
show libraryFileName, releaseAssetName, releaseAssetUrl, targetTripleFor;

Expand Down Expand Up @@ -58,6 +59,18 @@ Future<Uri> fetchPrebuiltLibrary(
);
}

// The prebuilt libraries would fail to load on another C library. Only the
// C library of this machine is known, so this only checks builds for it, as
// in `dart run` and `dart test`.
if (targetOS == OS.linux &&
OS.current == OS.linux &&
targetArch == Architecture.current) {
final reason = unsupportedLinuxLibcReason(currentGlibcVersion());
if (reason != null) {
throw BuildError(message: '$reason\n$_checkoutHint');
}
}

final fileName = libraryFileName(targetOS, static: static);
final cachedFile = File.fromUri(
input.outputDirectoryShared
Expand Down
58 changes: 58 additions & 0 deletions pkgs/boring/lib/src/hook_helpers/libc.dart
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
// Copyright (c) 2026, the Dart project authors. Please see the AUTHORS file
// for details. All rights reserved. Use of this source code is governed by a
// BSD-style license that can be found in the LICENSE file.

import 'dart:ffi';

/// The oldest glibc that the prebuilt Linux libraries run on.
///
/// They're built on the oldest Ubuntu that GitHub Actions has, 22.04, and the
/// pthread functions they use moved into libc in glibc 2.34. Keep in sync with
/// `max-glibc` of the Linux targets in `.github/workflows/boring_binaries.yaml`,
/// which checks the libraries, and with README.md.
const prebuiltLinuxGlibc = (2, 34);

/// The version of the GNU C library (glibc) of this process, or `null` if the
/// process doesn't use glibc, for example on Alpine Linux, which uses musl.
(int, int)? currentGlibcVersion() {
final process = DynamicLibrary.process();
if (!process.providesSymbol('gnu_get_libc_version')) {
return null;
}
final gnuGetLibcVersion = process
.lookupFunction<Pointer<Uint8> Function(), Pointer<Uint8> Function()>(
'gnu_get_libc_version',
);
final version = gnuGetLibcVersion();
final bytes = <int>[];
for (var i = 0; version[i] != 0; i++) {
bytes.add(version[i]);
}
return parseGlibcVersion(String.fromCharCodes(bytes));
}

/// Parses the major and minor version from a glibc version string, such as
/// `2.35` or `2.39.9000`.
(int, int)? parseGlibcVersion(String version) {
final match = RegExp(r'^(\d+)\.(\d+)').firstMatch(version);
if (match == null) {
return null;
}
return (int.parse(match[1]!), int.parse(match[2]!));
}

/// Why the prebuilt Linux libraries can't run with the C library
/// [glibcVersion] (see [currentGlibcVersion]), or `null` if they can.
String? unsupportedLinuxLibcReason((int, int)? glibcVersion) {
final (minMajor, minMinor) = prebuiltLinuxGlibc;
if (glibcVersion == null) {
return 'The prebuilt Linux libraries require glibc, but this system uses '
'another C library, such as musl on Alpine Linux.';
}
final (major, minor) = glibcVersion;
if (major < minMajor || (major == minMajor && minor < minMinor)) {
return 'The prebuilt Linux libraries require glibc $minMajor.$minMinor or '
'newer, but this system has glibc $major.$minor.';
}
return null;
}
Loading
Loading