Skip to content

Commit f059f7d

Browse files
neuromechanistneuromechanist
committed
Initial release of Secure LSL
Transparent encryption layer for Lab Streaming Layer using Ed25519 authentication and ChaCha20-Poly1305 encryption.
0 parents  commit f059f7d

2,325 files changed

Lines changed: 9197539 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
name: Secure LSL CI
2+
3+
on:
4+
push:
5+
branches: ['*']
6+
tags: ['*']
7+
pull_request:
8+
workflow_dispatch:
9+
inputs:
10+
cmake_extra:
11+
description: 'Extra CMake options'
12+
required: false
13+
default: ''
14+
15+
defaults:
16+
run:
17+
shell: bash
18+
19+
jobs:
20+
build:
21+
name: ${{ matrix.config.name }}
22+
runs-on: ${{ matrix.config.os }}
23+
strategy:
24+
fail-fast: false
25+
matrix:
26+
config:
27+
- name: "macOS-latest"
28+
os: "macos-latest"
29+
install_deps: "brew install libsodium"
30+
cmake_extra: ""
31+
- name: "ubuntu-24.04"
32+
os: "ubuntu-24.04"
33+
install_deps: "sudo apt-get update && sudo apt-get install -y libsodium-dev libpugixml-dev"
34+
cmake_extra: "-DLSL_BUNDLED_PUGIXML=OFF"
35+
- name: "ubuntu-22.04"
36+
os: "ubuntu-22.04"
37+
install_deps: "sudo apt-get update && sudo apt-get install -y libsodium-dev libpugixml-dev"
38+
cmake_extra: "-DLSL_BUNDLED_PUGIXML=OFF"
39+
40+
steps:
41+
- uses: actions/checkout@v4
42+
43+
- name: Install dependencies
44+
run: ${{ matrix.config.install_deps }}
45+
46+
- name: Configure CMake
47+
working-directory: liblsl
48+
run: |
49+
cmake --version
50+
cmake -S . -B build \
51+
-DCMAKE_BUILD_TYPE=Release \
52+
-DCMAKE_INSTALL_PREFIX=${PWD}/install \
53+
-DLSL_SECURITY=ON \
54+
-DLSL_SECURITY_TOOLS=ON \
55+
-DLSL_UNITTESTS=ON \
56+
-DLSL_BUILD_EXAMPLES=ON \
57+
-DCPACK_PACKAGE_DIRECTORY=${PWD}/package \
58+
-Dlslgitrevision=${{ github.sha }} \
59+
-Dlslgitbranch=${{ github.ref }} \
60+
${{ matrix.config.cmake_extra }} \
61+
${{ github.event.inputs.cmake_extra }}
62+
63+
- name: Build
64+
working-directory: liblsl
65+
run: cmake --build build --target install --config Release -j
66+
67+
- name: Print network config
68+
run: |
69+
if command -v ifconfig &> /dev/null; then ifconfig; fi
70+
if command -v ip &> /dev/null; then
71+
ip link
72+
ip addr
73+
fi
74+
75+
- name: Run security tests
76+
working-directory: liblsl
77+
run: install/bin/lsl_test_internal "[security]" --order rand --wait-for-keypress never --durations yes
78+
timeout-minutes: 5
79+
80+
- name: Run internal tests
81+
working-directory: liblsl
82+
run: install/bin/lsl_test_internal --order rand --wait-for-keypress never --durations yes
83+
timeout-minutes: 5
84+
if: ${{ success() || failure() }}
85+
86+
- name: Run exported tests
87+
working-directory: liblsl
88+
run: install/bin/lsl_test_exported --order rand --wait-for-keypress never --durations yes
89+
timeout-minutes: 5
90+
if: ${{ success() || failure() }}
91+
92+
- name: Test security tools
93+
working-directory: liblsl
94+
env:
95+
LSLAPICFG: /tmp/test_lsl_api.cfg
96+
run: |
97+
echo "Testing lsl-keygen..."
98+
install/bin/lsl-keygen --help
99+
# Use --insecure for CI (no TTY for passphrase prompt)
100+
install/bin/lsl-keygen --force --insecure
101+
echo "Testing lsl-config..."
102+
install/bin/lsl-config --check
103+
install/bin/lsl-config --show-public
104+
105+
- name: Upload install artifacts
106+
uses: actions/upload-artifact@v4
107+
with:
108+
name: build-${{ matrix.config.name }}
109+
path: liblsl/install
110+
111+
- name: Package
112+
working-directory: liblsl
113+
run: |
114+
cmake --build build --target package --config Release -j
115+
cmake -E remove_directory package/_CPack_Packages || true
116+
117+
- name: Upload package artifacts
118+
uses: actions/upload-artifact@v4
119+
with:
120+
name: pkg-${{ matrix.config.name }}
121+
path: liblsl/package
122+
123+
docs:
124+
name: "Build Documentation"
125+
runs-on: ubuntu-latest
126+
steps:
127+
- uses: actions/checkout@v4
128+
129+
- name: Install Doxygen
130+
run: sudo apt-get update && sudo apt-get install -y doxygen
131+
132+
- name: Set up Python
133+
uses: actions/setup-python@v5
134+
with:
135+
python-version: '3.12'
136+
137+
- name: Install docs dependencies
138+
run: pip install -r docs/requirements.txt
139+
140+
- name: Build documentation
141+
run: mkdocs build --strict

