Skip to content

Latest commit

 

History

History
176 lines (135 loc) · 16.7 KB

sec-design.md

File metadata and controls

176 lines (135 loc) · 16.7 KB

Project Design Document: MMKV - Mobile Key-Value Storage Framework

Project Name: MMKV - Mobile Key-Value Storage Framework

Project Repository: https://github.com/tencent/mmkv

Document Version: 1.1 Date: 2023-10-27 Author: AI Software Architect

1. Introduction

This document provides a detailed design overview of the MMKV (Mobile Key-Value) storage framework developed by Tencent. MMKV is engineered as a high-performance, efficient key-value storage solution tailored for mobile platforms, specifically Android and iOS. It achieves superior performance compared to traditional mobile storage mechanisms like SharedPreferences (Android) and UserDefaults (iOS) by leveraging memory mapping (mmap) and Protocol Buffers (protobuf).

The primary purpose of this design document is to offer a clear and comprehensive understanding of MMKV's architecture, its constituent components, and the flow of data within the system. This document is specifically intended to serve as a foundational resource for subsequent threat modeling activities, enabling security professionals to effectively identify potential security vulnerabilities and design appropriate mitigation strategies.

2. Project Overview

MMKV is designed as a robust replacement for SharedPreferences on Android and UserDefaults on iOS, focusing on delivering:

  • Exceptional Performance: Employs mmap for memory-mapped file operations, significantly reducing disk I/O overhead and enabling rapid read and write operations.
  • Robust Concurrency Support: Architected for safe multi-process and multi-thread access, guaranteeing data consistency and preventing data corruption under concurrent load.
  • Durable Data Persistence: Data is persistently stored on disk, ensuring data durability and availability even after application termination, system restarts, or device reboots.
  • Developer-Friendly API: Presents a simple and intuitive API, closely mirroring SharedPreferences/UserDefaults, facilitating easy adoption and integration for developers.
  • Guaranteed Data Integrity: Utilizes protobuf for data serialization, ensuring data integrity, schema evolution compatibility, and efficient data encoding.
  • Optional Data Encryption at Rest: Offers optional encryption of data at rest to protect sensitive information stored within MMKV.

3. System Architecture

MMKV's architecture is composed of several key components working in concert. The high-level architecture is depicted below:

graph LR
    subgraph "Application Process"
        "A[\"Application Code\"]" --> "B[\"MMKV Instance\"]";
    end
    "B" --> "C[\"MMKV Core Library\"]";
    "C" --> "D[\"mmap Manager\"]";
    "C" --> "E[\"Protobuf Serializer/Deserializer\"]";
    "C" --> "F[\"Lock Manager\"]";
    "D" --> "G[\"Data File\"]";
    "F" --> "G";
    "G" --> "H[\"File System\"]";

    classDef component fill:#ccf,stroke:#333,stroke-width:2px;
    classDef submodule fill:#eee,stroke:#333,stroke-width:2px;
    class "B", "C" component;
    class "D", "E", "F", "G", "H" submodule;
Loading

Component Descriptions:

  • "Application Code": Represents the application's code that interacts with the MMKV library to perform key-value data storage and retrieval operations. This is the primary interface point for developers using MMKV.
  • "MMKV Instance": Serves as the main API entry point for application developers. It exposes methods for setting and retrieving values of various data types (integer, string, boolean, etc.). Typically, each instance maps to a distinct data file, allowing for data separation and organization.
  • "MMKV Core Library": The central processing unit of MMKV, responsible for managing all underlying operations and coordinating the interactions between other components. It orchestrates the mmap manager, protobuf serializer/deserializer, and lock manager to fulfill data storage and retrieval requests.
  • "mmap Manager": Handles the memory mapping of the "Data File". It creates and manages an in-memory view of the file, enabling direct memory access for both read and write operations. This memory mapping is a key factor in MMKV's high performance.
  • "Protobuf Serializer/Deserializer": Responsible for the efficient serialization of data into the Protocol Buffers format before writing to the "Data File" and deserializing data from protobuf format when reading. Protobuf ensures data integrity, efficient encoding, and supports schema evolution, allowing for future data structure changes without breaking compatibility.
  • "Lock Manager": Implements concurrency control mechanisms to ensure data consistency and prevent corruption when multiple processes or threads attempt to access the same MMKV instance concurrently. It typically utilizes file locks provided by the operating system to synchronize access to the "Data File".
  • "Data File": The persistent storage file residing on disk where MMKV stores the key-value data. This file is memory-mapped by the "mmap Manager" for efficient access.
  • "File System": Represents the underlying operating system's file system, which is responsible for managing the physical storage of files and handling file access requests. MMKV relies on the file system for persistent storage of the "Data File".

4. Data Flow

The following diagrams illustrate the data flow for both write and read operations within MMKV, providing a step-by-step view of how data is processed:

