Skip to content

Commit a5682cb

Browse files
jackctj117jackctj117
committed
Added bare-metal build and documentation
1 parent 7593364 commit a5682cb

File tree

4 files changed

+217
-0
lines changed

4 files changed

+217
-0
lines changed

‎.github/workflows/baremetal.yml‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
name: Bare-Metal Configuration Tests
2+
3+
on:
4+
push:
5+
branches: [ 'master', 'main', 'release/**' ]
6+
pull_request:
7+
branches: [ '*' ]
8+
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
baremetal_autotools:
15+
name: Bare-metal build (autotools)
16+
if: github.repository_owner == 'wolfssl'
17+
runs-on: ubuntu-latest
18+
timeout-minutes: 10
19+
strategy:
20+
fail-fast: false
21+
matrix:
22+
config: [
23+
'--enable-baremetal',
24+
'--enable-baremetal --enable-cryptonly'
25+
]
26+
steps:
27+
- uses: actions/checkout@v4
28+
29+
- name: Install dependencies
30+
run: sudo apt-get update && sudo apt-get install -y autoconf automake libtool
31+
32+
- name: autogen
33+
run: ./autogen.sh
34+
35+
- name: configure
36+
run: CPPFLAGS="-DWOLFSSL_USER_IO" ./configure ${{ matrix.config }} --disable-examples --enable-cryptocb
37+
38+
- name: build
39+
run: make -j$(nproc)
40+
41+
- name: Verify macro definitions
42+
run: |
43+
cat > test_baremetal_defines.c <<'EOF'
44+
#include <wolfssl/options.h>
45+
#include <wolfssl/wolfcrypt/settings.h>
46+
#include <stdio.h>
47+
48+
int main() {
49+
int errors = 0;
50+
51+
#ifdef WOLFSSL_BAREMETAL
52+
printf("✓ WOLFSSL_BAREMETAL is defined\n");
53+
#else
54+
printf("✗ ERROR: WOLFSSL_BAREMETAL should be defined\n");
55+
errors++;
56+
#endif
57+
58+
#ifdef WOLFCRYPT_ONLY
59+
printf("✓ WOLFCRYPT_ONLY is defined\n");
60+
#ifdef NO_ASN_TIME
61+
printf("✓ NO_ASN_TIME is defined (expected with WOLFCRYPT_ONLY)\n");
62+
#else
63+
printf("✗ ERROR: NO_ASN_TIME should be defined when WOLFCRYPT_ONLY is set\n");
64+
errors++;
65+
#endif
66+
#else
67+
printf("✓ WOLFCRYPT_ONLY is NOT defined\n");
68+
#ifdef NO_ASN_TIME
69+
printf("✗ ERROR: NO_ASN_TIME should NOT be defined without WOLFCRYPT_ONLY\n");
70+
errors++;
71+
#else
72+
printf("✓ NO_ASN_TIME is NOT defined (expected without WOLFCRYPT_ONLY)\n");
73+
#endif
74+
#endif
75+
76+
return errors;
77+
}
78+
EOF
79+
gcc -I. test_baremetal_defines.c -o test_baremetal_defines
80+
./test_baremetal_defines
81+
82+
baremetal_cmake:
83+
name: Bare-metal build (CMake)
84+
if: github.repository_owner == 'wolfssl'
85+
runs-on: ubuntu-latest
86+
timeout-minutes: 10
87+
strategy:
88+
fail-fast: false
89+
matrix:
90+
cryptonly: [false, true]
91+
steps:
92+
- uses: actions/checkout@v4
93+
94+
- name: Install dependencies
95+
run: sudo apt-get update && sudo apt-get install -y cmake build-essential
96+
97+
- name: Configure CMake
98+
run: |
99+
mkdir build && cd build
100+
if [ "${{ matrix.cryptonly }}" = "true" ]; then
101+
cmake -DWOLFSSL_BAREMETAL=yes -DWOLFSSL_CRYPTONLY=yes -DWOLFSSL_EXAMPLES=no -DWOLFSSL_CRYPTOCB=yes -DCMAKE_C_FLAGS="-DWOLFSSL_USER_IO -DWOLFCRYPT_ONLY" ..
102+
else
103+
cmake -DWOLFSSL_BAREMETAL=yes -DWOLFSSL_EXAMPLES=no -DWOLFSSL_CRYPTOCB=yes -DCMAKE_C_FLAGS="-DWOLFSSL_USER_IO" ..
104+
fi
105+
106+
- name: Build
107+
run: cd build && cmake --build . -j$(nproc)
108+
109+
- name: Verify macro definitions
110+
run: |
111+
cd build
112+
cat > test_baremetal_defines.c <<'EOF'
113+
#include <wolfssl/options.h>
114+
#include <wolfssl/wolfcrypt/settings.h>
115+
#include <stdio.h>
116+
117+
int main() {
118+
int errors = 0;
119+
120+
#ifdef WOLFSSL_BAREMETAL
121+
printf("✓ WOLFSSL_BAREMETAL is defined\n");
122+
#else
123+
printf("✗ ERROR: WOLFSSL_BAREMETAL should be defined\n");
124+
errors++;
125+
#endif
126+
127+
#ifdef WOLFCRYPT_ONLY
128+
printf("✓ WOLFCRYPT_ONLY is defined\n");
129+
#ifdef NO_ASN_TIME
130+
printf("✓ NO_ASN_TIME is defined (expected with WOLFCRYPT_ONLY)\n");
131+
#else
132+
printf("✗ ERROR: NO_ASN_TIME should be defined when WOLFCRYPT_ONLY is set\n");
133+
errors++;
134+
#endif
135+
#else
136+
printf("✓ WOLFCRYPT_ONLY is NOT defined\n");
137+
#ifdef NO_ASN_TIME
138+
printf("✗ ERROR: NO_ASN_TIME should NOT be defined without WOLFCRYPT_ONLY\n");
139+
errors++;
140+
#else
141+
printf("✓ NO_ASN_TIME is NOT defined (expected without WOLFCRYPT_ONLY)\n");
142+
#endif
143+
#endif
144+
145+
return errors;
146+
}
147+
EOF
148+
# Key: -I. comes BEFORE -I.. so build/wolfssl/options.h is found first
149+
gcc -I. -I.. test_baremetal_defines.c -o test_baremetal_defines
150+
./test_baremetal_defines
151+

