// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library zx;

const CPRNG_DRAW_MAX_LEN usize64 = 256;
const CPRNG_ADD_ENTROPY_MAX_LEN usize64 = 256;

@transport("Syscall")
closed protocol Cprng {
    @internal
    strict DrawOnce() -> (struct {
        @voidptr
        buffer vector<byte>:CPRNG_DRAW_MAX_LEN;
    }) error Status;

    /// ## Summary
    ///
    /// Draw from the kernel's CPRNG.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// void zx_cprng_draw(void* buffer, size_t buffer_size);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_cprng_draw()` draws random bytes from the kernel CPRNG.  This data should
    /// be suitable for cryptographic applications.
    ///
    /// Clients that require a large volume of randomness should consider using these
    /// bytes to seed a user-space random number generator for better performance.
    /// "Large" here would mean a large multiple of `ZX_CPRNG_DRAW_MAX_LEN`, which is
    /// currently 256. As always, test the actual latency of your call site before
    /// optimizing.
    ///
    /// ## Rights
    ///
    /// None.
    ///
    /// ## Notes
    ///
    /// `zx_cprng_draw()` terminates the calling process if `buffer` is not a valid
    /// userspace pointer.
    ///
    /// There are no other error conditions.  If its arguments are valid,
    /// `zx_cprng_draw()` will succeed.
    ///
    /// ## See also
    ///
    ///  - [`zx_cprng_add_entropy()`]
    ///
    /// [`zx_cprng_add_entropy()`]: cprng_add_entropy.md
    @vdsocall
    strict Draw() -> (struct {
        @voidptr
        buffer vector<byte>:CPRNG_DRAW_MAX_LEN;
    });

    /// ## Summary
    ///
    /// Add entropy to the kernel CPRNG.
    ///
    /// ## Declaration
    ///
    /// ```c
    /// #include <zircon/syscalls.h>
    ///
    /// zx_status_t zx_cprng_add_entropy(const void* buffer, size_t buffer_size);
    /// ```
    ///
    /// ## Description
    ///
    /// `zx_cprng_add_entropy()` mixes the given entropy into the kernel CPRNG.
    /// a privileged operation.  It will accept at most `ZX_CPRNG_ADD_ENTROPY_MAX_LEN`
    /// bytes of entropy at a time.
    ///
    /// ## Rights
    ///
    /// None.
    ///
    /// ## Return value
    ///
    /// `zx_cprng_add_entropy()` returns `ZX_OK` on success.
    ///
    /// ## Errors
    ///
    /// `ZX_ERR_INVALID_ARGS` *buffer_size* is too large, or *buffer* is not a valid
    /// userspace pointer.
    ///
    /// ## BUGS
    ///
    /// This syscall should be very privileged.
    ///
    /// ## See also
    ///
    ///  - [`zx_cprng_draw()`]
    ///
    /// [`zx_cprng_draw()`]: cprng_draw.md
    strict AddEntropy(struct {
        @voidptr
        buffer vector<byte>:CPRNG_ADD_ENTROPY_MAX_LEN;
    }) -> () error Status;
};