{"id":20474230,"url":"https://github.com/marschall/getrandom-provider","last_synced_at":"2026-01-08T20:04:33.344Z","repository":{"id":57721282,"uuid":"113765047","full_name":"marschall/getrandom-provider","owner":"marschall","description":"A SecureRandomSPI that makes the getrandom() system call available to SecureRandom.","archived":false,"fork":false,"pushed_at":"2022-04-09T17:19:41.000Z","size":202,"stargazers_count":4,"open_issues_count":2,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-21T08:03:12.628Z","etag":null,"topics":["java","jce","linux","secure-random-generator"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/marschall.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-12-10T16:24:26.000Z","updated_at":"2022-03-24T20:53:32.000Z","dependencies_parsed_at":"2022-09-04T16:20:29.635Z","dependency_job_id":null,"html_url":"https://github.com/marschall/getrandom-provider","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marschall%2Fgetrandom-provider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marschall%2Fgetrandom-provider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marschall%2Fgetrandom-provider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/marschall%2Fgetrandom-provider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/marschall","download_url":"https://codeload.github.com/marschall/getrandom-provider/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246336149,"owners_count":20760992,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java","jce","linux","secure-random-generator"],"created_at":"2024-11-15T14:28:41.930Z","updated_at":"2026-01-08T20:04:28.318Z","avatar_url":"https://github.com/marschall.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# getrandom() SecureRandomSPI [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.github.marschall/getrandom-provider/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.github.marschall/getrandom-provider)  [![Javadocs](https://www.javadoc.io/badge/com.github.marschall/getrandom-provider.svg)](https://www.javadoc.io/doc/com.github.marschall/getrandom-provider)\n\nA `SecureRandomSPI` that makes [getrandom()](http://man7.org/linux/man-pages/man2/getrandom.2.html) system call available to `SecureRandom`.\n\n* uses syscall, does not depend on glibc wrapper\n* tries to use stack allocation rather than allocation on the C heap\n* 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\n* unlike the `NativePRNG` variants\n  * does not use a file handle\n  * does not have a global lock, but see comments on the kernel lock above\n  * does not additionally mix with `SHA1PRNG`\n  * blocks until the urandom source has been initialized\n  * zeros out native memory\n* supports the ServiceLoader mechanism\n* is a Java 9 module but works on Java 8\n* no dependencies outside the `java.base` module\n\nLikely benefits from [random number generator enhancements for Linux 5.17 and 5.18](https://www.zx2c4.com/projects/linux-rng-5.17-5.18/).\n\n## Usage\n\nA nonblocking (/dev/urandom) instance of the provider can be acquired using\n\n```java\nSecureRandom.getInstance(\"geturandom\"); // GetrandomProvider.GETURANDOM\n```\n\nAlternatively a blocking (/dev/random) instance of the provider can be acquired using\n\n```java\nSecureRandom.getInstance(\"getrandom\"); // GetrandomProvider.GETRANDOM\n```\n\nThe /dev/urandom variant is the preferred one, the /dev/random variant is only added for completeness, see [Myths about /dev/urandom](https://www.2uo.de/myths-about-urandom/).\n\n## Configuration\n\nThe provider can be configured in two different ways\n\n1. programmatic configuration\n1. static configuration\n\nFor 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.\n\n### Programmatic Configuration\n\nThe provider can be registered programmatically using\n\n```java\nSecurity.addProvider(new GetrandomProvider());\n```\n\n### Static Configuration Java 8\n\nThe provider can be configured statically in the `java.security` file by adding the provider at the end\n\n```\nsecurity.provider.N=com.github.marschall.getrandom.GetrandomProvider\n```\n\n`N` should be the value of the last provider incremented by 1. For Oracle/OpenJDK 8 on Linux `N` should likely be 10.\n\nThis can be done [per JVM installation](https://docs.oracle.com/en/java/javase/11/security/howtoimplaprovider.html#GUID-831AA25F-F702-442D-A2E4-8DA6DEA16F33) or [per JVM Instance](https://docs.oracle.com/en/java/javase/11/security/java-authentication-and-authorization-service-jaas-reference-guide.html#GUID-106F4B32-B9A3-4B75-BDBF-29B252BB3F53).\n\nNote that for this to work the provider JAR needs to be in the class path or extension folder.\n\n### Static Configuration Java 9+\n\nThe provider can be configured statically in the `java.security` file by adding the provider at the end\n\n```\nsecurity.provider.N=getrandom\n```\n\n`N` should be the value of the last provider incremented by 1. For Oracle/OpenJDK 9 on Linux `N` should likely be 13.\n\nThis can be done [per JVM installation](https://docs.oracle.com/javase/9/security/howtoimplaprovider.htm#GUID-831AA25F-F702-442D-A2E4-8DA6DEA16F33) or [per JVM Instance](https://dzone.com/articles/how-override-java-security).\n\nThe provider uses the ServiceLoader mechanism therefore using the `getrandom` string is enough, there is no need to use the fully qualified class name.\n\nNote that for this to work the provider JAR needs to be in the class path or module path.\n\n### Performance\n\n[Performance](https://github.com/marschall/random-provider-benchmarks/tree/master/src/main/output/meltdown) 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.\n\n### Usage for Tomcat Session Ids\n\nThis security provider can be used for session id generation in Tomcat. In order for that several things need to be configured:\n\n1. the JAR needs to be added to the class path\n1. the .so should be added to the Java library path (`java.library.path`)\n1. the provider needs to be installed into the JVM via `java.security.properties`\n1. Tomcat needs to be configured to use the algorithm\n\nPoints 1, 2 and 3 can be configured in `CATALINA_BASE/bin/setenv.sh`\n\n```sh\n#!/bin/sh\n\nCLASSPATH=\"/path/to/getrandom-provider-0.1.1.jar\"\nCATALINA_OPTS=\"$CATALINA_OPTS -Djava.library.path=/path/to/folder/with/so -Djava.security.properties=/path/to/jvm.java.security\"\n\nexport CLASSPATH\nexport CATALINA_OPTS\n```\n\nPoint can be configured on [the Manager Component](https://tomcat.apache.org/tomcat-8.5-doc/config/manager.html) in `conf/context.xml` by setting `secureRandomAlgorithm` to `geturandom`\n\n```xml\n\u003cManager secureRandomAlgorithm=\"geturandom\"\u003e\n\u003c/Manager\u003e\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarschall%2Fgetrandom-provider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarschall%2Fgetrandom-provider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarschall%2Fgetrandom-provider/lists"}