‎INSTALL‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -319,3 +319,46 @@ We also have vcpkg ports for wolftpm, wolfmqtt and curl.
319319

320320
Deprecated. wolfSSL now has its own XMMS/XMSS^MT implementation in
321321
wolfCrypt.
322+
323+
21. Building for Bare-Metal Embedded Systems
324+
325+
wolfSSL provides a simplified configuration for bare-metal embedded
326+
systems through the --enable-baremetal option. This configuration
327+
disables OS-dependent features and is suitable for microcontrollers
328+
and RTOS environments without POSIX support.
329+
330+
$ ./autogen.sh
331+
$ ./configure --enable-baremetal
332+
$ make
333+
334+
The --enable-baremetal option defines the following macros:
335+
336+
- SINGLE_THREADED: Disables multi-threading support
337+
- NO_DEV_RANDOM: Removes /dev/random dependency
338+
- NO_FILESYSTEM: Disables file system operations
339+
- NO_WRITEV: Disables writev() system call
340+
- NO_STDIO_FILESYSTEM: Removes stdio-based file I/O
341+
- WOLFSSL_NO_SOCK: Disables socket support
342+
- WOLFSSL_NO_GETPID: Removes getpid() dependency
343+
- NO_ASN_TIME: Conditionally defined when WOLFCRYPT_ONLY is also set
344+
(for systems without RTC to bypass certificate date checking)
345+
346+
For crypto-only builds (no TLS/SSL protocol layer), combine with
347+
--enable-cryptonly:
348+
349+
$ ./configure --enable-baremetal --enable-cryptonly
350+
351+
Important: Bare-metal systems must provide their own entropy source.
352+
You will need to implement wc_GenerateSeed() with platform-specific
353+
hardware RNG or define CUSTOM_RAND_GENERATE_BLOCK and implement
354+
wc_GenerateRand().
355+
356+
For CMake builds:
357+
358+
$ mkdir build && cd build
359+
$ cmake -DWOLFSSL_BAREMETAL=yes ..
360+
$ cmake --build .
361+
362+
Or with crypto-only:
363+
364+
$ cmake -DWOLFSSL_BAREMETAL=yes -DWOLFSSL_CRYPTONLY=yes ..

‎README.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,27 @@ https://www.wolfssl.com/docs/security-vulnerabilities/
287287
See INSTALL file for build instructions.
288288
More info can be found on-line at: https://wolfssl.com/wolfSSL/Docs.html
289289
290+
## Building
291+
292+
### Bare-Metal Embedded Systems
293+
294+
For bare-metal embedded systems (microcontrollers, RTOS without POSIX), use the `--enable-baremetal` configuration:
295+
296+
```bash
297+
./configure --enable-baremetal
298+
make
299+
```
300+
301+
This configuration disables OS-dependent features including file systems, sockets, threading, and process management. For crypto-only builds without the TLS protocol layer, add `--enable-cryptonly`:
302+
303+
```bash
304+
./configure --enable-baremetal --enable-cryptonly
305+
```
306+
307+
**Important:** You must provide a platform-specific entropy source by implementing `wc_GenerateSeed()` or defining `CUSTOM_RAND_GENERATE_BLOCK`.
308+
309+
See the INSTALL file for complete details.
310+
290311
# Resources
291312

292313
[wolfSSL Website](https://www.wolfssl.com/)

‎cmake/options.h.in‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -276,6 +276,8 @@ extern "C" {
276276
#cmakedefine WOLFSSL_ASIO
277277
#undef WOLFSSL_BASE64_ENCODE
278278
#cmakedefine WOLFSSL_BASE64_ENCODE
279+
#undef WOLFSSL_BAREMETAL
280+
#cmakedefine WOLFSSL_BAREMETAL
279281
#undef WOLFSSL_CAAM
280282
#cmakedefine WOLFSSL_CAAM
281283
#undef WOLFSSL_CERT_EXT

0 commit comments

Comments
 (0)