m³OS docs GitHub

Phase 42

Crypto Primitives

The OS has a cryptography library providing hash functions, symmetric encryption, and asymmetric key operations. This is the foundation layer that SSH (Phase 43) and future security features build upon.

Complete

Learning goal

Understand the core cryptographic building blocks: hashing, symmetric encryption, asymmetric encryption, key exchange.

Category

foundations

Why this phase matters

The OS has a cryptography library providing hash functions, symmetric encryption, and asymmetric key operations. This is the foundation layer that SSH (Phase 43) and future security features build upon.

How it works in m3OS

The roadmap entry defines the learning scope for this phase; a deeper implementation doc has not been matched yet.

How it builds on earlier phases

This phase builds on Expanded Coreutils and turns that foundation into Crypto Primitives.

Implementation outline

  • Add RustCrypto crate dependencies to the workspace (sha2, hmac, hkdf, chacha20poly1305, aes, ctr, ed25519-dalek, x25519-dalek, rand_chacha).
  • Create userspace/crypto-lib/ crate wrapping the RustCrypto APIs.
  • Implement CSPRNG seeded from getrandom syscall.
  • Verify SHA-256 produces correct test vectors inside the OS.
  • Verify HMAC-SHA-256 and HKDF with test vectors.
  • Verify ChaCha20-Poly1305 and AES-256 with test vectors.
  • Verify Ed25519 sign/verify with test vectors.
  • Verify X25519 key exchange with test vectors.
  • Build sha256sum utility.
  • Build genkey utility.
  • Run full integration test inside QEMU.
  • Document the library’s API for use by the SSH server in Phase 43.

Task progress snapshot

88 of 88 tracked tasks are complete.

Documentation targets

  • Documentation deliverables have not been listed yet.

Deferred follow-on work

  • Hardware-accelerated crypto (AES-NI)
  • TLS/SSL protocol implementation (Phase 43+ / future)
  • Certificate handling (X.509)
  • RSA implementation
  • Disk encryption
  • Key management infrastructure (keyring, agent)

Source materials

Important code

Code spotlight cards

Code spotlight

Create `userspace/crypto-lib/` crate

userspace/crypto-lib/Cargo.toml See file

crypto operations. Userspace binaries (sha256sum, genkey, SSH in Phase 43) depend. Why it matters: A dedicated library crate provides a single entry point for all. Focus on `crypto-lib` and `sha256sum` in `userspace/crypto-lib/Cargo.toml` while you trace the snippet.

View on GitHub

Code spotlight

Define crypto-lib public API surface

userspace/crypto-lib/src/lib.rs See file

future phases to consume crypto operations without understanding RustCrypto internals. Why it matters: A well-defined API boundary makes it easy for Phase 43 (SSH) and. Focus on `userspace/crypto-lib/src/lib.rs` while you trace the snippet.

View on GitHub

Code spotlight

Implement CSPRNG initialization from getrandom

userspace/crypto-lib/src/random.rs L14-L22

needs a reliable source of randomness. The CSPRNG bridges the kernel's getrandom. Why it matters: Every cryptographic operation that generates keys, nonces, or IVs. Focus on `CsprngState` and `csprng_init` in `userspace/crypto-lib/src/random.rs` while you trace the snippet.

/// Cryptographically secure pseudorandom number generator state.
pub struct CsprngState {
    rng: ChaCha20Rng,
}

/// Initialize the CSPRNG by reading 32 bytes from the kernel's `getrandom` syscall.
///
/// The seed is zeroed from stack memory after initializing the RNG.
pub fn csprng_init() -> Result<CsprngState, CryptoError> {

View on GitHub

Key files

  • userspace/crypto-lib/ — A no_std-compatible Rust library crate that re-exports RustCrypto primitives with a

How real OSes differ

  • Real systems use hardware-accelerated crypto (AES-NI, SHA extensions) for performance
  • OpenSSL or LibreSSL serve as the standard crypto library (huge, complex, battle-tested)
  • Linux has a kernel-level crypto API (crypto subsystem) for disk encryption, IPsec, etc.
  • HSMs or TPMs handle secure key storage
  • Certificate authorities and X.509 chains provide identity verification at scale

Success criteria

  • SHA-256 of known test vectors matches expected output.
  • HMAC-SHA-256 of known test vectors matches expected output.
  • HKDF key derivation produces expected output for RFC 5869 test vectors.
  • Ed25519 keypair generation, signing, and verification work correctly.
  • X25519 key exchange produces matching shared secrets on both sides.
  • ChaCha20-Poly1305 encrypt/decrypt round-trips correctly with RFC 8439 test vectors.
  • AES-256-CTR encrypt/decrypt round-trips correctly.
  • `sha256sum /bin/tcc` produces a stable, correct hash.
  • `genkey` creates an Ed25519 keypair saved to files.
  • CSPRNG produces non-repeating output seeded from `getrandom`.

Related phases

Keep exploring the roadmap

Phase 41

Complete

Expanded Coreutils

The OS ships with a comprehensive set of Unix utilities sufficient for daily development work. Moving beyond the minimal set from Phase 14, this phase adds text processing, file inspection, and system administration tools that developers expect.

productivity 1 prerequisite(s)

Phase 42

Complete

Async Executor

Learn how Async Executor fits into m3OS.

infrastructure 1 prerequisite(s)