prng.h

Go to the documentation of this file.

// Copyright lowRISC contributors (OpenTitan project).
// Licensed under the Apache License, Version 2.0, see LICENSE for details.
// SPDX-License-Identifier: Apache-2.0
 
#ifndef OPENTITAN_SW_DEVICE_SCA_LIB_PRNG_H_
#define OPENTITAN_SW_DEVICE_SCA_LIB_PRNG_H_
 
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif  // __cplusplus
 
/**
 * @file
 * @brief PRNG for side-channel analysis.
 *
 * This library provides a Mersenne Twister PRNG that can be used to generate
 * random plaintexts on the device. Generating random plaintexts on the device
 * eliminates the overhead of sending them from the host and can significantly
 * improve capture rate. The host must use the same PRNG to be able to compute
 * the plaintext and the ciphertext of each trace.
 *
 * TODO(alphan): Replace this with a more efficient PRNG after updating
 * host-side code.
 */
 
/**
 * Initializes the random number generator.
 *
 * @param seed Seed to initalize with.
 */
void prng_seed(uint32_t seed);
 
/**
 * Generates a random uint32_t.
 *
 * The behavior of this function matches the behavior of `random.randint(0,
 * 0xFFFFFFFF)` in python.
 *
 * @return A random uint32_t.
 */
uint32_t prng_rand_uint32(void);
 
/**
 * Generates a random byte.
 *
 * The behavior of this function matches the behavior of `random.randint(0,
 * 255)` in python, which is used by ChipWhisperer's `ktp.next()`.
 *
 * @return A random byte.
 */
uint8_t prng_rand_byte(void);
 
/**
 * Fills a buffer with random bytes.
 *
 * The behavior of this function matches the behavior of `random.randint(0,
 * 255)` in python, which is used by ChipWhisperer's `ktp.next()`.
 *
 * @param[out] buffer     A buffer.
 * @param      buffer_len Size of the buffer.
 *
 * @return A random byte.
 */
void prng_rand_bytes(uint8_t *buffer, size_t buffer_len);
 
#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus
 
#endif  // OPENTITAN_SW_DEVICE_SCA_LIB_PRNG_H_