graph LR
    subgraph "Write Operation"
        "WA[\"Application Write Request\"]" --> "WB[\"MMKV Instance (Write API)\"]";
        "WB" --> "WC[\"MMKV Core Library\"]";
        "WC" --> "WD[\"Protobuf Serializer\"]";
        "WD" --> "WE[\"mmap Manager (Write to Memory Map)\"]";
        "WE" --> "WF[\"Data File (Memory Mapped)\"]";
        "WF" --> "WG[\"File System (Disk Persistence)\"]";
    end

    subgraph "Read Operation"
        "RA[\"Application Read Request\"]" --> "RB[\"MMKV Instance (Read API)\"]";
        "RB" --> "RC[\"MMKV Core Library\"]";
        "RC" --> "RD[\"mmap Manager (Read from Memory Map)\"]";
        "RD" --> "RE[\"Data File (Memory Mapped)\"]";
        "RE" --> "RF[\"Protobuf Deserializer\"]";
        "RF" --> "RG[\"Return Data to Application\"]";
    end

    classDef component fill:#ccf,stroke:#333,stroke-width:2px;
    classDef submodule fill:#eee,stroke:#333,stroke-width:2px;
    class "WB", "WC", "RB", "RC" component;
    class "WD", "WE", "WF", "WG", "RF", "RD", "RE", "RG" submodule;
Loading

Data Flow Descriptions:

  • Write Operation:

    1. "Application Write Request": The application initiates a request to write data through the MMKV Instance API (e.g., mmkv.putString("key", "value")).
    2. "MMKV Instance (Write API)": The MMKV Instance receives the write request and forwards it to the Core Library.
    3. "MMKV Core Library": The Core Library processes the request, preparing the data for serialization and storage.
    4. "Protobuf Serializer": The Protobuf Serializer serializes the data (key and value) into the efficient Protocol Buffers binary format.
    5. "mmap Manager (Write to Memory Map)": The mmap Manager receives the serialized data and writes it directly into the memory-mapped region of the "Data File". This write operation is performed in memory.
    6. "Data File (Memory Mapped)": The "Data File" in memory is updated with the new data. Because it's memory-mapped, these changes are eventually synchronized to the physical disk by the operating system.
    7. "File System (Disk Persistence)": The operating system's File System handles the process of flushing the changes from the memory map to the physical disk, ensuring data persistence. This synchronization is typically handled asynchronously by the OS.

  • Read Operation:

    1. "Application Read Request": The application initiates a request to read data through the MMKV Instance API (e.g., mmkv.getString("key", "defaultValue")).
    2. "MMKV Instance (Read API)": The MMKV Instance receives the read request and passes it to the Core Library.
    3. "MMKV Core Library": The Core Library processes the request, preparing to retrieve the data.
    4. "mmap Manager (Read from Memory Map)": The mmap Manager reads the requested data directly from the memory-mapped region of the "Data File". This read operation is performed directly from memory, providing fast access.
    5. "Data File (Memory Mapped)": The data is retrieved from the in-memory view of the "Data File".
    6. "Protobuf Deserializer": The Protobuf Deserializer deserializes the data from the Protocol Buffers binary format back into the application's data type.
    7. "Return Data to Application": The deserialized data is returned to the application code through the MMKV Instance API.

5. Security Considerations for Threat Modeling

This section outlines security considerations relevant to MMKV, categorized for clarity in threat modeling:

5.1. Confidentiality Threats:

  • Data File Access by Malicious Applications: If file permissions on the "Data File" are not correctly set, other malicious applications on the device could potentially read sensitive data stored by MMKV.
    • Mitigation: Ensure strict file permissions are applied to the "Data File" at creation, limiting access only to the application using MMKV. Follow platform-specific best practices for secure file permissions.
  • Data Breach via Physical Device Access: If a device is lost or stolen, and data-at-rest encryption is not enabled, an attacker with physical access could potentially extract and read the "Data File" contents.
    • Mitigation: Enable MMKV's encryption feature for sensitive data. Implement full-disk encryption on the mobile device as an additional layer of defense.
  • Side-Channel Attacks (Theoretical): While less likely in typical mobile scenarios, performance optimizations like mmap could theoretically introduce side-channel vulnerabilities where information leakage might occur through timing variations in memory access.
    • Mitigation: This is a complex area. For extremely high-security applications, consider thorough security analysis and potentially disabling mmap if side-channel risks are deemed significant (unlikely in most mobile use cases).

