ObsidianCrypt: Post-Quantum Secure Note Synchronization

Secure your Obsidian vaults with post-quantum cryptography and Windows Hello biometric authentication.

Overview

ObsidianCrypt provides transparent, post-quantum resistant encryption for Obsidian vaults synchronized via Git. Files are automatically encrypted before commit and decrypted on checkout, with no impact on your normal Obsidian workflow.

Key Features

• Post-Quantum Security: ML-KEM-1024 key encapsulation with AES-256-GCM-SIV
• Windows Hello Integration: Biometric authentication with TPM key derivation
• Transparent Git Integration: Clean/smudge filters with meaningful diffs
• Selective Encryption: File-level control via .gitattributes patterns
• Forward Secrecy: Per-file ephemeral keys with unlinkable encryption

Architecture

Current Implementation (v1.0)

Cryptographic Stack:

• Key Derivation: HKDF-SHA256 from Windows Hello biometric seed
• Asymmetric: ML-KEM-1024 for quantum-resistant key encapsulation
• Symmetric: AES-256-GCM-SIV via AesGcmSiv.Net for nonce-misuse resistance
• Authentication: Windows Hello + TPM attestation

System Components:

• Windows Service: Background authentication and crypto operations
• CLI Client: Command-line interface for testing and management
• Git Filters: Transparent encryption/decryption during git operations
• Obsidian Plugin: Vault management and service monitoring
• Named Pipe IPC: Secure service communication with protocol validation

Future Roadmap (v2.0+)

Enhanced Security:

• TPM Key Sealing: Store ML-KEM private keys sealed in TPM
• Hardware Attestation: TPM-based proof of platform integrity
• Vault Sharing: Multi-user encrypted vaults with key distribution
• Commit Signing: Post-quantum signatures tied to user identity

Advanced Features:

• Cross-Platform: macOS (Touch ID) and Linux (FIDO2) support
• Streaming Encryption: Efficient handling of large attachments
• Backup Recovery: Secure key escrow with split secrets
• Enterprise Management: Centralized policy and key management

Security Model

Threat Protection

Current (v1.0):

• ✅ Quantum adversaries (>128-bit post-quantum security)
• ✅ Physical device access (TPM-derived keys)
• ✅ Network interception (repository contains only encrypted data)
• ✅ Biometric spoofing (Windows Hello liveness detection)
• ✅ Nonce misuse attacks (GCM-SIV deterministic encryption)

Future (v2.0+):

• 🔄 Advanced persistent threats (TPM attestation)
• 🔄 Insider threats (hardware-backed audit logs)
• 🔄 Supply chain attacks (verified boot integration)

Trust Boundaries

1. Hardware: TPM provides root of trust for key material
2. Platform: Windows Hello handles biometric authentication
3. Service: Minimal attack surface with session-based keys
4. Git: Repository contains only post-quantum encrypted content

Installation

Prerequisites

• Windows 10/11 with Windows Hello biometric authentication
• TPM 2.0 chip (required for hardware key derivation)
• Git 2.30+ with filter support
• Obsidian 1.0+ for plugin integration
• .NET 9.0 Runtime (for service and CLI)

Note: AES-256-GCM-SIV cryptography is provided by the AesGcmSiv.Net NuGet package with no external dependencies.

Quick Start

Option 1: Winget Installation (Recommended)

# Install via Windows Package Manager
winget install ObsidianCrypt.ObsidianCrypt

# Verify installation
ObsidianCrypt.Client.exe status
ObsidianCrypt.Client.exe test

Option 2: Manual Installation

# 1. Download and run the MSI installer as Administrator
# 2. Verify service is running
.\scripts\run-service.ps1 -Status

# 3. Test the installation
ObsidianCrypt.Client.exe status
ObsidianCrypt.Client.exe test

**Note**: The CLI client is self-contained and includes all required dependencies.

# 4. Configure git filters for your vault
cd C:\Users\YourName\Documents\ObsidianVault
git config filter.obsidian-crypt.clean 'powershell -File "C:\Program Files\ObsidianCrypt\GitFilters\obsidian-clean.ps1"'

# 5. Install Obsidian plugin (optional)
# The plugin is distributed separately and should be installed directly in Obsidian
# from the repository: https://github.com/willmortimer/ObsidianCrypt
git config filter.obsidian-crypt.smudge 'powershell -File "C:\Program Files\ObsidianCrypt\GitFilters\obsidian-smudge.ps1"'
git config diff.obsidian-decrypt.textconv 'powershell -File "C:\Program Files\ObsidianCrypt\GitFilters\obsidian-decrypt.ps1"'

