Skip to content

Commit

Permalink
Improve docs for the custom backend (#550)
Browse files Browse the repository at this point in the history
  • Loading branch information
newpavlov authored Nov 29, 2024
1 parent a5bc5fe commit d2ddafb
Showing 1 changed file with 25 additions and 0 deletions.
25 changes: 25 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -169,6 +169,31 @@ data and its length in bytes. Note that the buffer MAY be uninitialized.
On success, the function should return `Ok(())` and fully fill the input buffer;
otherwise, it should return an error value.

While wrapping functions which work with byte slices you should fully initialize
the buffer before passing it to the function:
```rust
use getrandom::Error;

fn my_entropy_source(buf: &mut [u8]) -> Result<(), getrandom::Error> {
// ...
Ok(())
}

#[no_mangle]
unsafe extern "Rust" fn __getrandom_v03_custom(
dest: *mut u8,
len: usize,
) -> Result<(), Error> {
let buf = unsafe {
// fill the buffer with zeros
core::ptr::write_bytes(dest, 0, len);
// create mutable byte slice
core::slice::from_raw_parts_mut(dest, len)
};
my_entropy_source(buf)
}
```

If you are confident that `getrandom` is not used in your project, but
it gets pulled nevertheless by one of your dependencies, then you can
use the following custom backend, which always returns the "unsupported" error:
Expand Down

0 comments on commit d2ddafb

Please sign in to comment.