[DOCUMENTATION]

QWAMOS Technical Documentation

Welcome to the official QWAMOS documentation. This guide covers installation, architecture, security features, and development guidelines for the quantum-resistant mobile operating system.

What is QWAMOS?

QWAMOS (Qubes+Whonix Advanced Mobile OS) is a post-quantum secure, ARM64-native mobile hypervisor operating system. Unlike traditional Android ROMs or apps, QWAMOS runs directly on mobile hardware as the primary OS, providing hardware-level VM isolation for all activities.

Key Features:

Post-quantum cryptography (ML-DSA-87, Kyber-1024)
Hardware VM isolation for each app
Integrated Tor/I2P anonymous routing
Complete baseband isolation
Panic wipe with cryptographic data destruction
100% open source (GPL-3.0)

System Requirements

Hardware Requirements

          
            • Processor: ARM64 (ARMv8-A or newer)

            • RAM: Minimum 4GB, recommended 8GB+

            • Storage: Minimum 64GB, recommended 128GB+

            • Bootloader: Unlocked

            • Virtualization: Hardware virtualization support (ARM VHE)

Supported Devices

QWAMOS has been tested on the following devices:

Google Pixel 6/7/8 series
OnePlus 8T/9/10 series
Pine64 PinePhone Pro
Fairphone 4/5

⚠️ Warning: Installing QWAMOS will completely replace your existing OS. Ensure you have backups of all important data before proceeding.

Installation Guide

Prerequisites

Unlock your device bootloader
Install custom recovery (TWRP recommended)
Download QWAMOS release package
Verify signatures with ML-DSA-87

Installation Steps

1. Download and Verify

          
            # Download release package

            $ wget https://github.com/Dezirae-Stark/QWAMOS/releases/download/v2.0.1/qwamos-v2.0.1-arm64.zip

            $ wget https://github.com/Dezirae-Stark/QWAMOS/releases/download/v2.0.1/qwamos-v2.0.1-arm64.sig

            # Verify ML-DSA-87 signature

            $ python3 tools/crypto/verify_release.py \

              --package qwamos-v2.0.1-arm64.zip \

              --signature qwamos-v2.0.1-arm64.sig

2. Boot to Recovery

          
            # Reboot to recovery mode

            $ adb reboot recovery

            # Or use hardware keys:

            # Power + Volume Down (varies by device)

3. Install QWAMOS

          
            # In TWRP, select "Install"

            # Navigate to qwamos-v2.0.1-arm64.zip

            # Swipe to confirm installation

            # Installation takes 10-15 minutes

            # The installer will:

            # - Partition storage for hypervisor

            # - Install QWAMOS core system

            # - Configure secure boot

            # - Set up VM templates

Hypervisor Architecture

QWAMOS implements a Type-1 bare-metal hypervisor that runs directly on ARM64 hardware, providing complete isolation between guest VMs.

Core Components

Hardware Abstraction Layer Direct hardware access, interrupt handling, memory management

Microkernel Minimal privileged code, IPC, scheduling, security enforcement

VM Manager QEMU instances, resource allocation, device passthrough

Guest Operating Systems Android, GrapheneOS, Linux distributions, specialized VMs

Memory Isolation

Each VM operates in its own memory space with hardware-enforced boundaries:

          
            VM0: 0x0000000000000000 - 0x0000000100000000 (4GB)

            VM1: 0x0000000100000000 - 0x0000000200000000 (4GB)

            VM2: 0x0000000200000000 - 0x0000000300000000 (4GB)

            ...

            Hypervisor: 0xFFFFFFF000000000 - 0xFFFFFFFFFFFFFFFF (Reserved)

Post-Quantum Cryptography

QWAMOS integrates NIST-standardized post-quantum algorithms to protect against future quantum computer attacks.

ML-DSA-87 (Dilithium5)

Digital Signatures

Security Level: NIST Level 5 (256-bit classical security)
Public Key Size: 2,592 bytes
Signature Size: 4,627 bytes
Signing Time: ~1ms on ARM64

            
              from qwamos.crypto import MLDSASigner

              # Generate keypair

              signer = MLDSASigner()

              keypair = signer.generate_keypair()

              # Sign data

              message = b"Critical system update"

              signature = signer.sign(message, keypair.private_key)

              # Verify signature

              valid = signer.verify(message, signature, keypair.public_key)

              print(f"Signature valid: {valid}")

Kyber-1024

Key Encapsulation

Security Level: NIST Level 5
Public Key Size: 1,568 bytes
Ciphertext Size: 1,568 bytes
Shared Secret: 32 bytes

            
              from qwamos.crypto import KyberKEM

              # Key exchange

              kem = KyberKEM()

              alice_keys = kem.generate_keypair()

              # Bob encapsulates

              ciphertext, shared_secret_bob = kem.encapsulate(alice_keys.public_key)

              # Alice decapsulates

              shared_secret_alice = kem.decapsulate(ciphertext, alice_keys.private_key)

              assert shared_secret_alice == shared_secret_bob

Panic Wipe System

QWAMOS includes a hardware-level panic wipe system that can instantly destroy all encryption keys and sensitive data.

Trigger Methods

Triple Power Tap: Press power button 3 times rapidly
Custom Gesture: Configure in Settings → Security
Remote Trigger: Via secure management interface
Duress Password: Special password that triggers wipe

Wipe Process

          
            1. Interrupt all VM operations

            2. Overwrite key storage in secure element

            3. Zero out RAM contents

            4. Corrupt partition tables

            5. Overwrite first 10MB of each partition

            6. Trigger hardware reset

            Total time: < 3 seconds

⚠️ Critical: Panic wipe is irreversible. All data will be permanently destroyed with no possibility of recovery.

API Reference

VM Management API

Create VM

          
            POST /api/v1/vms

            {

              "name": "secure_browser",

              "template": "android-12",

              "memory": "2G",

              "cpus": 2,

              "network": "tor_only",

              "storage": {

                "size": "8G",

                "encryption": "chacha20-poly1305"

              }

            }

List VMs

          
            GET /api/v1/vms

            Response:

            [

              {

                "id": "vm-001",

                "name": "secure_browser",

                "state": "running",

                "memory_usage": "1.2G",

                "cpu_usage": "15%"

              }

            ]

Network Policy API

Set VM Network Policy

          
            PUT /api/v1/vms/{vm_id}/network-policy

            {

              "routing": "tor",

              "firewall_rules": [

                {

                  "direction": "outbound",

                  "protocol": "tcp",

                  "port": 443,

                  "action": "allow"

                }

              ],

              "dns": "dnscrypt"

            }

Troubleshooting

Common Issues

Boot Loop After Installation

Symptoms: Device restarts continuously after QWAMOS installation

Solution:

Boot to recovery mode
Check logs: cat /tmp/recovery.log
Verify bootloader compatibility
Re-flash with --force-partition flag

VM Won't Start

Error: "Failed to allocate memory for VM"

Solution:

            
              # Check memory allocation

              $ qwamos-cli memory status

              # Free up memory

              $ qwamos-cli vm stop unused_vm

              $ qwamos-cli memory compact

              # Retry with lower memory

              $ qwamos-cli vm start --memory 1G

Network Connection Issues

Symptoms: No internet in VM despite Tor running

Debug Steps:

            
              # Check Tor status

              $ qwamos-cli network tor status

              # View Tor logs

              $ qwamos-cli network tor logs

              # Test connectivity

              $ qwamos-cli network test --vm secure_browser

              # Reset network stack

              $ qwamos-cli network reset --confirm