packages/ti/drv/sciclient/docs/system-firmware-public-documentation/_sources/2_tisci_msgs/security/rng_api.rst.txt

   1 =============================
   2  Random Number Generator API
   3 =============================
   4
   5 .. _sec_api_rng_tisci_desc:
   6
   7 This chapter provides information on the available random number generator(RNG) API.
   8 Currently only one RNG API is supported.
   9
  10 +------------------+--------------------------------------------+
  11 | TISCI Message ID |                        Message Name        |
  12 +==================+============================================+
  13 | 0x9020           | :ref:`TISCI_MSG_GET_RANDOM <get-random>`   |
  14 +------------------+--------------------------------------------+
  15
  16 Introduction
  17 ============
  18
  19 Keystone 3 device Random Number Generator(RNG) module includes a
  20 Non-Deterministic Random Bit Generator (NRBG) coupled to a Deterministic Random
  21 bit Generator (DRBG). The RNG is SP 800-90A and FIPS 140-2 compliant.
  22
  23 |sysfw| initializes the RNG module during boot and provides a TISCI interface to
  24 retrieve random numbers. Random numbers are available in blocks of 4 x 32 bit
  25 words.
  26
  27 API Description
  28 ===============
  29
  30 .. _get-random:
  31
  32 TISCI_MSG_GET_RANDOM - Get Random Number
  33 ----------------------------------------
  34
  35 TISCI Message ID
  36 ----------------
  37
  38 .. sysfwapimacro:: TISCI_MSG_GET_RANDOM
  39
  40 .. sysfwapistruct:: tisci_rng_get_random_req
  41     :exclude-members: payload
  42
  43 .. sysfwapistruct:: tisci_rng_get_random_resp
  44
  45 .. note::
  46
  47    The user must always request 4 words or 8 words of
  48    random data. Other request lengths are not allowed.
  49
  50 The RNG internally has a 16 word random data buffer that is automatically
  51 refilled. If data is requested too quickly, this buffer might empty and the API
  52 might return with 0 length data. In such case, the user must wait before
  53 invoking the API once again.