Skip to content

Commit 6eff17e

Browse files
justsmthjustsmth
authored
Support WASM/Emscripten (#2959)
### Issues: Addresses: P372521248 ### Description of changes: This PR adds support for building and testing AWS-LC with WebAssembly (WASM) using an Emscripten toolchain. ### Description - Defines `OPENSSL_WASM` when compiling with `__wasm__` to enable WASM-specific code paths - Configures WASM builds to use `getentropy()` for random number generation, which Emscripten provides - Provide CMake toolchain file: `util/wasm-toolchain.cmake` - Added `tests/ci/run_emscripten_tests.sh` for testing. - Added CI workflow: .github/workflows/emscripten.yml ### Call-outs: - Threading is enabled via Emscripten's pthread implementation using Web Workers and SharedArrayBuffer - Tests that require `fork()` or POSIX sockets are excluded as these are not supported in the WASM/Emscripten environments ### Testing: - The new CI workflow builds AWS-LC and runs `crypto_test`, `urandom_test`, and `ssl_test` in a WASM/Node.js environment - All tests pass except those explicitly filtered out due to WASM platform limitations (fork/socket operations) By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license and the ISC license.
1 parent 741d90d commit 6eff17e

8 files changed

Lines changed: 455 additions & 29 deletions

File tree

‎.github/workflows/emscripten.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
2+
# SPDX-License-Identifier: Apache-2.0 OR ISC
3+
4+
name: WASM Build & Test
5+
on:
6+
push:
7+
branches: ["*"]
8+
pull_request:
9+
branches: ["*"]
10+
concurrency:
11+
group: ${{ github.workflow }}-${{ github.ref_name }}
12+
cancel-in-progress: true
13+
permissions:
14+
contents: read
15+
16+
env:
17+
EMSDK_VERSION: "4.0.23"
18+
19+
jobs:
20+
wasm-build-test:
21+
if: github.repository_owner == 'aws'
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- name: Setup Node.js
27+
uses: actions/setup-node@v4
28+
with:
29+
node-version: '20'
30+
31+
- name: Install build dependencies
32+
run: |
33+
sudo apt-get update -o Acquire::Languages=none -o Acquire::Translation=none
34+
sudo apt-get -y --no-install-recommends install cmake ninja-build
35+
36+
- name: Setup Emscripten SDK
37+
uses: mymindstorm/setup-emsdk@v14
38+
with:
39+
version: ${{ env.EMSDK_VERSION }}
40+
41+
- name: Verify Emscripten installation
42+
run: |
43+
emcc --version
44+
node --version
45+
46+
- name: Run Emscripten tests
47+
env:
48+
EMSDK_PATH: ${{ env.EMSDK }}
49+
run: |
50+
./tests/ci/run_emscripten_tests.sh

‎.gitignore‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ cmake-build-debug/
33
build/
44
build32/
55
build64/
6-
build-fips/
6+
build-*/
77
*_BUILD_ROOT/
88
ssl/test/runner/runner
99
*.pyc

‎README.md‎

Lines changed: 34 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -68,24 +68,24 @@ adding it to our CI.
6868

6969
## Platform Support
7070

71-
AWS-LC correctness is tested on a variety of *platforms* (i.e., OS/CPU combinations).
72-
The following is an overview of the platforms we actively support or are
73-
known to be of interest to our community.
71+
AWS-LC correctness is tested on a variety of *platforms* (i.e., OS/CPU combinations).
72+
The following is an overview of the platforms we actively support or are
73+
known to be of interest to our community.
7474

7575
If you use a platform not listed below and would like to request it be added to our CI,
7676
please open an [issue](https://github.com/aws/aws-lc/issues/new/choose) for discussion.
77-
Regardless of our support level for a particular platform, we will gladly consider contributions that
77+
Regardless of our support level for a particular platform, we will gladly consider contributions that
7878
improve or extend our support.
7979

8080
### Supported Platforms
8181

82-
The following platforms are actively tested in our CI pipeline. A few of these platforms are tested across
83-
multiple compilers or compiler versions. For each pull request, the proposed change is validated to confirm that it
84-
successfully builds and tests pass for these platform.
85-
A more complete description of our test setup can be found in the
82+
The following platforms are actively tested in our CI pipeline. A few of these platforms are tested across
83+
multiple compilers or compiler versions. For each pull request, the proposed change is validated to confirm that it
84+
successfully builds and tests pass for these platform.
85+
A more complete description of our test setup can be found in the
8686
[CI README](https://github.com/aws/aws-lc/blob/main/tests/ci/README.md).
8787

88-
| OS | CPU |
88+
| OS | CPU |
8989
|---------|---------|
9090
| Linux | x86 |
9191
| Linux | x86-64 |
@@ -100,21 +100,33 @@ A more complete description of our test setup can be found in the
100100

101101
### Other platforms
102102

103-
The platforms listed below are of interest to us or to our community. However, problems reported
104-
against them might not be prioritized for immediate action by our team. We welcome contributions
103+
The platforms listed below are of interest to us or to our community. However, problems reported
104+
against them might not be prioritized for immediate action by our team. We welcome contributions
105105
that improve the experience for consumers on these platforms.
106106

107-
| OS | CPU |
108-
|-----------|-------------|
109-
| Android | arm32 |
110-
| iOS | aarch64 |
111-
| Linux | arm32 |
112-
| Linux | loongarch64 |
113-
| Linux | risc-v64 |
114-
| Linux | s390x |
115-
| Windows | aarch64 |
116-
| OpenBSD | x86-64 |
117-
| FreeBSD | x86-64 |
107+
| OS | CPU |
108+
|------------|-------------|
109+
| Android | arm32 |
110+
| Emscripten | wasm32 |
111+
| iOS | aarch64 |
112+
| Linux | arm32 |
113+
| Linux | loongarch64 |
114+
| Linux | risc-v64 |
115+
| Linux | s390x |
116+
| Windows | aarch64 |
117+
| OpenBSD | x86-64 |
118+
| FreeBSD | x86-64 |
119+
120+
### WebAssembly (WASM) Support
121+
122+
AWS-LC can be built for WebAssembly using Emscripten. This support is experimental and has important security considerations:
123+
124+
- **No FIPS mode**: WASM builds cannot be FIPS-validated
125+
- **Randomness**: Relies on the runtime's `getentropy()` implementation
126+
- **No side-channel protections**: Timing and cache-based side-channel mitigations that exist for native builds may not apply in the WASM environment
127+
- **Threading limitations**: Uses Web Workers which have different security properties than native threads
128+
129+
For build instructions, see [BUILDING.md](./BUILDING.md).
118130

119131
### FIPS Compliance
120132

@@ -193,5 +205,3 @@ Security via our
193205
Please do **not** create a public GitHub issue.
194206

195207
If you package or distribute AWS-LC, or use AWS-LC as part of a large multi-user service, you may be eligible for pre-notification of future AWS-LC releases. Please contact aws-lc-pre-notifications@amazon.com.
196-
197-

‎crypto/CMakeLists.txt‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -702,8 +702,9 @@ endif()
702702
#
703703
# For now we assume embedded OSes do not have threads. Additionally, the Threads
704704
# package does not work with Android, but Android does not require any extra
705-
# parameters to link pthreads.
706-
if(NOT CMAKE_SYSTEM_NAME MATCHES "^(Generic|Android)$")
705+
# parameters to link pthreads. Emscripten provides its own pthread implementation
706+
# via Web Workers and SharedArrayBuffer, configured through compiler flags.
707+
if(NOT CMAKE_SYSTEM_NAME MATCHES "^(Generic|Android|Emscripten)$")
707708
find_package(Threads REQUIRED)
708709
target_link_libraries(crypto PUBLIC Threads::Threads)
709710
endif()

‎crypto/rand_extra/internal.h‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
#define OPENSSL_RAND_WINDOWS
1313
#elif defined(OPENSSL_MACOS) || defined(OPENSSL_OPENBSD) || \
1414
defined(OPENSSL_FREEBSD) || defined(OPENSSL_NETBSD) || \
15-
defined(OPENSSL_SOLARIS) || \
15+
defined(OPENSSL_SOLARIS) || defined(OPENSSL_WASM) || \
1616
(defined(OPENSSL_LINUX) && !defined(HAVE_LINUX_RANDOM_H))
1717
#define OPENSSL_RAND_GETENTROPY
1818
#elif defined(OPENSSL_IOS)

‎include/openssl/target.h‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,8 @@
8787
#define OPENSSL_LOONGARCH64
8888
#elif defined(__pnacl__)
8989
#define OPENSSL_PNACL
90-
#elif defined(__wasm__) // Allowed but no macro defined
90+
#elif defined(__wasm__)
91+
#define OPENSSL_WASM
9192
#elif defined(__asmjs__) // Allowed but no macro defined
9293
#elif defined(__myriad2__) // Allowed but no macro defined
9394
#else

0 commit comments

Comments
 (0)