# 5. Configure encryption patterns
echo "*.md filter=obsidian-crypt diff=obsidian-decrypt" >> .gitattributes
echo "*.canvas filter=obsidian-crypt diff=obsidian-decrypt" >> .gitattributes

# 6. Install Obsidian plugin (optional)
cp -r obsidian-plugin\ "C:\Users\YourName\AppData\Roaming\obsidian\plugins\obsidian-crypt\"

Usage

Basic Workflow

1. Setup: Install service and configure git filters
2. Authenticate: Windows Hello prompts appear during git operations
3. Work Normally: Obsidian sees decrypted files, git stores encrypted content
4. Collaborate: Share encrypted repositories without exposing content

CLI Commands

# Check service status and connectivity
ObsidianCrypt.Client.exe status

# Test encryption/decryption roundtrip
ObsidianCrypt.Client.exe test --text "Hello, World!" --path "test.md"

# Encrypt a file
ObsidianCrypt.Client.exe encrypt --input plaintext.md --output encrypted.bin --path "notes/file.md"

# Decrypt a file
ObsidianCrypt.Client.exe decrypt --input encrypted.bin --output decrypted.md --path "notes/file.md"

# Use with pipes (stdin/stdout)
echo "Secret content" | ObsidianCrypt.Client.exe encrypt --path "secret.md" > encrypted.bin
ObsidianCrypt.Client.exe decrypt --path "secret.md" < encrypted.bin

Service Management

# Development mode (console)
.\scripts\run-service.ps1

# Install as Windows service
.\scripts\run-service.ps1 -Install -Start

# Service control
.\scripts\run-service.ps1 -Stop
.\scripts\run-service.ps1 -Start
.\scripts\run-service.ps1 -Restart
.\scripts\run-service.ps1 -Status

# Production installer
.\deployment\service-installer.ps1 -Action Install
.\deployment\service-installer.ps1 -Action Uninstall

File Selection

Control which files are encrypted via .gitattributes:

# Encrypt all notes and canvases
*.md filter=obsidian-crypt diff=obsidian-decrypt
*.canvas filter=obsidian-crypt diff=obsidian-decrypt

