Using Linux's memfd_secret syscall from the JVM with JEP-419

Now let’s get practical.

Looking at man 2 syscall, the manpage shed some details on how to make the call, specifically in the Architecture calling conventions section. Those details are in assembly, e.g.

The calling convention of other architectures are also described e.g. on ARM processors, the system call is performed by a swi 0x0 instruction, on aarch64 by svc #0.

This manual page also gives an important difference with regular functions, while we look up system calls by their names: write, read, execve, exit, mmap, memfd_create etc. The programs and the kernel actually know them by numbers.

Why numbers? The reason is that syscalls are like messages that are passed down, and these numbers somewhat like enum ordinals indicating the type of message. These numbers are part of the syscall ABI (Application Binary Interface) and as such they are stable for a CPU architecture although unbounded (new syscalls can be added).

From the syscall manpage the Intel CPUs syscall calling convention is:

In order to quickly practice a syscall, let’s do a very simple hello world. The example will be in assembler, I promise this is the only source snippet in assembly and after that I’ll be back with Java and Panama.

When looking at this very simplistic code, something immediately stands out: From application point of view (user land), a syscall is just like an atomic pseudo machine instruction. I believe this example is more striking than the figure above on syscall ring transitions.

We saw what is exactly a syscall and how to make one using assembly. In general though, it’s rare to invoke syscall directly as the standard library exposes wrappers that handle everything for most of the syscalls.

Because memfd_secret syscall has been recently used there’s no wrapper functions in the standard library, hence we’ll need to make a system call ourselves.

Indeed, when developing in C/C++, when something returns -1, it usually means that something went wrong, and that the result is invalid.

Moreover, the errno variable is a global variable that is set by the system calls and some library functions, see the relevant man 3 errno.

Because it is a global variable its declaration depends on the system.

So we’ll need to check the errors after each call in our case, as each of these calls are system calls underneath.

On Linux we can see that errno definition is actually a call to a function that return a pointer : *__errno_location ()

On Linux the package more-utils has a tool called errno that can be used to list all the error codes errno -l.

Additionally, there is a function strerror that returns a string from an error code.

So, placing this check after the memfd_secret syscall, looked like a good bet. Eventually doing something similar after each call is a good idea as well, it kinda looks like the Go lang way of checking errors.

While reviewing the memfd_secret commit, we can see there’s a check that returns ENOSYS when a condition is not met.

So in order to make the whole thing work, we need to tackle what’s preventing memfd_secret to happen.

So actually, Linux is gating the memfd_secret syscall by a flag named secretmem_enable. That maybe why memfd_secret is not listed whe looking at man 2 syscalls.

It’s not quite clear from the commit that introduced memfd_secret but in order to work, the machine boot has to be configured with the flag secretmem.enable=1.

My test machine is a Fedora 35, let’s read their page on the GRUB2 bootloader.

From this page, it seems there’s a fairly simple way to change the bootloader configuration.

Notice the actual flag name is secretmem.enable, not secretmem_enable !

The reboot the OS. Now if the configuration was properly applied, memfd_secret should return a valid file descriptor.

Typically, this secret storage could be used to store a decryption key during startup, and it’ll be used to decrypt encrypted payload. Of course, care must be taken to prevent this data from leaving this memory. Which might not be possible under many circumstances. E.g. a library that takes a Java String, in which case the secret buffer is copied in elsewhere in the heap.

So appart from the memfd_secret syscall, the other calls, looks to be replaceable ?

MemorySegment.mapFile looks like a good bet to replace mmap.

However, upon first use, things start to look problematic. The signature requires a Path and the mapping is limited to a single MapMode.

Supposing the file descriptor value is 4, if it was possible to pass /dev/fd/4 or /proc/self/fd/4 as a Path, we could not map this segment as read and write via this API. And performing this operation twice, one in read-only mode and one in write-only mode, would not work as this special file descriptor is closed after the first memory mapping.

There’s some interesting bits in FileOutputStream / FileInputStream as they can be created from a JDK’s FileDescriptor, they to allow to get the underneath FileChannel, which then allow to call map() to get a memory mapping. However, FileDescriptor class does not have a public constructor, and even being able to hack FileDescriptor (with`--add-opens=java.base/java.io=ALL-UNNAMED`) is not enough as we get in the same situation as above because it’s only possible to have a mapping in read-only or write-only.

Basically, we’re stuck with using the mmap native function to do what’s necessary. I don’t know if it is out of scope for the JEP-419, or the next JEP-424, but I think this would be a good thing to support MemorySegment of arbitrary file descriptor, in particular when writing programs that run on the command line, this could enable things like java Main.java <(cat neko | grep meow).

Finally, I don’t believe there’s something equivalent available in JDK for the ftruncate function.

In the snippet above, we’ve declared a MethodHandle to the syscall function, if there’s multiple syscalls, we’ll need to pass the syscall number as the first argument each time. MethodHandles API allows to make partial function.

Now if the syscall has different arity, MethodHandle::appendArgumentLayouts has us covered, so that we can use the basic template of a syscall, sort of, and build on top of this to have specific identifiers for each syscall.

Other things are possible with MethodHandles that can be handy with Panama, yet out of scope for this blog post. Just check the API.

The JDK Panama team, also created a tool known as jextract whose job is to lift most of the work to generate the MethodHandles.

So mentioned in other blog post or conference talks I gave, jextract is now a separate tool, at this point there’s no binary release which means it has to be built. The jextract project page explains how to do this. My test machine is a Fedora, so adapt the command and the JDK distribution to your needs.

If everything is alright you can use jextract:

The basic usage is jextract <options> <header file>. Since there is multiple headers, the trick is to specify a handcrafted header with every needed header.

Also note that jextract support passing the options as option file. So we can pass output options, like the target package and class name, but also the symbols we’d like.

So once done, we’ll have a file with all the symbols we need.

What’s nice is that the arguments are named, eg. sysno, addr, __fd, etc.

Once you have made your research on which symbols you need, it’s really nice to let jextract generate the code for you, which is likely to be up-to date, with the best practice backed in.

There’s one thing where this a bit suboptimal, the __errno_location function is actually an OS specific function, that is used to revolve the errno value. I’m unsure if jextract should resolve macros in general, yet errno seems like something very common, so could it make sense if jextract could handle this one? But then it’s opening the door to macro resolution which is a different level of complexity.

That being said, it’s not a deal-breaker, just something to be aware of.