5.2. Integrity Threats:

  • Data Corruption due to Concurrency Issues: If the "Lock Manager" fails to properly synchronize concurrent access from multiple processes or threads, data corruption within the "Data File" could occur.
    • Mitigation: Thoroughly review and test the "Lock Manager" implementation. Utilize robust file locking mechanisms provided by the operating system. Implement unit and integration tests to verify concurrency safety under various scenarios.
  • Data Tampering by Malicious Applications (if permissions are weak): If file permissions are misconfigured, a malicious application could potentially modify the "Data File", leading to data integrity compromise.
    • Mitigation: Enforce strict file permissions. Consider implementing integrity checks (e.g., checksums or digital signatures) on the "Data File" if extremely high integrity is required, although this adds overhead.
  • Protobuf Deserialization Vulnerabilities: Vulnerabilities in the Protobuf library itself could potentially be exploited to corrupt data during deserialization.
    • Mitigation: Use a secure and up-to-date version of the Protobuf library. Regularly monitor for and patch any reported vulnerabilities in Protobuf.

5.3. Availability Threats:

  • Denial of Service (DoS) via File Locking Issues: If the "Lock Manager" implementation has flaws, it could be exploited to cause deadlocks or excessive locking, leading to denial of service for applications relying on MMKV.
    • Mitigation: Rigorous testing of the "Lock Manager" under heavy load and concurrent access scenarios. Implement timeouts and error handling in locking mechanisms to prevent indefinite blocking.
  • File System Errors or Disk Corruption: Underlying file system errors or physical disk corruption could lead to data loss or inaccessibility, impacting the availability of MMKV data.
    • Mitigation: MMKV itself cannot directly mitigate file system level issues. Rely on the operating system's file system integrity features and device health monitoring. Implement application-level error handling to gracefully manage potential storage failures.
  • Resource Exhaustion (Disk Space): Uncontrolled growth of the "Data File" could potentially exhaust disk space, leading to application failures or device instability.
    • Mitigation: Implement appropriate data management strategies within the application using MMKV. Consider data purging or archiving mechanisms for less frequently used data. Monitor disk space usage.

5.4. Key Management Threats (If Encryption is Enabled):

  • Weak Encryption Key Generation: If the encryption key is generated using weak or predictable methods, it could be susceptible to brute-force or dictionary attacks.
    • Mitigation: Use cryptographically secure random number generators for key generation. Follow industry best practices for key generation.
  • Insecure Key Storage: If the encryption key is stored insecurely (e.g., hardcoded, stored in plain text, or easily accessible storage), it could be compromised, rendering encryption ineffective.
    • Mitigation: Utilize secure key storage mechanisms provided by the operating system (e.g., Android Keystore, iOS Keychain). Avoid storing keys directly within the application's code or data files.
  • Key Leakage during Application Compromise: If the application process is compromised (e.g., via memory dumping or debugging), the encryption key could potentially be extracted from memory if not properly protected.
    • Mitigation: Employ memory protection techniques where possible. Minimize the time the key is held in memory. Consider using hardware-backed key storage for enhanced security.

6. Deployment Scenarios

MMKV is primarily designed for mobile applications on Android and iOS. Common deployment scenarios include:

  • Mobile Application Settings Storage: Storing user preferences, application configurations, and settings persistently.
  • Caching Small to Medium-Sized Data: Caching frequently accessed data to improve application performance and reduce network requests.
  • Offline Data Storage: Storing data for offline functionality in mobile applications.
  • Embedded Systems (Potentially): In resource-constrained embedded systems requiring efficient persistent storage, MMKV's core principles could be adapted.

7. Assumptions and Constraints

  • Operating System Support: MMKV's current implementation is primarily focused on Android and iOS. Porting to other operating systems might require significant effort.
  • File System Reliability: MMKV assumes a reasonably reliable underlying file system. File system corruption or errors are outside of MMKV's direct control.
  • Resource Limits: While MMKV is efficient, excessive storage of very large datasets might still impact device resources (disk space, memory). Applications should manage data usage responsibly.
  • Security relies on correct usage: MMKV provides security features like encryption, but their effectiveness depends on proper implementation and usage by the application developer (e.g., enabling encryption, secure key management).

8. Future Considerations

  • Enhanced Encryption Options: Explore and potentially integrate more advanced encryption algorithms (e.g., AES-GCM) and key derivation functions. Investigate integration with hardware security modules (HSMs) for key management.
  • Data Backup and Restore Mechanisms: Develop built-in mechanisms for secure and efficient data backup and restore, potentially leveraging cloud storage or platform-specific backup APIs.
  • Monitoring and Logging Enhancements: Implement more comprehensive monitoring metrics for MMKV performance (e.g., read/write latency, storage usage) and detailed logging of errors and security-related events for debugging and auditing.
  • Formal Security Audit and Penetration Testing: Conduct a formal security audit by external security experts and perform penetration testing to proactively identify and address potential vulnerabilities in the codebase and design.
  • Cross-Platform Support Expansion: Investigate and potentially expand support to other mobile or desktop platforms to broaden MMKV's applicability.

This improved design document provides a more detailed and security-focused overview of MMKV. It is intended to be a valuable resource for threat modeling and security analysis, enabling a more comprehensive assessment of potential risks and the design of effective mitigations.