# Encrypt private directories
private/** filter=obsidian-crypt diff=obsidian-decrypt
personal/** filter=obsidian-crypt diff=obsidian-decrypt

# Exclude configuration and public files
.obsidian/** -filter
README.md -filter
public/** -filter

Viewing Encrypted Content

# Git diffs show decrypted content automatically
git diff HEAD~1 notes/important.md

# View historical versions
git show HEAD~5:notes/important.md

# Log with content changes
git log -p --follow notes/important.md

Technical Details

Build System Architecture

MSBuild Integration:

• AES-GCM-SIV: Integrated via AesGcmSiv.Net NuGet package
• Dynamic Loading: Runtime library resolution with multiple fallback paths
• Path Resolution: MSBuild-generated constants eliminate hardcoded paths
• Cross-Platform: Library name detection for Windows/Linux/macOS
• Deployment Ready: Self-contained packages with all dependencies

Key Components:

• src/ObsidianCrypt.Crypto/HKDFSHA256.cs: HKDF key derivation wrapper
• src/ObsidianCrypt.Crypto/PQCrypto.cs: Post-quantum crypto implementation
• tests/Integration.Tests/TestPaths.targets: Automated path generation
• All .csproj files: Integrated MSBuild targets for consistent builds

Cryptographic Implementation

Key Derivation Flow:

1. Windows Hello biometric authentication
2. TPM-attested seed derivation
3. HKDF-SHA256 expansion to crypto keys
4. Per-file ML-KEM ephemeral key generation

Encryption Process:

1. Generate random ephemeral key
2. Encapsulate with ML-KEM-1024 public key
3. Derive file key from KEM shared secret
4. Encrypt with AES-256-GCM-SIV (deterministic nonce)
5. Sign entire structure with ML-DSA-87

File Format:

[Version: 1 byte]
[Algorithm ID: 1 byte] 
[KEM Ciphertext: 1568 bytes]
[GCM-SIV Nonce: 12 bytes]
[Encrypted Data: variable]
[Auth Tag: 16 bytes]
[ML-DSA Signature: 4627 bytes]
[Metadata: variable]

Performance Characteristics

• Encryption: ~50MB/s (AES-256-GCM-SIV hardware acceleration via AesGcmSiv.Net)
• Key Operations: ~1ms (ML-KEM-1024 encapsulation)
• Authentication: ~500ms (Windows Hello biometric verification)
• File Overhead: ~6.3KB constant + 0.1% size increase
• Service Startup: ~2-3 seconds (including TPM initialization)
• Memory Usage: ~15-25MB resident (scales with concurrent operations)
• Library Loading: ~20ms (AesGcmSiv.Net static initialization)

Development

Building from Source

# Clone repository
git clone https://github.com/willmortimer/ObsidianCrypt.git
cd ObsidianCrypt

# Full build with tests (includes AesGcmSiv.Net integration)
.\scripts\build.ps1

# Build specific configuration
.\scripts\build.ps1 -Configuration Release -Verbose

# Run tests with coverage
.\scripts\test.ps1 -Coverage

# Run specific tests
.\scripts\test.ps1 -Filter "PQCrypto*"

# Package for deployment (self-contained with dependencies)
.\scripts\package.ps1

MSBuild Integration: The build system automatically handles AesGcmSiv.Net package integration with no external dependencies.

Development Setup

# Initial development setup
.\scripts\dev-setup.ps1

# Run service in development mode
.\scripts\run-service.ps1

# Build Obsidian plugin
cd obsidian-plugin
pnpm install
pnpm run dev

Path Resolution: All components now use MSBuild-generated paths, eliminating hardcoded absolute paths and improving portability.

Testing

# Unit tests (crypto operations with AesGcmSiv.Net)
dotnet test tests\ObsidianCrypt.Crypto.Tests

# Integration tests (requires running service)
dotnet test tests\ObsidianCrypt.Service.Tests

# End-to-end tests (CLI and git workflow with MSBuild paths)
dotnet test tests\Integration.Tests

# Run all tests with service dependency check
.\scripts\test.ps1

Test Improvements:

• Crypto tests now use AesGcmSiv.Net for simplified and reliable testing
• Integration tests use MSBuild-generated paths for CLI client location
• All tests are now portable and work across different development environments

Contributing

1. Security Issues: Report privately via [email protected]
2. Feature Requests: Open GitHub issue with detailed use case
3. Pull Requests: Include tests and documentation updates
4. Code Style: Follow .NET coding conventions and security best practices

Security Considerations

Operational Security

• Key Material: Never persisted to disk, exists only in memory during sessions
• Service Isolation: Runs with minimal privileges, automatic restart clears state
• Audit Logging: Authentication attempts and crypto operations logged
• Emergency Decrypt: Administrative override requires elevated privileges

Known Limitations

• Platform Dependency: Currently Windows-only (macOS/Linux in roadmap)
• Hardware Requirements: Requires TPM 2.0 and biometric authentication
• Network Transparency: Encrypted content visible in git repositories
• Key Recovery: No key escrow mechanism (by design)
• Deployment: Requires .NET 8.0 Runtime (self-contained option available)

Cryptographic Assumptions

• Post-Quantum Security: Based on lattice problems (ML-KEM) and hash security
• Hardware Trust: TPM provides secure key derivation and attestation
• Implementation Security: AesGcmSiv.Net provides constant-time operations
• Protocol Security: Authenticated encryption prevents tampering

License

MIT License - see LICENSE file for details.

Troubleshooting

Common Issues

Service won't start:

# Check Windows Hello is configured
# Verify TPM 2.0 is enabled in BIOS
# Run as Administrator:
.\scripts\run-service.ps1 -Status

Git filters not working:

# Verify service is running
ObsidianCrypt.Client.exe status

# Check git filter configuration
git config --list | findstr obsidian-crypt

# Test filters manually
echo "test" | powershell -File "C:\Program Files\ObsidianCrypt\GitFilters\obsidian-clean.ps1"

CLI connection timeouts:

# Check if service is running
net start | findstr ObsidianCrypt

# Restart service
net stop ObsidianCrypt
net start ObsidianCrypt

Performance Tuning

• Large files: Use streaming for files >10MB
• Batch operations: Process multiple files in single session
• Memory usage: Service automatically manages crypto key lifecycle

Support

• Documentation: CLAUDE.md for development guidance
• Architecture: See README.md Technical Details section
• Security Model: Review Security Considerations above
• Issues: GitHub issue tracker
• Development: See CLAUDE.md for build instructions