‎.github/workflows/docs.yml‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
name: Deploy Docs to GitHub Pages
2+
3+
on:
4+
push:
5+
branches: [main]
6+
workflow_dispatch:
7+
8+
permissions:
9+
contents: read
10+
pages: write
11+
id-token: write
12+
13+
concurrency:
14+
group: "pages"
15+
cancel-in-progress: false
16+
17+
jobs:
18+
build:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- uses: actions/checkout@v4
22+
23+
- name: Install Doxygen
24+
run: sudo apt-get update && sudo apt-get install -y doxygen
25+
26+
- name: Set up Python
27+
uses: actions/setup-python@v5
28+
with:
29+
python-version: '3.12'
30+
31+
- name: Install dependencies
32+
run: pip install -r docs/requirements.txt
33+
34+
- name: Build documentation
35+
run: mkdocs build
36+
37+
- name: Upload artifact
38+
uses: actions/upload-pages-artifact@v3
39+
with:
40+
path: site
41+
42+
deploy:
43+
environment:
44+
name: github-pages
45+
url: ${{ steps.deployment.outputs.page_url }}
46+
runs-on: ubuntu-latest
47+
needs: build
48+
steps:
49+
- name: Deploy to GitHub Pages
50+
id: deployment
51+
uses: actions/deploy-pages@v4

‎.gitignore‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Development context (not distributed)
2+
CLAUDE.md
3+
.rules/
4+
.context/
5+
.claude/
6+
.serena/
7+
internal-docs/
8+
9+
# IDE and editors
10+
.vscode/
11+
.idea/
12+
.cursor/
13+
*.swp
14+
*.swo
15+
.DS_Store
16+
17+
# Environment and secrets
18+
.env
19+
.env.local
20+
.env.*.local
21+
22+
# Python
23+
__pycache__/
24+
*.py[cod]
25+
*$py.class
26+
*.so
27+
.Python
28+
build/
29+
develop-eggs/
30+
dist/
31+
eggs/
32+
.eggs/
33+
lib/
34+
lib64/
35+
parts/
36+
sdist/
37+
var/
38+
wheels/
39+
*.egg-info/
40+
.installed.cfg
41+
*.egg
42+
MANIFEST
43+
.pytest_cache/
44+
.coverage
45+
htmlcov/
46+
.mypy_cache/
47+
.ruff_cache/
48+
49+
# Virtual environments
50+
venv/
51+
ENV/
52+
env/
53+
.venv/
54+
55+
# C++ build artifacts
56+
build/
57+
cmake-build-*/
58+
*.o
59+
*.a
60+
*.so
61+
*.dylib
62+
*.dll
63+
*.lib
64+
*.obj
65+
*.exe
66+
CMakeFiles/
67+
CMakeCache.txt
68+
cmake_install.cmake
69+
Makefile
70+
compile_commands.json
71+
72+
# Testing
73+
*.log
74+
logs/
75+
test_output/
76+
77+
# Temporary files
78+
tmp/
79+
temp/
80+
*.tmp
81+
*.bak
82+
*~
83+
84+
# Documentation build
85+
docs/_build/
86+
site/
87+
88+
# Package distribution
89+
*.tar.gz
90+
*.zip
91+
92+
# Coverage reports
93+
coverage/
94+
*.gcov
95+
*.gcda
96+
*.gcno
97+
liblsl-Matlab/

‎CHANGELOG.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Changelog
2+
3+
All notable changes to Secure LSL will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## [1.16.1-secure.1.0.0-alpha] - 2025-12-07
9+
10+
### Added
11+
- Initial security layer implementation
12+
- Ed25519 device authentication
13+
- ChaCha20-Poly1305 authenticated encryption
14+
- X25519 + HKDF session key derivation
15+
- Replay attack prevention with nonce tracking
16+
- Security configuration via lsl_api.cfg [security] section
17+
- Key generation tool: `lsl-keygen`
18+
- Configuration validator: `lsl-config`
19+
- Version query API:
20+
- `lsl_is_secure_build()` - detect secure library at runtime
21+
- `lsl_base_version()` - get upstream liblsl version
22+
- `lsl_security_version()` - get security layer version
23+
- `lsl_full_version()` - get combined version string
24+
- C++ wrappers for all version functions
25+
- Renamed binary to `liblsl-secure` to prevent confusion
26+
- MkDocs documentation site with security guides
27+
- Cross-platform test suite (Python, MATLAB, C++)
28+
- Interoperability tests between all language bindings
29+
30+
### Changed
31+
- Library output name: `liblsl` -> `liblsl-secure`
32+
- Version string includes security info in `lsl_library_info()`
33+
34+
### Security
35+
- All data encryption uses libsodium (NIST-validated)
36+
- Constant-time cryptographic operations
37+
- Secure memory zeroing for sensitive data
38+
- Unanimous security enforcement (secure outlets reject insecure inlets and vice versa)
39+
40+
## Version Format
41+
42+
Secure LSL uses dual versioning:
43+
- **Base version**: Tracks upstream liblsl (e.g., 1.16.1)
44+
- **Security version**: Tracks security layer (e.g., 1.0.0)
45+
- **Combined**: `{base}-secure.{security}[-stage]`
46+
47+
Stages: `alpha` -> `beta` -> `rc.N` -> (stable)

0 commit comments

Comments
 (0)