From 70ea259c603e0f84eda766be29d4259f1e8fe5b7 Mon Sep 17 00:00:00 2001
From: DJ Delorie <dj@delorie.com>
Date: Tue, 23 Mar 2021 19:03:45 -0400
Subject: Search $LIBFFI_TMPDIR also (#605)

Most temp file directories need to be hardened against execution, but
libffi needs execute privileges.  Add a libffi-specific temp directory
that can be set up by sysadmins as needed with suitable permissions.
This both ensures that libffi will have a valid temp directory to use
as well as preventing attempts to access other directories.
---
 doc/libffi.texi | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 50 insertions(+)

(limited to 'doc')

diff --git a/doc/libffi.texi b/doc/libffi.texi
index 79f9377..28f0e6a 100644
--- a/doc/libffi.texi
+++ b/doc/libffi.texi
@@ -65,6 +65,7 @@ SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 @menu
 * Introduction::                What is libffi?
 * Using libffi::                How to use libffi.
+* Memory Usage::                Where memory for closures comes from.
 * Missing Features::            Things libffi can't do.
 * Index::                       Index.
 @end menu
@@ -970,6 +971,55 @@ Currently the only affected platform is PowerPC and the only affected
 type is @code{long double}.
 @end itemize
 
+@node Memory Usage
+@chapter Memory Usage
+
+Note that memory allocated by @code{ffi_closure_alloc} and freed by
+@code{ffi_closure_free} does not come from the same general pool of
+memory that @code{malloc} and @code{free} use.  To accomodate security
+settings, @samp{libffi} may aquire memory, for example, by mapping
+temporary files into multiple places in the address space (once to
+write out the closure, a second to execute it).  The search follows
+this list, using the first that works:
+
+@itemize @bullet
+
+@item
+A anonymous mapping (i.e. not file-backed)
+
+@item
+@code{memfd_create()}, if the kernel supports it.
+
+@item
+A file created in the directory referenced by the environment variable
+@code{LIBFFI_TMPDIR}.
+
+@item
+Likewise for the environment variable @code{TMPDIR}.
+
+@item
+A file created in @code{/tmp}.
+
+@item
+A file created in @code{/var/tmp}.
+
+@item
+A file created in @code{/dev/shm}.
+
+@item
+A file created in the user's home directory (@code{$HOME}).
+
+@item
+A file created in any directory listed in @code{/etc/mtab}.
+
+@item
+A file created in any directory listed in @code{/proc/mounts}.
+
+@end itemize
+
+If security settings prohibit using any of these for closures,
+@code{ffi_closure_alloc} will fail.
+
 @node Missing Features
 @chapter Missing Features
 
-- 
cgit v1.2.1