How jedisct1/libsodium works
Project Type and Purpose
• Project type: Cross-platform cryptographic library (C language).
• Purpose: Provide easy-to-use cryptographic primitives (encryption/decryption, signatures, hashing, password hashing, random number generation) and build/publish them across many platforms.
File Structure
• Top-level “src” directory with subdirectories for each crypto primitive (crypto_aead, crypto_auth, crypto_box, crypto_core, etc.).
• “include” directory exposing public API headers (sodium.h and per-module headers).
• Build/config layers:
– Autotools files (configure.ac, Makefile.am).
– Platform-specific build scripts under “builds/” (MSVC-projects), “dist-build/” (Android, Emscripten, WASM, iOS/macOS), and “build.zig”.
– CI configurations in “.github/workflows”, “azure-pipelines.yml”, “appveyor.yml”.
• “test” directory: test harnesses for each primitive (reference implementations and expected outputs).
• Packaging: “packaging/dotnet-core” for .NET wrappers.
README for Additional Insights
• Confirms it’s an API-focused library, not an application.
• Emphasizes cross-platform portability and API stability.
Main Components
a. Public API Layer (“include/” – sodium.h, crypto_* headers)
b. Core Crypto Engine (“src/libsodium/” + per‐algorithm subfolders)
c. Build System Layer
• Autotools Build (configure, Makefile.am)
• Platform/Language Bindings
– MSVC (*.vcxproj under builds/msvc and regen-msvc)
– Emscripten/WASM and Zig (build.zig, dist-build scripts)
– .NET-Core pkgproj (packaging/dotnet-core)
d. Test Harness (“test/” – default and quirks tests)
e. Continuous Integration (GitHub Actions, Azure Pipelines, Appveyor)
f. External Consumers (applications linking against the library, language bindings like Python, Go, Node.js – represented abstractly)
Relationships and Data Flows
• Build System Layer compiles the Core Crypto Engine and Public API into a library binary (.dll, .so, .a, .lib).
• The Test Harness drives the Public API and validates outputs from Core Crypto Engine.
• CI pipelines invoke the Build System for each target platform, then run the Test Harness.
• External Consumers link against the compiled library and include headers from the Public API Layer.
Architectural Patterns and Design Principles
• Layered modular design: separation of public API vs. implementation vs. build vs. tests.
• Plugin-like modules: each crypto algorithm lives in its own folder and is registered via common build files.
• Portability abstraction: platform-specific code is isolated in build scripts and conditional implementations.
• Reference implementations vs. optimized versions (e.g., AESNI, ARM Crypto, SSE).
Technologies, Frameworks, Libraries
• C99 source code (portable crypto implementations, reference & optimized variants).
• Autotools (configure.ac, Makefile.am) for UNIX builds.
• MSBuild / Visual Studio projects for Windows.
• Zig build (build.zig) and Emscripten for WASM.
• Continuous Integration: GitHub Actions, Azure Pipelines, Appveyor.
Elements
– API calls → Core modules
– Build scripts → compiled library
– Tests → API → Core modules
– CI → Build & Tests
– Consumers → library
– Rectangles for code components
– Clouds for CI services