MdePkg/Include/Library/ArmTrngLib.h

   1 /** @file
   2   Arm TRNG interface library definitions (Cf. [1]).
   3
   4   Copyright (c) 2021 - 2022, Arm Limited. All rights reserved.<BR>
   5
   6   SPDX-License-Identifier: BSD-2-Clause-Patent
   7
   8   @par Reference(s):
   9   - [1] Arm True Random Number Generator Firmware, Interface 1.0,
  10         Platform Design Document.
  11         (https://developer.arm.com/documentation/den0098/latest/)
  12   - [2] NIST Special Publication 800-90B, Recommendation for the Entropy
  13         Sources Used for Random Bit Generation.
  14         (https://csrc.nist.gov/publications/detail/sp/800-90b/final)
  15
  16   @par Glossary:
  17     - TRNG - True Random Number Generator
  18 **/
  19
  20 #ifndef ARM_TRNG_LIB_H_
  21 #define ARM_TRNG_LIB_H_
  22
  23 /** Get the version of the Arm TRNG backend.
  24
  25   A TRNG may be implemented by the system firmware, in which case this
  26   function shall return the version of the Arm TRNG backend.
  27   The implementation must return NOT_SUPPORTED if a Back end is not present.
  28
  29   @param [out]  MajorRevision     Major revision.
  30   @param [out]  MinorRevision     Minor revision.
  31
  32   @retval  RETURN_SUCCESS            The function completed successfully.
  33   @retval  RETURN_INVALID_PARAMETER  Invalid parameter.
  34   @retval  RETURN_UNSUPPORTED        Backend not present.
  35 **/
  36 RETURN_STATUS
  37 EFIAPI
  38 GetArmTrngVersion (
  39   OUT UINT16  *MajorRevision,
  40   OUT UINT16  *MinorRevision
  41   );
  42
  43 /** Get the UUID of the Arm TRNG backend.
  44
  45   A TRNG may be implemented by the system firmware, in which case this
  46   function shall return the UUID of the TRNG backend.
  47   Returning the Arm TRNG UUID is optional and if not implemented,
  48   RETURN_UNSUPPORTED shall be returned.
  49
  50   Note: The caller must not rely on the returned UUID as a trustworthy Arm TRNG
  51         Back end identity
  52
  53   @param [out]  Guid              UUID of the Arm TRNG backend.
  54
  55   @retval  RETURN_SUCCESS            The function completed successfully.
  56   @retval  RETURN_INVALID_PARAMETER  Invalid parameter.
  57   @retval  RETURN_UNSUPPORTED        Function not implemented.
  58 **/
  59 RETURN_STATUS
  60 EFIAPI
  61 GetArmTrngUuid (
  62   OUT GUID  *Guid
  63   );
  64
  65 /** Returns maximum number of entropy bits that can be returned in a single
  66     call.
  67
  68   @return Returns the maximum number of Entropy bits that can be returned
  69           in a single call to GetArmTrngEntropy().
  70 **/
  71 UINTN
  72 EFIAPI
  73 GetArmTrngMaxSupportedEntropyBits (
  74   VOID
  75   );
  76
  77 /** Returns N bits of conditioned entropy.
  78
  79   See [2] Section 2.3.1 GetEntropy: An Interface to the Entropy Source
  80     GetEntropy
  81       Input:
  82         bits_of_entropy: the requested amount of entropy
  83       Output:
  84         entropy_bitstring: The string that provides the requested entropy.
  85       status: A Boolean value that is TRUE if the request has been satisfied,
  86               and is FALSE otherwise.
  87
  88   @param  [in]   EntropyBits  Number of entropy bits requested.
  89   @param  [in]   BufferSize   Size of the Buffer in bytes.
  90   @param  [out]  Buffer       Buffer to return the entropy bits.
  91
  92   @retval  RETURN_SUCCESS            The function completed successfully.
  93   @retval  RETURN_INVALID_PARAMETER  Invalid parameter.
  94   @retval  RETURN_UNSUPPORTED        Function not implemented.
  95   @retval  RETURN_BAD_BUFFER_SIZE    Buffer size is too small.
  96   @retval  RETURN_NOT_READY          No Entropy available.
  97 **/
  98 RETURN_STATUS
  99 EFIAPI
 100 GetArmTrngEntropy (
 101   IN  UINTN  EntropyBits,
 102   IN  UINTN  BufferSize,
 103   OUT UINT8  *Buffer
 104   );
 105
 106 #endif // ARM_TRNG_LIB_H_