{"id":18016563,"url":"https://github.com/webassembly/wasi-random","last_synced_at":"2025-06-29T15:06:37.389Z","repository":{"id":39718218,"uuid":"261895387","full_name":"WebAssembly/wasi-random","owner":"WebAssembly","description":"Entropy source API for WASI","archived":false,"fork":false,"pushed_at":"2025-06-12T21:10:29.000Z","size":915,"stargazers_count":35,"open_issues_count":1,"forks_count":10,"subscribers_count":16,"default_branch":"main","last_synced_at":"2025-06-29T15:06:34.798Z","etag":null,"topics":["proposal","wasi"],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WebAssembly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-05-06T22:47:27.000Z","updated_at":"2025-06-12T21:09:40.000Z","dependencies_parsed_at":"2023-11-11T00:21:48.240Z","dependency_job_id":"90c02274-5025-4296-b82b-03a26a06cad7","html_url":"https://github.com/WebAssembly/wasi-random","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/WebAssembly/wasi-random","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-random","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-random/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-random/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-random/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WebAssembly","download_url":"https://codeload.github.com/WebAssembly/wasi-random/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WebAssembly%2Fwasi-random/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262614457,"owners_count":23337277,"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":["proposal","wasi"],"created_at":"2024-10-30T04:18:28.519Z","updated_at":"2025-06-29T15:06:37.353Z","avatar_url":"https://github.com/WebAssembly.png","language":null,"readme":"# WASI Random\n\nA proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.\n\n### Current Phase\n\nWASI-random is currently in [Phase 3].\n\n[Phase 3]: https://github.com/WebAssembly/WASI/blob/main/Proposals.md#phase-3---implementation-phase-cg--wg\n\n### Champions\n\n- Dan Gohman\n\n### Portability Criteria\n\nWASI random must have host implementations which can pass the testsuite\non at least Windows, macOS, and Linux.\n\nWASI random must have at least two complete independent implementations.\n\n## Table of Contents\n\n- [Introduction](#introduction)\n- [Goals](#goals)\n- [Non-goals](#non-goals)\n- [API walk-through](#api-walk-through)\n  - [Use case 1](#use-case-1)\n  - [Use case 2](#use-case-2)\n- [Detailed design discussion](#detailed-design-discussion)\n  - [[Tricky design choice 1]](#tricky-design-choice-1)\n  - [[Tricky design choice 2]](#tricky-design-choice-2)\n- [Considered alternatives](#considered-alternatives)\n  - [[Alternative 1]](#alternative-1)\n  - [[Alternative 2]](#alternative-2)\n- [Stakeholder Interest \u0026 Feedback](#stakeholder-interest--feedback)\n- [References \u0026 acknowledgements](#references--acknowledgements)\n\n### Introduction\n\nWASI Random is a WASI API for obtaining pseudo-random data.\n\n### Goals\n\nThe primary goals of WASI Random are:\n - To allow users to use WASI programs to obtain high-quality low-level\n   random data suitable for cryptography.\n - To allow source languages to enable DoS protection in their hash-maps\n   in host environments that support it.\n\n### Non-goals\n\nWASI Random is not aiming to allow programs to handle errors or to query for\navailability. It always succeeds (though on platforms where randomness is\nunavailable, programs may fail to be instantiated or may trap).\n\nWASI Random is not aiming to be a full DRBG API. Such an API could be\nconsidered in WASI, but it should be a separate proposal.\n\nWASI Random does not include facilities for feeding entropy back into\nthe system. It is expected that most entropy that applications would observe\nshould also be observable by the host implementation, and so there should\nbe little need to feed it back in. There may be other uses for such an API,\nbut they can be addressed in separate proposals.\n\nWASI Random does not have an async API. It is expected to be implemented with\na CSPRNG which is expected to be sufficiently seeded.\n\nWASI Random does not have an explicit facility for domain separation or\npersonalization messages. If such features are desired, it would make sense to\ndefine them as custom sections, rather than program data, so that they could\neasily be excluded from module caching and possibly also from code signing.\nThis would make sense as a separate proposal.\n\nWASI Random does not provide an \"entropy API\" or a \"true random\" API directly.\nThe currently expected use cases want a CSPRNG API.\n\nWASI Random does not expose an entropy estimation. It is expected to always\nhave sufficient entropy to seed a CSPRNG.\n\nWASI Random does not provide any facility for replacing random data with\ndeterministic data. It is intended to be usable in use cases where determinism\nwould break application assumptions. Implementations may have debugging\nfacilities which make this API deterministic, however these should only be\nused for debugging, and not production use.\n\n### API walk-through\n\n#### Main API: getting cryptographically-secure pseudo-random bytes\n\nReturn a list of cryptographically-secure pseudo-random bytes:\n\n```rust\n    let len: u32 = your_own_code_to_decide_how_many_bytes_you_want();\n\n    let bytes: Vec\u003cu8\u003e = get_random_bytes(len);\n```\n\n#### Main API: getting cryptographically-secure pseudo-random bytes faster\n\nSometimes the bindings for `list\u003cu8\u003e` can have some overhead, so\nanother function is available which returns the same data but as a\n`u64`:\n\n```rust\n    let data: u64 = get_random_u64();\n```\n\n#### Insecure API: Hash-map DoS protection\n\nReturn a pair of u64's that can be used to initialize a hash implementation:\n\n```rust\n    let init: (u64, u64) = insecure_random();\n\n    let combined: u128 = init.0 as u128 | (init.1 as u128 \u003c\u003c 64);\n\n    your_own_code_to_initialize_hash_map(combined);\n```\n\n### Detailed design discussion\n\n### What if the system lacks sufficient entropy during early boot?\n\nRandomness APIs which can fail, or which can be \"nonblocking\" and return\nincomplete results, are error prone and tend to lead applications to resort\nto fallbacks which don't tend to be well-tested.\n\nCSPRNGs are believed to be good enough that most systems in most situations\ncan provide effectively unlimited random data. The main case where this\nisn't the case is on systems which have just booted and which have not yet\ncollected sufficient entropy to initialize their CSPRNGs. In these cases,\nthis API is designed with the belief that it's better for implementations\nto respond to the problem, rather than to pass the responsibility on to\napplications.\n\n### What should happen on host platforms with weak or broken randomness APIs?\n\nIt's implementations' responsibility to handle these situations. They may do\nso by supplementing the host platform APIs with data collected from other\nsources, they may refuse to run programs that use Random APIs, or if needed,\nthey may trap programs dynamically to prevent programs from continuing to\nexecute with poor data.\n\nImplementations are encouraged to perform regular reseeding (if the host\nplatform doesn't already do so).\n\n### Should there be a randomness resource, and should the API take a handle?\n\nPrograms shouldn't need to be aware of *which* random generator they have, since\nthe data is random and indistinguishable.\n\nWASI programs using the Random API will have imports specific to the Random API,\nbecause they are distinct from imports used for general-purpose `stream`.\n\n### Should random data be provided as a `stream`?\n\nReusing the `stream` type is tempting, however it's desirable for users of this\nAPI to be provided actually random data, and not the contents of arbitrary\nstreams which might be substituted, so it doesn't turn out to be useful to unify\nthis API with `stream`.\n\nThis also ensures that programs using the Random API can be identified by\ntheir imports, as mentioned in the previous question.\n\n### Should the API specify a number of bits of security?\n\nBest practices suggest that implementations should provide at least 196 bits of\nsecurity. However, many host platforms' CSPRNG APIs do not currently document\ntheir bits of security, and it doesn't seem desirable to require wasm engines to\nrun their own CSPRNG on a platform which already has one, so for now, the API\ndoes not specify a specific number.\n\n### Why is insecure-random a fixed-sized return value?\n\nThis limits the amount of data that can be obtained through it. Since it's\ninsecure, it's not intended to be used as an alternative to `getrandom`.\n\n### Stakeholder Interest \u0026 Feedback\n\nTODO before entering Phase 3.\n\nPreview1 has a random function, and it's widely exposed in toolchains.\n\n### References \u0026 acknowledgements\n\nMany thanks for valuable feedback and advice from:\n\n- Zach Lym\n- Luke Wagner\n- Linux Weekly News' many articles about Linux random APIs including [this one].\n\n[this one]: https://lwn.net/Articles/808575/\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebassembly%2Fwasi-random","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwebassembly%2Fwasi-random","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwebassembly%2Fwasi-random/lists"}