OS integration guide

README.md

@@ -79,6 +79,59 @@ this allocator offers across different size classes. The intention is that this
 will be offered as part of hardened variants of the Bionic and musl C standard
 libraries.
 
+# OS integration
+
+## Android-based operating systems
+
+On GrapheneOS, hardened\_malloc is integrated into the standard C library as
+the standard malloc implementation. Other Android-based operating systems can
+reuse the integration code to provide it. If desired, jemalloc can be left as
+a runtime configuration option by only conditionally using hardened\_malloc to
+give users the choice between performance and security. However, this reduces
+security for threat models where persistent state is untrusted, i.e. verified
+boot and attestation (see the [attestation sister
+project](https://attestation.app/about)).
+
+Make sure to raise `vm.max_map_count` substantially too to accomodate the very
+large number of guard pages created by hardened\_malloc. This can be done in
+`init.rc` (`system/core/rootdir/init.rc`) near the other virtual memory
+configuration:
+
+    write /proc/sys/vm/max_map_count 524240
+
+This is unnecessary if you set `CONFIG_GUARD_SLABS_INTERVAL` to a very large
+value in the build configuration.
+
+## Traditional Linux-based operating systems
+
+On traditional Linux-based operating systems, hardened\_malloc can either be
+integrated into the libc implementation as a replacement for the standard
+malloc implementation or loaded as a dynamic library. Rather rebuilding each
+executable to be linked against it, it can be added as a preloaded library to
+`/etc/ld.so.preload`. For example, with `libhardened_malloc.so` installed to
+`/usr/local/lib/libhardened_malloc.so`, add that full path as a line to the
+`/etc/ld.so.preload` configuration file:
+
+    /usr/local/lib/libhardened_malloc.so
+
+The format of this configuration file is a whitespace-separated list, so it's
+good practice to put each library on a separate line.
+
+Using the `LD_PRELOAD` environment variable to load it on a case-by-case basis
+will not work when `AT_SECURE` is set such as with setuid binaries. It's also
+generally not a recommended approach for production usage. The recommendation
+is to enable it globally and make exceptions for performance critical cases by
+running the application in a container / namespace without it enabled.
+
+Make sure to raise `vm.max_map_count` substantially too to accomodate the very
+large number of guard pages created by hardened\_malloc. As an example, in
+`/etc/sysctl.d/hardened_malloc.conf`:
+
+    vm.max_map_count = 524240
+
+This is unnecessary if you set `CONFIG_GUARD_SLABS_INTERVAL` to a very large
+value in the build configuration.
+
 ## Configuration
 
 You can set some configuration options at compile-time via arguments to the