marschall / getrandom-provider

A SecureRandomSPI that makes the getrandom() system call available to SecureRandom.

getrandom() SecureRandomSPI

A SecureRandomSPI that makes getrandom() system call available to SecureRandom.

• uses syscall, does not depend on glibc wrapper
• tries to use stack allocation rather than allocation on the C heap
• is marked as thread safe so concurrent access through SecureRandom will not synchronize in Java 9 and later, however there seems to be a kernel lock on /dev/urandom so you will likely not get additional parallelism
• unlike the NativePRNG variants
  • does not use a file handle
  • does not have a global lock, but see comments on the kernel lock above
  • does not additionally mix with SHA1PRNG
  • blocks until the urandom source has been initialized
  • zeros out native memory
• supports the ServiceLoader mechanism
• is a Java 9 module but works on Java 8
• no dependencies outside the java.base module

Likely benefits from random number generator enhancements for Linux 5.17 and 5.18.

Usage

A nonblocking (/dev/urandom) instance of the provider can be acquired using

SecureRandom.getInstance("geturandom"); // GetrandomProvider.GETURANDOM

Alternatively a blocking (/dev/random) instance of the provider can be acquired using

SecureRandom.getInstance("getrandom"); // GetrandomProvider.GETRANDOM

The /dev/urandom variant is the preferred one, the /dev/random variant is only added for completeness, see Myths about /dev/urandom.

Configuration

The provider can be configured in two different ways

1. programmatic configuration
2. static configuration

For best startup performance it is recommended to extract the .so from the JAR and add it to a folder present in the LD_LIBRARY_PATH environment variable or the java.library.path system property. Otherwise this library will extract the .so to a temporary folder the first time it is called.

Programmatic Configuration

The provider can be registered programmatically using

Security.addProvider(new GetrandomProvider());

Static Configuration Java 8

The provider can be configured statically in the java.security file by adding the provider at the end

security.provider.N=com.github.marschall.getrandom.GetrandomProvider

N should be the value of the last provider incremented by 1. For Oracle/OpenJDK 8 on Linux N should likely be 10.

This can be done per JVM installation or per JVM Instance.

Note that for this to work the provider JAR needs to be in the class path or extension folder.

Static Configuration Java 9+

The provider can be configured statically in the java.security file by adding the provider at the end

security.provider.N=getrandom

N should be the value of the last provider incremented by 1. For Oracle/OpenJDK 9 on Linux N should likely be 13.

This can be done per JVM installation or per JVM Instance.

The provider uses the ServiceLoader mechanism therefore using the getrandom string is enough, there is no need to use the fully qualified class name.

Note that for this to work the provider JAR needs to be in the class path or module path.

Performance

Performance compared to NativePRNGNonBlocking is lower for small, single threaded workloads due to the syscall overhead and additionally negatively impacted by the meltdown patches. However for large or threaded workloads performance is higher.

Usage for Tomcat Session Ids

This security provider can be used for session id generation in Tomcat. In order for that several things need to be configured:

1. the JAR needs to be added to the class path
2. the .so should be added to the Java library path (java.library.path)
3. the provider needs to be installed into the JVM via java.security.properties
4. Tomcat needs to be configured to use the algorithm

Points 1, 2 and 3 can be configured in CATALINA_BASE/bin/setenv.sh

#!/bin/sh

CLASSPATH="/path/to/getrandom-provider-0.1.1.jar"
CATALINA_OPTS="$CATALINA_OPTS -Djava.library.path=/path/to/folder/with/so -Djava.security.properties=/path/to/jvm.java.security"

export CLASSPATH
export CATALINA_OPTS

Point can be configured on the Manager Component in conf/context.xml by setting secureRandomAlgorithm to geturandom

<Manager secureRandomAlgorithm="geturandom">
</Manager>

getrandom-provider's Issues

Add badges

Add badges for Maven Central and Javadoc.

Package .so

Package the .so into the JAR file.

Remove NAR packaging

It should be possible to run NAR without the packaging.

Consider GetByteArrayElements

For GCs that support object pinning like Shenandoah object pinning in the form of GetByteArrayElements and ReleaseByteArrayElements pairs may be worth considering for urandom reads as a copy can be avoided in this case. However for everybody else this would mean an allocation on the C heap which the current stack allocation scheme avoids.

Handle malloc NULL

We have to better handle the case then malloc() return null.

Extract .so

Provide a way to extract the .so that people don't have to set the library path.

Consider a next buffer

The the NativePRNG variants have a 32 byte next buffer.

Pass array length to JNI

Pass the array length to JNI so we can avoid the GetArrayLength call.

Seal the JAR

https://stackoverflow.com/questions/13527235/maven-how-do-i-mark-a-jar-as-sealed