# grapheneos/hardened_malloc architecture

> Architecture diagram of the GitHub repository grapheneos/hardened_malloc, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/grapheneos/hardened_malloc
- Repository: https://github.com/grapheneos/hardened_malloc

## Overview

hardened_malloc is a hardened general-purpose allocator that replaces the standard malloc family on Android or Linux. The principal workflow routes application allocation and release requests through allocator entry points, which service small requests from slabs and large requests from guarded page regions. It hardens those paths with randomized allocation state, quarantine, and optional Arm memory tagging, while exposing compatibility and statistics extensions. The source excerpts show key allocator and memory interfaces; several documented features are described in the README but their implementation paths are not fully sampled, so those links are omitted where unverified.

Main entry points: [`h_malloc.c`](https://github.com/grapheneos/hardened_malloc/blob/main/h_malloc.c) (Allocator core), [`include/h_malloc.h`](https://github.com/grapheneos/hardened_malloc/blob/main/include/h_malloc.h) (C allocation API), [`new.cc`](https://github.com/grapheneos/hardened_malloc/blob/main/new.cc) (C++ new/delete), [`pages.c`](https://github.com/grapheneos/hardened_malloc/blob/main/pages.c) (Guarded pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Allocator API"]
  node_malloc_api["C allocation API<br/>[h_malloc.h]"]
  node_cpp_api["C++ new/delete<br/>[new.cc]"]
  node_stats["Stats and extensions<br/>[h_malloc.c]"]
end

subgraph group_allocation["Allocation engine"]
  node_allocator["Allocator core<br/>[h_malloc.c]"]
  node_small_alloc["Slab allocations<br/>[h_malloc.c]"]
  node_large_alloc["Large allocations<br/>[h_malloc.c]"]
end

subgraph group_platform["Memory platform"]
  node_page_allocator["Guarded pages<br/>[pages.c]"]
  node_memory_ops["Virtual memory operations<br/>[memory.c]"]
end

subgraph group_hardening["Hardening primitives"]
  node_random_source["Random state<br/>[random.c]"]
  node_chacha["ChaCha stream<br/>[chacha.c]"]
  node_memtag["Memory tagging<br/>[memtag.h]"]
  node_arm_mte["Arm MTE operations<br/>[arm_mte.h]"]
end

node_app(("Application"))

node_app -->|"requests allocation"| node_malloc_api
node_malloc_api -->|"dispatches API"| node_allocator
node_cpp_api -->|"calls allocation"| node_allocator
node_allocator -->|"allocates small"| node_small_alloc
node_allocator -->|"allocates large"| node_large_alloc
node_allocator -->|"requests pages"| node_page_allocator
node_page_allocator -->|"maps and protects"| node_memory_ops
node_allocator -->|"uses randomness"| node_random_source
node_random_source -->|"generates stream"| node_chacha
node_allocator -->|"handles tagged pointers"| node_memtag
node_memtag -->|"uses MTE primitives"| node_arm_mte
node_app -->|"uses C++ allocation"| node_cpp_api
node_malloc_api -->|"exposes extensions"| node_stats

click node_malloc_api "https://github.com/grapheneos/hardened_malloc/blob/main/include/h_malloc.h"
click node_allocator "https://github.com/grapheneos/hardened_malloc/blob/main/h_malloc.c"
click node_small_alloc "https://github.com/grapheneos/hardened_malloc/blob/main/h_malloc.c"
click node_large_alloc "https://github.com/grapheneos/hardened_malloc/blob/main/h_malloc.c"
click node_cpp_api "https://github.com/grapheneos/hardened_malloc/blob/main/new.cc"
click node_stats "https://github.com/grapheneos/hardened_malloc/blob/main/h_malloc.c"
click node_page_allocator "https://github.com/grapheneos/hardened_malloc/blob/main/pages.c"
click node_memory_ops "https://github.com/grapheneos/hardened_malloc/blob/main/memory.c"
click node_random_source "https://github.com/grapheneos/hardened_malloc/blob/main/random.c"
click node_chacha "https://github.com/grapheneos/hardened_malloc/blob/main/chacha.c"
click node_memtag "https://github.com/grapheneos/hardened_malloc/blob/main/memtag.h"
click node_arm_mte "https://github.com/grapheneos/hardened_malloc/blob/main/arm_mte.h"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_malloc_api,node_cpp_api,node_stats toneBlue
class node_allocator,node_small_alloc,node_large_alloc toneAmber
class node_page_allocator,node_memory_ops toneMint
class node_random_source,node_chacha,node_memtag,node_arm_mte toneRose
class node_app toneIndigo
```

## Components

### Allocator API

- [C allocation API](https://github.com/grapheneos/hardened_malloc/blob/main/include/h_malloc.h): `include/h_malloc.h`
- [C++ new/delete](https://github.com/grapheneos/hardened_malloc/blob/main/new.cc): `new.cc`
- [Stats and extensions](https://github.com/grapheneos/hardened_malloc/blob/main/h_malloc.c): `h_malloc.c`

### Allocation engine

- [Allocator core](https://github.com/grapheneos/hardened_malloc/blob/main/h_malloc.c): `h_malloc.c`
- [Slab allocations](https://github.com/grapheneos/hardened_malloc/blob/main/h_malloc.c): `h_malloc.c`
- [Large allocations](https://github.com/grapheneos/hardened_malloc/blob/main/h_malloc.c): `h_malloc.c`

### Memory platform

- [Guarded pages](https://github.com/grapheneos/hardened_malloc/blob/main/pages.c): `pages.c`
- [Virtual memory operations](https://github.com/grapheneos/hardened_malloc/blob/main/memory.c): `memory.c`

### Hardening primitives

- [Random state](https://github.com/grapheneos/hardened_malloc/blob/main/random.c): `random.c`
- [ChaCha stream](https://github.com/grapheneos/hardened_malloc/blob/main/chacha.c): `chacha.c`
- [Memory tagging](https://github.com/grapheneos/hardened_malloc/blob/main/memtag.h): `memtag.h`
- [Arm MTE operations](https://github.com/grapheneos/hardened_malloc/blob/main/arm_mte.h): `arm_mte.h`

### Other components

- **Application**

## Connections

- Application → C allocation API: requests allocation (evidence: `README.md`)
- C allocation API → Allocator core: dispatches API (evidence: `h_malloc.c`)
- C++ new/delete → Allocator core: calls allocation (evidence: `new.cc`)
- Allocator core → Slab allocations: allocates small (evidence: `h_malloc.c`)
- Allocator core → Large allocations: allocates large (evidence: `h_malloc.c`)
- Allocator core → Guarded pages: requests pages (evidence: `h_malloc.c`)
- Guarded pages → Virtual memory operations: maps and protects (evidence: `pages.c`)
- Allocator core → Random state: uses randomness (evidence: `h_malloc.c`)
- Random state → ChaCha stream: generates stream (evidence: `random.c`)
- Allocator core → Memory tagging: handles tagged pointers (evidence: `h_malloc.c`)
- Memory tagging → Arm MTE operations: uses MTE primitives (evidence: `memtag.h`)
- Application → C++ new/delete: uses C++ allocation (evidence: `README.md`)
- C allocation API → Stats and extensions: exposes extensions (evidence: `include/h_malloc.h`)
